1. 从一次“工具调用失败”说起Agent 的 skill 链路到底卡在哪很多人第一次写 Agent都会经历这样一个瞬间模型明明返回了tool_calls参数看着也对但本地执行完把结果塞回去模型却开始胡言乱语或者干脆重复调用同一个工具。问题往往不在模型而在链路中间——LLM 决策、Agent 执行、skill 说明书注入、结果回填这四步里任何一步的协议格式对不上整个 Agent Loop 就断了。这篇就聚焦 OpenAI 协议下Agent 从 LLM 决策到 skill/tools 执行的完整调用链路。所谓 skill本质上就是一份结构化的指令文件比如SKILL.md它不直接执行而是通过 tools 被 LLM “读进来”再指导 LLM 决定下一步调哪个工具。所以想搞懂 skill得先搞懂 tools 的协议流转。适合谁看已经能跑通单次 function calling但多工具串联时经常翻车的人想用统一 Key 管理多个模型通道、又不想在 Agent 框架里到处改 base_url 的人。下面我会用 TaoToken 作为统一 API 通道把 config.toml 和 settings.json 的配置骨架给出来再走一遍完整的 skill 调用链路最后给出预期返回结构和常见报错排查。2. TaoToken 前置统一 Key 与 API 通道准备在拆链路之前先把通道打通。Agent 框架通常要配置三样东西base_url、api_key、model。如果你同时用多个模型供应商最烦的就是每个框架、每个工具都要改一遍地址和 Key。TaoToken 的作用就是把这些收敛成一个统一入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。注意OpenAI 协议下很多客户端要求 base_url 以/v1结尾所以实际填的时候通常是https://taotoken.net/api/v1具体以你所用框架的文档为准。Key 的获取在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后先别急着写 Agent用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复 ok}] }返回里能看到choices[0].message.content就说明通道没问题。这一步很关键因为后面 Agent 报错时你要能区分是“通道不通”还是“协议写错”。如果你更想先在网页里试模型可以直接用模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。注意不要把 Key 硬编码进 Agent 的源码里。用环境变量或本地配置文件后面 config.toml 和 settings.json 都会体现这一点。3. 可复制配置config.toml 与 settings.json 骨架不同 Agent 框架的配置文件格式不一样但核心字段就那几个。下面给两份骨架你可以按自己用的框架微调。先看config.toml适合 Rust 系或支持 TOML 的 Agent 框架[llm] provider openai base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout_seconds 60 max_retries 2 [agent] max_iterations 8 tool_choice auto parallel_tool_calls false [skills] enabled [mp-read, file-summary] skill_dir ./skills inject_mode system_prompt再看settings.json适合 Node/Python 系框架{ llm: { baseUrl: https://taotoken.net/api/v1, apiKeyEnv: TAOTOKEN_API_KEY, model: gpt-4o-mini, temperature: 0.2 }, agent: { maxIterations: 8, toolChoice: auto }, skills: { dir: ./skills, inject: system, list: [mp-read, file-summary] }, tools: [ { type: function, function: { name: Read, description: 读取本地文件内容, parameters: { type: object, properties: { path: { type: string } }, required: [path] } } }, { type: function, function: { name: Shell, description: 执行 Shell 命令, parameters: { type: object, properties: { command: { type: string } }, required: [command] } } } ] }两个配置里最关键的是base_url指向 TaoToken 的/api/v1以及api_key_env指向环境变量。这样你在本地、CI、容器里切换环境时只改环境变量不动代码。max_iterations是 Agent Loop 的保险丝防止模型陷入无限工具调用。4. 拆解 skill 调用链路从 LLM 决策到 tools 执行现在进入正题。整个链路是一个典型的 Agent Loop思考 → 行动 → 观察循环直到finish_reason变成stop。第一步用户发起请求Agent 把 skill 清单注入 system prompt。注意 skill 的描述要短只写触发条件不写完整步骤完整步骤放在 skill 文件里等 LLM 主动来读。请求体大致是这样{ model: gpt-4o-mini, messages: [ { role: system, content: 你是一个AI助手。可用技能(Skills)\navailable_skills\nskill name\mp-read\当用户需要阅读、提取或总结公众号文章或出现 mp.weixin.qq 链接时使用。/skill\n/available_skills }, { role: user, content: 帮我总结一下这篇公众号文章https://mp.weixin.qq.com/s/xxxx } ], tools: [ { type: function, function: { name: Read, description: 读取本地文件内容, parameters: { type: object, properties: { path: { type: string } }, required: [path] } } }, { type: function, function: { name: Shell, description: 执行Shell命令, parameters: { type: object, properties: { command: { type: string } }, required: [command] } } } ], tool_choice: auto }第二步LLM 返回finish_reason: tool_calls表示它要先读 skill 详情。这里它选择用Read去读本地 skill 文件{ choices: [{ finish_reason: tool_calls, message: { role: assistant, content: null, tool_calls: [{ id: call_abc123, type: function, function: { name: Read, arguments: {\path\: \./skills/mp-read/SKILL.md\} } }] } }] }第三步Agent 执行Read把 skill 文件内容作为role: tool的消息拼回请求。注意tool_call_id必须和上一步的id严格对应这是最常见的错位点{ role: tool, tool_call_id: call_abc123, content: # Skill: mp-read\n## 触发条件\n用户提供公众号链接时触发。\n## 执行步骤\n1. 使用 Shell 执行 node fetch_mp.js URL 获取正文。\n2. 阅读返回文本输出 200 字以内摘要。 }第四步再次请求 LLM。这次 LLM 读到了 skill 详情知道下一步该调Shell抓正文{ choices: [{ finish_reason: tool_calls, message: { role: assistant, content: null, tool_calls: [{ id: call_def456, type: function, function: { name: Shell, arguments: {\command\: \node fetch_mp.js https://mp.weixin.qq.com/s/xxxx\} } }] } }] }第五步Agent 执行 Shell把抓到的正文作为 tool 结果回填{ role: tool, tool_call_id: call_def456, content: 文章标题AI Agent 的未来\n文章内容本文将探讨...(省略) }第六步LLM 拿到正文finish_reason变成stop输出最终摘要。到这里一次 skill 调用链路才算闭环。你会发现skill 本身从不执行它只是被 LLM 读进来当“操作手册”真正干活的是 tools。5. 验证请求与预期返回结构链路跑通后你需要一个可复现的验证动作。建议写一个最小脚本把上面六步串起来重点观察三个字段finish_reason、tool_calls[].id、tool_call_id。预期返回结构可以归纳成一张表阶段finish_reason关键字段说明读 skilltool_callstool_calls[0].function.name ReadLLM 主动读说明书抓正文tool_callstool_calls[0].function.name Shell按 skill 步骤执行出摘要stopmessage.content 非空链路结束验证时把每次请求的 messages 数组打印出来确认 assistant 的 tool_calls 和 tool 的 tool_call_id 一一对应。如果finish_reason一直是tool_calls不收敛多半是 skill 描述太模糊或者max_iterations设太大导致模型反复读文件。如果你在验证模型本身的行为比如换个模型看它是否更愿意按 skill 步骤走可以直接在模型对话页对比https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码类 Agent、需要稳定通道的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。6. 本篇常见错排查报错一tool_call_id不匹配。现象是模型返回 400提示 tool 消息找不到对应的 call。原因是回填时用了新的 id或者漏了某次 tool_calls。排查方法把 messages 按顺序打印逐个核对 id。报错二模型不调用工具直接回答。现象是finish_reason直接是stop。通常是tool_choice设成了none或者 skill 描述里没写清触发条件。把tool_choice改回auto并在 skill 描述里明确“出现某链接时使用”。报错三base_url 少了/v1。现象是 404 或 401。OpenAI 协议客户端大多要求https://taotoken.net/api/v1只写/api会拼错路径。接入文档里有各框架的填写示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。报错四Key 读不到。现象是 401。检查环境变量名是否和配置里的api_key_env一致容器里是否真的注入了。别把 Key 写进settings.json提交到仓库。报错五Agent Loop 不收敛。现象是反复调用同一个工具。把max_iterations降到 5 左右同时在 skill 里写清“执行一次即可不要重复读取”。最后补一句实操经验skill 文件别写太长LLM 读进来会占上下文把“触发条件”和“执行步骤”分开写模型判断是否触发时只看前者效率更高。链路调通后你可以把Read换成任意自定义工具skill 的玩法就打开了。 结合 OpenAI 协议，用 TaoToken 统一 Key 拆解 Agent 的 skill 调用链路
1. 从一次“工具调用失败”说起Agent 的 skill 链路到底卡在哪很多人第一次写 Agent都会经历这样一个瞬间模型明明返回了tool_calls参数看着也对但本地执行完把结果塞回去模型却开始胡言乱语或者干脆重复调用同一个工具。问题往往不在模型而在链路中间——LLM 决策、Agent 执行、skill 说明书注入、结果回填这四步里任何一步的协议格式对不上整个 Agent Loop 就断了。这篇就聚焦 OpenAI 协议下Agent 从 LLM 决策到 skill/tools 执行的完整调用链路。所谓 skill本质上就是一份结构化的指令文件比如SKILL.md它不直接执行而是通过 tools 被 LLM “读进来”再指导 LLM 决定下一步调哪个工具。所以想搞懂 skill得先搞懂 tools 的协议流转。适合谁看已经能跑通单次 function calling但多工具串联时经常翻车的人想用统一 Key 管理多个模型通道、又不想在 Agent 框架里到处改 base_url 的人。下面我会用 TaoToken 作为统一 API 通道把 config.toml 和 settings.json 的配置骨架给出来再走一遍完整的 skill 调用链路最后给出预期返回结构和常见报错排查。2. TaoToken 前置统一 Key 与 API 通道准备在拆链路之前先把通道打通。Agent 框架通常要配置三样东西base_url、api_key、model。如果你同时用多个模型供应商最烦的就是每个框架、每个工具都要改一遍地址和 Key。TaoToken 的作用就是把这些收敛成一个统一入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。注意OpenAI 协议下很多客户端要求 base_url 以/v1结尾所以实际填的时候通常是https://taotoken.net/api/v1具体以你所用框架的文档为准。Key 的获取在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后先别急着写 Agent用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复 ok}] }返回里能看到choices[0].message.content就说明通道没问题。这一步很关键因为后面 Agent 报错时你要能区分是“通道不通”还是“协议写错”。如果你更想先在网页里试模型可以直接用模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。注意不要把 Key 硬编码进 Agent 的源码里。用环境变量或本地配置文件后面 config.toml 和 settings.json 都会体现这一点。3. 可复制配置config.toml 与 settings.json 骨架不同 Agent 框架的配置文件格式不一样但核心字段就那几个。下面给两份骨架你可以按自己用的框架微调。先看config.toml适合 Rust 系或支持 TOML 的 Agent 框架[llm] provider openai base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout_seconds 60 max_retries 2 [agent] max_iterations 8 tool_choice auto parallel_tool_calls false [skills] enabled [mp-read, file-summary] skill_dir ./skills inject_mode system_prompt再看settings.json适合 Node/Python 系框架{ llm: { baseUrl: https://taotoken.net/api/v1, apiKeyEnv: TAOTOKEN_API_KEY, model: gpt-4o-mini, temperature: 0.2 }, agent: { maxIterations: 8, toolChoice: auto }, skills: { dir: ./skills, inject: system, list: [mp-read, file-summary] }, tools: [ { type: function, function: { name: Read, description: 读取本地文件内容, parameters: { type: object, properties: { path: { type: string } }, required: [path] } } }, { type: function, function: { name: Shell, description: 执行 Shell 命令, parameters: { type: object, properties: { command: { type: string } }, required: [command] } } } ] }两个配置里最关键的是base_url指向 TaoToken 的/api/v1以及api_key_env指向环境变量。这样你在本地、CI、容器里切换环境时只改环境变量不动代码。max_iterations是 Agent Loop 的保险丝防止模型陷入无限工具调用。4. 拆解 skill 调用链路从 LLM 决策到 tools 执行现在进入正题。整个链路是一个典型的 Agent Loop思考 → 行动 → 观察循环直到finish_reason变成stop。第一步用户发起请求Agent 把 skill 清单注入 system prompt。注意 skill 的描述要短只写触发条件不写完整步骤完整步骤放在 skill 文件里等 LLM 主动来读。请求体大致是这样{ model: gpt-4o-mini, messages: [ { role: system, content: 你是一个AI助手。可用技能(Skills)\navailable_skills\nskill name\mp-read\当用户需要阅读、提取或总结公众号文章或出现 mp.weixin.qq 链接时使用。/skill\n/available_skills }, { role: user, content: 帮我总结一下这篇公众号文章https://mp.weixin.qq.com/s/xxxx } ], tools: [ { type: function, function: { name: Read, description: 读取本地文件内容, parameters: { type: object, properties: { path: { type: string } }, required: [path] } } }, { type: function, function: { name: Shell, description: 执行Shell命令, parameters: { type: object, properties: { command: { type: string } }, required: [command] } } } ], tool_choice: auto }第二步LLM 返回finish_reason: tool_calls表示它要先读 skill 详情。这里它选择用Read去读本地 skill 文件{ choices: [{ finish_reason: tool_calls, message: { role: assistant, content: null, tool_calls: [{ id: call_abc123, type: function, function: { name: Read, arguments: {\path\: \./skills/mp-read/SKILL.md\} } }] } }] }第三步Agent 执行Read把 skill 文件内容作为role: tool的消息拼回请求。注意tool_call_id必须和上一步的id严格对应这是最常见的错位点{ role: tool, tool_call_id: call_abc123, content: # Skill: mp-read\n## 触发条件\n用户提供公众号链接时触发。\n## 执行步骤\n1. 使用 Shell 执行 node fetch_mp.js URL 获取正文。\n2. 阅读返回文本输出 200 字以内摘要。 }第四步再次请求 LLM。这次 LLM 读到了 skill 详情知道下一步该调Shell抓正文{ choices: [{ finish_reason: tool_calls, message: { role: assistant, content: null, tool_calls: [{ id: call_def456, type: function, function: { name: Shell, arguments: {\command\: \node fetch_mp.js https://mp.weixin.qq.com/s/xxxx\} } }] } }] }第五步Agent 执行 Shell把抓到的正文作为 tool 结果回填{ role: tool, tool_call_id: call_def456, content: 文章标题AI Agent 的未来\n文章内容本文将探讨...(省略) }第六步LLM 拿到正文finish_reason变成stop输出最终摘要。到这里一次 skill 调用链路才算闭环。你会发现skill 本身从不执行它只是被 LLM 读进来当“操作手册”真正干活的是 tools。5. 验证请求与预期返回结构链路跑通后你需要一个可复现的验证动作。建议写一个最小脚本把上面六步串起来重点观察三个字段finish_reason、tool_calls[].id、tool_call_id。预期返回结构可以归纳成一张表阶段finish_reason关键字段说明读 skilltool_callstool_calls[0].function.name ReadLLM 主动读说明书抓正文tool_callstool_calls[0].function.name Shell按 skill 步骤执行出摘要stopmessage.content 非空链路结束验证时把每次请求的 messages 数组打印出来确认 assistant 的 tool_calls 和 tool 的 tool_call_id 一一对应。如果finish_reason一直是tool_calls不收敛多半是 skill 描述太模糊或者max_iterations设太大导致模型反复读文件。如果你在验证模型本身的行为比如换个模型看它是否更愿意按 skill 步骤走可以直接在模型对话页对比https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码类 Agent、需要稳定通道的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。6. 本篇常见错排查报错一tool_call_id不匹配。现象是模型返回 400提示 tool 消息找不到对应的 call。原因是回填时用了新的 id或者漏了某次 tool_calls。排查方法把 messages 按顺序打印逐个核对 id。报错二模型不调用工具直接回答。现象是finish_reason直接是stop。通常是tool_choice设成了none或者 skill 描述里没写清触发条件。把tool_choice改回auto并在 skill 描述里明确“出现某链接时使用”。报错三base_url 少了/v1。现象是 404 或 401。OpenAI 协议客户端大多要求https://taotoken.net/api/v1只写/api会拼错路径。接入文档里有各框架的填写示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。报错四Key 读不到。现象是 401。检查环境变量名是否和配置里的api_key_env一致容器里是否真的注入了。别把 Key 写进settings.json提交到仓库。报错五Agent Loop 不收敛。现象是反复调用同一个工具。把max_iterations降到 5 左右同时在 skill 里写清“执行一次即可不要重复读取”。最后补一句实操经验skill 文件别写太长LLM 读进来会占上下文把“触发条件”和“执行步骤”分开写模型判断是否触发时只看前者效率更高。链路调通后你可以把Read换成任意自定义工具skill 的玩法就打开了。