1. 从一次“工具调用失败”说起Agent 开发的核心链路到底长什么样很多人第一次写 Agent代码跑起来之后会遇到一个很典型的现象模型明明“知道”该调用哪个工具参数也拼得像模像样但执行结果回传之后模型却像没看见一样继续重复调用同一个工具或者干脆开始胡编答案。这不是模型笨而是整条链路里某个节点断了。Agent 开发的核心链路说白了就四段任务解析、工具调用、结果回传、状态更新。任务解析负责把用户那句“帮我查一下上海明天适不适合跑步”拆成可执行意图工具调用负责把意图映射成具体的函数名和参数结果回传负责把工具返回的 JSON 塞回上下文状态更新负责决定下一步是继续调工具还是直接回答。这四段里任何一段的格式、顺序、字段名对不上链路就会断。我试过用最朴素的方式手写一个最小 Agent不依赖任何重型框架只靠一份 settings.json 和一个循环就能把这条链路跑通。下面这份配置骨架和验证动作适合想系统理解 Agent 工程结构、又不想一上来就被框架抽象淹没的开发者。你不需要先成为提示词大师也不需要先搭好向量数据库先把“解析—调用—回传”这条最小闭环跑起来后面加记忆、加规划、加多 Agent 才有落脚点。2. 前置准备用 TaoToken 把模型入口和工具入口分开管在跑通链路之前先把两个入口理清楚一个是模型入口一个是工具入口。模型入口负责“理解”和“决策”工具入口负责“执行”。很多初学者把这两件事混在一个脚本里结果调试时根本分不清是模型没理解对还是工具没执行对。模型入口这边我习惯用 TaoToken 来做统一接入。它的 API 地址是https://taotoken.net/api兼容常见的对话补全格式换模型只需要改一个 model 字段不用重写调用逻辑。对于 Agent 开发来说这一点很关键任务解析阶段可能用便宜的小模型工具调用决策阶段可能用推理更强的模型结果回传后的总结阶段又可能换回小模型。入口统一之后链路里的模型切换就不会牵动工具层。工具入口这边最小 Agent 不需要 MCP也不需要复杂的函数注册中心。你只需要一个本地函数表把工具名映射到实际的可执行函数再让模型输出的 JSON 去查这张表。这样做的好处是链路透明模型输出了什么、查到了哪个函数、传了什么参数、返回了什么每一步都能打印出来。如果你还没有 API Key可以去 TaoToken 的 API Keys 页面创建一个地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys。创建之后先别急着写复杂逻辑用模型对话页面发一条最简单的消息确认 Key 能用、网络能通再进入下一步。模型对话入口在https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat适合用来快速验证模型是否正常响应。3. 可复制的 settings.json 配置骨架下面这份 settings.json 是我在本地跑最小 Agent 时用的骨架。它不绑定任何特定框架你可以把它读进 Python 脚本也可以读进 Node 脚本。核心字段分三块model 块管模型入口tools 块管工具定义loop 块管链路行为。{ model: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet-4-20250514, planner_model: claude-sonnet-4-20250514, summarizer_model: claude-sonnet-4-20250514, temperature: 0.2, max_tokens: 2048 }, tools: [ { name: get_weather, description: 查询指定城市指定日期的天气情况返回温度和降水概率, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如 上海 }, date: { type: string, description: 日期格式 YYYY-MM-DD } }, required: [city, date] } }, { name: calculate, description: 执行基础数学计算支持加减乘除和幂运算, parameters: { type: object, properties: { expression: { type: string, description: 数学表达式例如 (128)*3 } }, required: [expression] } } ], loop: { max_steps: 6, stop_on_final_answer: true, echo_tool_result: true, tool_timeout_seconds: 10 } }这份配置里model.base_url指向 TaoToken 的 API 入口api_key_env表示从环境变量读取 Key避免把密钥写进文件。tools数组里每个工具都有 name、description 和 parameters这三样正好对应模型做工具调用决策时需要的全部信息。loop块里的max_steps是防止链路死循环的保险丝echo_tool_result打开之后每次工具返回都会打印到控制台方便你肉眼追踪结果回传节点。注意parameters里的required字段。很多工具调用失败不是因为模型不会调而是因为模型不知道哪些参数是必填的。把 required 写清楚模型输出的 JSON 参数完整度会明显提升。另外description 不要写得太抽象写“查询指定城市指定日期的天气情况”比写“天气工具”有效得多因为模型是靠这段文字来判断该不该调用这个工具的。4. 一次链路验证从任务解析到结果回传的完整动作配置写好后下一步是写一个最小循环来验证链路。下面这段 Python 代码不依赖任何 Agent 框架只用标准库和 requests把任务解析、工具调用、结果回传三个节点串起来。你可以直接复制到本地运行只需要先设置环境变量TAOTOKEN_API_KEY。import json import os import re import requests with open(settings.json, r, encodingutf-8) as f: cfg json.load(f) API_KEY os.environ[cfg[model][api_key_env]] BASE_URL cfg[model][base_url].rstrip(/) MODEL cfg[model][default_model] def call_llm(messages, toolsNone): payload { model: MODEL, messages: messages, temperature: cfg[model][temperature], max_tokens: cfg[model][max_tokens] } if tools: payload[tools] tools resp requests.post( f{BASE_URL}/v1/chat/completions, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json }, jsonpayload, timeout60 ) resp.raise_for_status() return resp.json() def build_tool_schema(tools): return [ { type: function, function: { name: t[name], description: t[description], parameters: t[parameters] } } for t in tools ] def execute_tool(name, args): if name get_weather: return {city: args[city], date: args[date], temp: 26, rain_prob: 0.2} if name calculate: return {expression: args[expression], result: eval(args[expression])} return {error: funknown tool: {name}} def run_agent(user_input): messages [ {role: system, content: 你是一个会调用工具的助手。需要外部信息时调用工具拿到结果后直接回答用户。}, {role: user, content: user_input} ] tool_schema build_tool_schema(cfg[tools]) for step in range(cfg[loop][max_steps]): data call_llm(messages, tool_schema) msg data[choices][0][message] messages.append(msg) tool_calls msg.get(tool_calls) if not tool_calls: print(最终回答:, msg.get(content)) return msg.get(content) for tc in tool_calls: fn_name tc[function][name] fn_args json.loads(tc[function][arguments]) print(f[step {step}] 调用工具: {fn_name} 参数: {fn_args}) result execute_tool(fn_name, fn_args) print(f[step {step}] 工具返回: {result}) messages.append({ role: tool, tool_call_id: tc[id], content: json.dumps(result, ensure_asciiFalse) }) print(达到最大步数链路终止) return None if __name__ __main__: run_agent(上海明天适合跑步吗明天是2025-06-15)这段代码里任务解析节点体现在模型第一次返回的tool_calls字段工具调用节点体现在execute_tool函数结果回传节点体现在把工具返回值以role: tool的消息追加回messages。运行之后你应该能看到类似这样的输出[step 0] 调用工具: get_weather 参数: {city: 上海, date: 2025-06-15} [step 0] 工具返回: {city: 上海, date: 2025-06-15, temp: 26, rain_prob: 0.2} 最终回答: 上海明天温度约26度降水概率20%适合跑步建议傍晚出门。如果你看到工具被调用、结果被回传、模型基于结果给出了自然语言回答说明最小 Agent 链路已经跑通。接下来你可以把execute_tool里的假数据换成真实 API或者把get_weather换成你自己的业务函数链路结构不需要改。5. 本篇常见错排查链路断在哪一步链路跑不通的时候不要急着换模型先按节点排查。下面这几个错误是我在本地验证时踩过的坑按出现频率排序。第一个高频错误是工具调用返回空。模型没有输出tool_calls而是直接给了一段文字回答。这通常是因为工具描述写得太模糊或者系统提示词里没有明确要求“需要外部信息时调用工具”。解决办法是把工具 description 写具体并在 system 消息里加一句“涉及实时数据时必须调用工具不要凭记忆回答”。第二个错误是参数解析失败。模型输出的arguments不是合法 JSON比如用了单引号或者多了注释。这通常发生在模型对参数格式理解不稳定的时候。你可以在 system 消息里加一句“工具参数必须是合法 JSON字符串用双引号”或者在代码里加一层容错解析把常见格式问题修掉再json.loads。第三个错误是结果回传后模型不采纳。工具明明返回了temp: 26模型却回答“我无法获取天气”。这多半是因为回传消息的tool_call_id和模型输出的id对不上或者role写成了function而不是tool。检查你的回传消息结构确保tool_call_id与上一条 assistant 消息里的tool_calls[].id完全一致。第四个错误是链路死循环。模型反复调用同一个工具max_steps用完了还在调。这通常是因为工具返回的结果里缺少模型需要的字段模型以为没拿到数据就再调一次。你可以在工具返回里加一个明确的status: success字段或者在 system 消息里说明“如果工具返回中已包含所需信息直接回答不要重复调用”。第五个错误是超时。工具执行时间过长或者模型响应慢导致整个链路卡住。settings.json里的tool_timeout_seconds就是为这个准备的给每个工具调用加超时超时后把错误信息回传给模型让模型决定是重试还是换工具。如果你在排查过程中发现是模型接入层的问题比如请求格式不对、模型名写错、Key 无效可以去接入文档页面核对参数地址是https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc。文档里对请求体字段和返回结构有完整说明比在代码里猜要快得多。6. 链路跑通之后下一步该往哪里走最小链路跑通之后你会很自然地想加东西加记忆、加规划、加多轮工具调用、加错误恢复。这时候不要一上来就引入重型框架先把当前链路的每个节点抽象成可替换的模块。任务解析节点可以换成更强的规划模型工具调用节点可以换成 MCP 协议结果回传节点可以加摘要压缩状态更新节点可以加短期记忆。如果你打算长期做 Agent 开发尤其是需要反复调试工具调用和上下文管理的场景可以了解一下 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan。它适合需要稳定模型入口、又不想在多个模型之间反复切换配置的开发者。控制台入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole可以用来查看调用记录和用量方便定位链路里哪个节点消耗最大。最后说一个实用技巧在链路验证阶段把每次模型请求和工具返回都写进本地日志文件按trace_id串联。这样当链路断掉的时候你能一眼看出是任务解析没解析对还是工具调用参数错了还是结果回传格式不对。这个习惯比任何调试工具都管用因为 Agent 的问题往往不在单点而在节点之间的衔接。
