1. 先搞清楚LLM Agents 到底难在哪为什么新手第一个 Agent 总是跑不起来很多人第一次接触 LLM Agents脑子里想的是一句话让模型自己思考、自己调工具、自己记住上下文然后帮我把活干完。听起来很爽但真正动手写代码时卡点往往不在“模型聪不聪明”而在三个非常具体的地方模型记不住上一轮干了什么、工具注册了却调不动、任务一复杂就不知道下一步该干嘛。这三个问题分别对应 Agents 的三大核心组件——记忆、工具、规划。你把这三点拆开理解再串成一个闭环第一个可观测的 Agent 才算真正跑通。先说记忆。LLM 本身是无状态的你发一次请求它答一次请求结束它就把刚才聊的内容忘干净了。所谓“短期记忆”本质是把历史对话塞进上下文窗口靠 token 数量硬撑窗口一满要么截断要么摘要。所谓“长期记忆”是把历史交互、行动记录写进外部存储向量库、KV、甚至一个 JSON 文件需要时再检索回来拼进 prompt。新手最容易犯的错是把“记忆”理解成模型自带的能力结果多轮对话一跑就露馅。再说工具。工具就是让模型能“动手”的接口比如查天气、读数据库、跑一段计算。模型不会真的执行函数它只会生成一段符合你约定格式的文本通常是 JSON你的代码解析这段文本、真正调用函数、再把结果塞回对话。所以工具调不动的根因九成是“格式没对齐”或“schema 描述不清”而不是模型笨。最后说规划。规划是模型把“帮我分析这份销售数据并出个报告”拆成“读文件→清洗→统计→写结论”的能力。它依赖模型的推理行为常见做法是 ReAct 式的“思考—行动—观察”循环。规划做不好Agent 就会在原地打转或者一步跳太远直接跑偏。这三个组件单独看都不难难在它们要串成一个闭环而且这个闭环里每一次模型调用都要稳定、可观测、可复现。这就引出一个很现实的问题你本地跑 demo 时用一个 Key 调一个模型没问题但一旦要接多个 Agent 框架、换不同模型做对比、或者让规划器和执行器用不同模型Key 管理和通道稳定性立刻变成绊脚石。我试过在几个框架之间来回切模型每次改 base_url 和 key 都要翻半天配置后来统一走 TaoToken 的 API 通道把模型调用收敛到一个入口调试效率高不少。下面就从环境准备开始一步步把闭环搭起来。2. 前置准备用 TaoToken 统一 Key 串起多 Agent 框架的模型调用在写任何 Agent 代码之前先把“模型调用”这一层理顺。原因很简单记忆、工具、规划三大组件里每一个环节都要调模型——规划器要调、工具选择要调、记忆摘要也要调。如果每个环节你都单独配一套 Key 和 base_url代码会迅速变成一团乱麻排障时根本分不清是逻辑问题还是通道问题。TaoToken 在这里扮演的角色是一个统一的模型调用入口。你只需要在它那里拿到一个 API Key把 base_url 指向https://taotoken.net/api然后在代码里通过 model 参数切换不同模型。这样你的 Agent 框架代码里只维护一份凭证规划用哪个模型、执行用哪个模型全靠参数控制不用改环境变量。对新手来说这能省掉大量“为什么这个框架连不上、那个框架报 401”的无效折腾。具体操作分三步。第一步打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册并登录进入控制台。第二步在控制台里找到 API Keys 页面deep linkhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys创建一个新的 Key复制保存好——它只显示一次。第三步确认你要用的模型 ID可以在模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chat先手动聊两句确认通道正常、模型可用再写进代码。这里有个细节值得强调不同 Agent 框架对“模型标识”的写法不完全一样。有的框架要求openai/gpt-4o这种带前缀的格式有的只要gpt-4o。你拿到 Key 之后先用一个最小的 curl 请求验证通道确认返回结构再往框架里填。验证命令如下把YOUR_KEY换成你自己的curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复两个字收到}] }如果返回的 JSON 里choices[0].message.content是“收到”说明 Key 和通道都没问题。这一步看着简单但它把“模型调用”这个变量先固定住了后面记忆、工具、规划出问题时你可以放心地排除通道因素。另外提醒一句Key 不要硬编码进 Git 仓库用环境变量或.env文件管理这是基本习惯。对于需要长期跑 Agent、做多轮规划实验的场景如果你发现自己调用量上来了可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan它更适合持续性的编码和 Agent 任务比按次调用更省心。不过第一个闭环阶段用普通 API Key 完全够用先把逻辑跑通再说。3. 可复制配置记忆、工具、规划三大组件的落地代码片段这一节是全文的核心我按“记忆→工具→规划”的顺序给出可直接复制的配置和代码。所有模型调用统一走 TaoToken 的 base_url你只需要替换 Key 和模型 ID。代码用 Python依赖openai官方 SDKTaoToken 的 API 兼容 OpenAI 协议所以直接用这个 SDK 最省事。先装依赖并设置环境变量pip install openai export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api3.1 记忆组件短期用上下文长期用文件持久化短期记忆最直接的做法是维护一个messages列表每轮把用户输入和模型回复 append 进去。但列表会无限增长所以加一个简单的截断策略保留 system prompt 最近 N 轮。长期记忆我用一个 JSON 文件模拟把每轮的关键结论写进去下次启动时读回来拼进 system prompt。真实项目里你会换成向量库但文件版足够让你看清“记忆是怎么被检索和注入的”。import json, os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) MEMORY_FILE agent_memory.json def load_long_term_memory(): if os.path.exists(MEMORY_FILE): with open(MEMORY_FILE, r, encodingutf-8) as f: return json.load(f) return [] def save_long_term_memory(records): with open(MEMORY_FILE, w, encodingutf-8) as f: json.dump(records, f, ensure_asciiFalse, indent2) def build_messages(user_input, short_term, long_term): system 你是一个助手。以下是历史记忆供参考\n for r in long_term[-5:]: system f- {r}\n messages [{role: system, content: system}] messages.extend(short_term[-6:]) messages.append({role: user, content: user_input}) return messages这段代码的关键点在于长期记忆不是全量塞进去而是取最近 5 条避免 prompt 膨胀。你可以把long_term换成向量检索结果逻辑完全一样——检索出相关片段拼进 system prompt。3.2 工具组件用 JSON Schema 注册解析模型返回的调用意图工具注册的核心是给模型一份“工具说明书”也就是 JSON Schema。模型根据这份说明决定调不调、调哪个、传什么参数。下面注册一个计算器工具和一个查当前时间的工具然后演示如何解析模型的工具调用请求。import datetime TOOLS [ { type: function, function: { name: calculator, description: 执行简单的四则运算输入两个数字和运算符, parameters: { type: object, properties: { a: {type: number, description: 第一个数字}, b: {type: number, description: 第二个数字}, op: {type: string, enum: [, -, *, /]}, }, required: [a, b, op], }, }, }, { type: function, function: { name: get_current_time, description: 获取当前日期和时间, parameters: {type: object, properties: {}}, }, }, ] def execute_tool(name, args): if name calculator: a, b, op args[a], args[b], args[op] if op : return a b if op -: return a - b if op *: return a * b if op /: return a / b if name get_current_time: return datetime.datetime.now().isoformat() return 未知工具调用时把TOOLS传给client.chat.completions.create(toolsTOOLS)模型如果决定用工具返回的message.tool_calls里会有函数名和参数 JSON。你解析它、执行execute_tool、把结果以role: tool的消息塞回对话再请求一次模型它就会基于工具结果继续回答。这个“请求→工具调用→回填结果→再请求”的循环就是工具组件的完整闭环。3.3 规划组件ReAct 式循环让模型自己拆步骤规划我用最朴素的 ReAct 思路给模型一个系统提示要求它按“思考→行动→观察”的格式输出代码解析“行动”行决定是否调工具把“观察”结果回填循环直到模型给出最终答案。下面是一个可运行的最小实现REACT_PROMPT 你可以使用以下工具calculator, get_current_time。 请严格按以下格式回答 思考你的推理过程 行动工具名参数为JSON 观察工具返回结果由系统填写 ...可重复多轮 最终答案给用户的结论 def run_react_agent(user_input, max_steps5): history [{role: system, content: REACT_PROMPT}, {role: user, content: user_input}] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messageshistory, temperature0, ) content resp.choices[0].message.content history.append({role: assistant, content: content}) if 最终答案 in content: return content # 解析行动行简化版生产环境用正则更稳 for line in content.splitlines(): if line.startswith(行动): action line.replace(行动, ).strip() name, args_str action.split(, 1) args json.loads(args_str.replace(参数为, ).strip()) result execute_tool(name.strip(), args) history.append({role: user, content: f观察{result}}) break return 达到最大步数未得到最终答案这段代码把规划、工具、记忆串在了一起history是短期记忆execute_tool是工具执行循环本身是规划。你可以拿“3 乘以 7 等于多少再告诉我现在几点”去测观察它是否先调 calculator 再调 get_current_time。4. 验证请求与成功结果跑通第一个可观测的 Agent 闭环配置写完必须验证。验证的目标不是“能跑”而是“每一步都可观测”——你能看到模型想了什么、调了什么工具、工具返回了什么、最终答案怎么来的。下面给出完整的验证脚本和预期输出你照着跑一遍对照结果判断每个组件是否真的生效。先验证记忆组件。开两个终端会话第一个会话告诉 Agent 你的名字第二个会话问“我叫什么”。如果长期记忆文件生效第二个会话应该能答出来。验证代码如下# 会话1 short_term [] long_term load_long_term_memory() msgs build_messages(我叫小林记住这个名字, short_term, long_term) resp client.chat.completions.create(modelgpt-4o-mini, messagesmsgs) print(resp.choices[0].message.content) long_term.append(用户叫小林) save_long_term_memory(long_term) # 会话2新进程 long_term load_long_term_memory() msgs build_messages(我叫什么, [], long_term) resp client.chat.completions.create(modelgpt-4o-mini, messagesmsgs) print(resp.choices[0].message.content) # 预期包含“小林”预期结果会话 2 的输出里出现“小林”。如果没出现检查agent_memory.json是否真的写入了、build_messages是否把 long_term 拼进了 system prompt。再验证工具组件。直接发一个需要计算的问题打印tool_callsresp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 帮我算 128 乘以 64}], toolsTOOLS, ) print(resp.choices[0].message.tool_calls)预期结果tool_calls不为空function.name是calculatorarguments里是{a:128,b:64,op:*}。如果tool_calls是 None说明模型没决定用工具检查工具 description 是否清晰、问题是否足够明确。最后验证规划闭环。跑run_react_agent(3 乘以 7 等于多少再告诉我现在几点)预期输出里能看到至少两轮“思考/行动/观察”最终答案包含 21 和一个时间戳。如果它一步就给出答案却没调工具说明 ReAct prompt 没约束住把格式要求写得更强硬一些或者换一个指令遵循更强的模型。成功结果的判断标准我总结成一张表方便你对照组件验证动作成功标志失败常见表现记忆跨会话问名字答出“小林”答“不知道”或答错工具问乘法tool_calls 含 calculatortool_calls 为 None规划复合问题多轮思考行动观察直接给答案不调工具三个都通过你的第一个可观测 Agent 闭环就算跑通了。这时候你可以把print换成日志记录每一步的 token 消耗和耗时为后续优化做准备。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 逐个击破新手跑 Agent 时遇到的报错八成集中在下面几类。我把真实报错原文和排查路径列出来你对着改就行。401 Unauthorized / invalid_api_key。这是最常见的一类报错长这样Error code: 401 - {error: {message: Invalid API key}}。原因无非三个Key 复制时带了空格、Key 已失效或被删、环境变量没生效。排查顺序先echo $TAOTOKEN_API_KEY确认变量有值且无空格再用第 2 节的 curl 命令单独测 Key如果 curl 通但代码不通检查代码里是不是把 base_url 写成了别的地址。注意 base_url 必须是https://taotoken.net/api末尾不要多加/v1SDK 会自己拼。local proxy failed / connection refused。报错类似APIConnectionError: Connection error或local proxy failed。这类多半是本地网络环境或代理配置干扰了请求。排查先确认你能正常访问https://taotoken.net/api检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向一个已经关掉的本地端口有的话临时 unset 掉再试如果你在公司内网确认出口策略没有拦截。这类问题跟 Key 无关别急着换 Key。reading choices / undefined is not an object。报错长这样TypeError: Cannot read properties of undefined (reading choices)。这是代码在解析响应时resp本身是 undefined 或结构不对。根因通常是请求抛异常被吞了或者你用了流式返回却没按流式解析。排查把resp整个打印出来看结构确认没有开streamTrue却按非流式读choices确认 SDK 版本和 API 协议匹配。还有一种情况是模型 ID 写错服务端返回了错误结构你的代码却直接去读choices自然就 undefined。OAuth / token 过期类报错。如果你在 Claude Code 或某些 CLI 工具里看到 OAuth 相关报错通常是工具的登录态失效跟 API Key 是两套机制。这类工具要么走 OAuth 登录要么走 API Key别混用。如果你是用 API Key 接入确认工具配置里填的是 Base URL Key Model ID 三件套缺一不可。以 Claude Code 这类工具为例配置里要同时写清ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址、ANTHROPIC_API_KEY你的 Key、以及模型 ID三者对齐才能通。Cline 配 MCP 时同理MCP server 的启动参数里要把这三个值传全少一个就会在初始化阶段报错。工具调不动但没报错。这种最隐蔽模型返回了文本但tool_calls是空的。排查打印完整的message看模型到底说了什么检查tools参数是否真的传进去了有的框架要求tool_choiceauto检查工具 schema 的required字段是否和模型生成的参数对得上。实测下来description 写得太含糊是主因把“执行计算”改成“输入两个数字和运算符返回计算结果”命中率立刻上来。排障时有个通用心法先把变量收敛到最少。用 curl 验证通道用最小 Python 脚本验证 SDK再往框架里套。每加一层就测一次别一次性堆完再 debug。接入相关的完整文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc遇到协议细节可以去翻。6. 下一步怎么走从单 Agent 到多 Agent以及长期编码场景的通道选择单 Agent 闭环跑通之后你会自然想往前走一步多 Agent 协作。多 Agent 的本质是把“记忆、工具、规划”这三件套复制多份每个 Agent 有自己的工具集和记忆再由一个监督者做任务分发。你现在的代码已经具备所有零件——run_react_agent就是一个可复用的单 Agent把它包一层让监督者根据任务类型选择调用哪个 Agent多 Agent 的雏形就出来了。关键是把每个 Agent 的长期记忆文件分开存避免互相污染。再往后你会遇到“规划器和执行器用不同模型”的需求规划用推理强的模型执行用便宜快的模型。这时候统一 Key 的价值就体现出来了——你只需要在代码里传不同的 model 参数不用改任何凭证配置。如果你的 Agent 要长期跑、频繁调模型做规划和反思可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan它针对持续性编码和 Agent 任务做了优化比零散调用更划算。最后给一个实用建议从今天起给你的 Agent 加一行日志记录每次模型调用的输入摘要、输出摘要、token 数和耗时。这个习惯在你调规划逻辑时会救命——你会清楚地看到模型在哪一步开始跑偏而不是对着一个错误答案瞎猜。记忆、工具、规划这三大组件真正拉开差距的不是代码写得多花哨而是你对每一步的可观测程度。把闭环跑通、把日志打全、把报错对照表贴在显示器边上剩下的就是迭代。
