1. 从一次“工具调用失败”说起Agent 术语到底卡在哪很多人第一次写 AI Agent代码跑起来是这样的模型明明在回复里写了要调用get_weather可你的程序解析半天拿不到参数最后只能把整段文本丢给用户看。问题不在模型笨而在于你没分清 User Prompt、System Prompt、Function Calling、Agent Tool、MCP 协议这几层到底谁管什么。我先把结论摆出来User Prompt 是用户说的话System Prompt 是开发者给模型定的规矩Agent Tool 是真正干活的函数或服务Function Calling 是模型“申请调用工具”的标准格式MCP 协议则是 Agent 和工具服务之间的通信规范。这五个词经常被混着用但它们在调用链路上处于完全不同的位置。举个具体场景。你做一个“查天气并提醒带伞”的 Agent。用户输入“明天出门要带伞吗”是 User Prompt你告诉模型“你是天气助手只能调用已注册工具”是 System Promptget_weather(city, date)这个函数是 Agent Tool模型返回{name:get_weather,arguments:{city:杭州}}这种结构化 JSON 是 Function Calling而如果这个天气工具被部署成独立服务、通过统一协议被多个 Agent 复用那它就走上了 MCP 协议的路子。为什么现在要专门盘点这些术语因为 2024 年之后 Agent 开发从“手写 prompt 拼工具”进化到了“协议化、服务化”。早期 AutoGPT 那种把工具说明塞进 System Prompt、靠模型自由发挥返回格式的做法格式不稳定、重试成本高。Function Calling 把工具描述和返回格式标准化了MCP 又把工具本身服务化了。理解这条演进线你才知道自己该在哪一层写代码。这篇会沿着“术语定义 → 调用链路 → 统一接入 → 连通性验证 → 报错排查”的顺序走。接入示例我用 TaoToken 的统一 Key/API 通道因为它把多家模型的 Base URL 收敛成一个方便你在同一套 Agent 代码里切换模型做对比。下面每个术语我都会对应到可运行的配置或请求上不停留在概念。2. TaoToken 统一 Key/API 通道Agent 多模型接入的前置准备写 Agent 最烦的一件事是Function Calling 的请求格式各家不一样。OpenAI 用tools字段Claude 早期用tools但结构有差异Gemini 又是另一套。你如果每个模型都单独写适配层代码会迅速膨胀。TaoToken 的思路是提供一个统一的 API 通道Base URL 固定Key 固定模型 ID 通过参数切换这样你的 Agent 主逻辑只写一遍。先说清楚它是什么TaoToken 是一个大模型 API 聚合通道对外暴露兼容 OpenAI 风格的接口。你可以把它理解成“一个入口后面接多家模型”。对 Agent 开发来说最大的价值是 Function Calling 的工具描述 JSON 可以复用同一份切换模型时只改model字段。适合谁用三类人一是刚学 Agent、不想同时注册五家平台账号的二是已经在写 Function Calling、想快速对比不同模型工具调用准确率的三是做 MCP 工具服务、需要给 Agent 配一个稳定模型出口的。前置准备只有三样东西第一一个 API Key。去控制台创建地址是https://taotoken.net/console。创建后复制保存后面所有请求都用它。第二确认 Base URL。对话补全的统一入口是https://taotoken.net/api注意这个地址不带任何查询参数。如果你用的是 OpenAI SDK通常填到/v1这一级具体看你 SDK 版本下面配置片段里我会写清楚。第三选一个支持 Function Calling 的模型 ID。不是所有模型都支持工具调用选之前先在模型列表里确认。常见的支持工具调用的模型 ID 形如gpt-4o、claude-3-5-sonnet这类具体以你控制台里能看到的为准。这里有个容易踩的坑Base URL 和 API Key 要配套。有人把 Key 填对了Base URL 还留着官方地址结果 401。统一通道的意义就是两者必须一起换。你可以先只配一个模型跑通再扩展到多模型。另外提醒一句Agent 开发和普通对话不一样它对多轮工具调用的稳定性要求更高。普通聊天一次请求就结束Agent 可能一轮任务里连续调用三四个工具每次都要把历史消息和工具结果带回去。所以你的 Key 要有足够的调用额度别跑到一半限流了。准备好这三样下一节直接上可复制的配置。我会给 Python SDK、curl、以及一个 JSON 配置文件三种形式你按自己技术栈挑。3. 可复制配置Base URL、Key、Model ID 三件套怎么写这一节是全文最该收藏的部分。Agent 接入的配置核心就三件套Base URL API Key Model ID。我把它们放进不同格式里你直接改 Key 就能用。先看 Python 用 OpenAI SDK 的写法。这是最常见的 Agent 开发方式因为 Function Calling 的tools参数在 OpenAI SDK 里支持得最完整from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api/v1, api_keysk-你的TaoToken密钥 ) response client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 你是一个会调用工具的助手。}, {role: user, content: 杭州明天天气怎么样} ], tools[ { type: function, function: { name: get_weather, description: 查询指定城市指定日期的天气, parameters: { type: object, properties: { city: {type: string, description: 城市名}, date: {type: string, description: 日期格式 YYYY-MM-DD} }, required: [city, date] } } } ], tool_choiceauto ) print(response.choices[0].message)注意base_url我写的是https://taotoken.net/api/v1。不同 SDK 版本对/v1的处理不一样有的 SDK 会自动补有的不会。如果你请求报 404先把/v1去掉或加上试一次这是最常见的路径问题。再看 curl 版本方便你在终端快速验证不依赖任何 SDKcurl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-4o, messages: [ {role: user, content: 你好测试连通性} ] }如果你用配置文件管理比如给 Cline、Codex 这类工具用可以写成 JSON。这里以auth.json风格的配置为例三件套齐全{ base_url: https://taotoken.net/api/v1, api_key: sk-你的TaoToken密钥, model: gpt-4o, provider: openai-compatible }如果你用的是 Claude Code 这类工具配置通常放在settings.json里字段名可能是env下的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这里要特别注意Claude Code 走的是 Anthropic 风格接口Base URL 和 OpenAI 风格不完全一样具体路径以接入文档为准别直接把 OpenAI 的/v1/chat/completions套上去。关于 Model ID我再强调一次它必须和你的请求格式匹配。你填了一个只支持文本补全、不支持 Function Calling 的模型然后传了tools参数有的通道会直接报错有的会静默忽略工具。所以选模型前先确认它支持工具调用。配置写完后别急着写复杂 Agent。先用一个最简单的“无工具”请求验证通道通不通通了再加tools。这样出问题时你能快速定位是通道问题还是工具格式问题。下一节就讲怎么验证。4. 验证请求与成功结果从连通性到 Function Calling 返回配置写完第一件事是验证。我把它分成两步先验证基础连通性再验证 Function Calling 是否真的返回结构化工具调用。第一步基础连通性。用上一节的 curl把messages换成最简单的“你好”。如果返回类似下面的结构说明 Base URL 和 Key 都对{ id: chatcmpl-xxx, object: chat.completion, choices: [ { index: 0, message: { role: assistant, content: 你好有什么可以帮你的吗 }, finish_reason: stop } ] }看到choices[0].message.content有内容第一步就过了。如果这里就报 401别往下走先解决 Key 问题。第二步验证 Function Calling。把带tools的请求发出去重点看返回里的finish_reason和message.tool_calls。一个成功的工具调用返回长这样{ choices: [ { index: 0, message: { role: assistant, content: null, tool_calls: [ { id: call_abc123, type: function, function: { name: get_weather, arguments: {\city\:\杭州\,\date\:\2025-01-20\} } } ] }, finish_reason: tool_calls } ] }关键点有三个finish_reason是tool_calls而不是stopmessage.content可能是nulltool_calls[0].function.arguments是一个 JSON 字符串你需要json.loads解析它。很多人第一次拿到arguments直接当字典用结果报类型错误就是漏了解析这一步。拿到工具调用后你的 Agent 要做的是执行本地函数get_weather(杭州, 2025-01-20)把结果作为一条role: tool的消息追加到messages里再发一次请求。第二次请求模型会基于工具结果生成自然语言回答。这就是完整的 Function Calling 闭环。如果你用的是 MCP 协议验证方式略有不同。MCP Server 启动后Agent 作为 MCP Client 要先发一个“列出可用工具”的请求拿到工具清单再决定调用哪个。MCP 的通信可以是标准输入输出也可以是 HTTP。验证 MCP Server 是否正常最直接的方法是看它能否响应工具列表查询返回里应该包含工具名、描述、参数 schema。成功结果长什么样我总结成一张对照表验证项成功标志失败标志基础连通content 有文本finish_reasonstop401 / 404 / 超时Function Callingfinish_reasontool_calls有 tool_calls 数组finish_reasonstop模型只回文本工具结果回传第二次请求返回自然语言总结模型重复调用同一工具MCP 工具列表返回工具名描述参数 schema连接拒绝 / 空列表验证通过后你才算真正把术语和工程对上了。下一节讲报错这些错我基本都遇到过。5. 本篇常见错排查401、local proxy failed、reading choices、OAuthAgent 接入的报错有几个高频面孔我按出现频率排一下每个都给定位思路。401 Unauthorized。最常见没有之一。原因通常是三个Key 复制时带了空格或换行Key 和 Base URL 不配套比如 Key 是 TaoToken 的Base URL 还写着官方地址或者 Key 已过期/被删。排查方法先用 curl 最小请求测排除 SDK 干扰。如果 curl 也 401就是 Key 或 Base URL 的问题。注意Authorization: Bearer后面有个空格别漏。local proxy failed。这个报错通常出现在你本地配了某些网络工具或者 SDK 读取了系统环境变量里的代理设置。Agent 请求发不出去报连接失败。排查思路检查环境变量HTTP_PROXY、HTTPS_PROXY是否被设置检查 SDK 初始化时有没有传http_client带代理。如果你没主动配代理那可能是某个工具自动注入的。把代理相关环境变量清掉再试。这里要说明我们只讨论本地环境变量配置问题不涉及任何网络访问方式。reading choices 报错。典型信息是KeyError: choices或NoneType object is not subscriptable。这说明你拿到的 response 里没有choices字段。原因可能是请求返回了错误结构比如{error: {...}}但你的代码直接去取response.choices或者流式返回时你按非流式解析了。排查方法先把原始 response 打印出来别急着取字段。如果是错误结构里面通常有error.message告诉你真正原因。流式的话每个 chunk 的choices[0].delta才是内容不是message。OAuth 相关报错。如果你用的是 Claude Code 或某些 CLI 工具它们可能默认走 OAuth 登录流程而不是 API Key。报错信息里会出现OAuth、token refresh failed之类。这时候你要做的是把工具切换到 API Key 模式在配置里显式填 Base URL 和 Key别让它走登录流程。Claude Code 的配置里通常有apiKeyHelper或环境变量方式具体看接入文档。三件套一定要写全Base URL、Key、Model ID缺一个都可能回退到 OAuth。再补一个隐蔽的坑模型不支持工具调用。你配置全对但模型 ID 选了个纯文本模型传tools后模型不返回tool_calls而是用自然语言描述“我应该调用 get_weather”。这不是报错但你的 Agent 会卡住。解决办法是换一个明确支持 Function Calling 的模型 ID。排查顺序我建议固定成先 curl 测连通 → 再测无工具对话 → 再加 tools 测工具调用 → 最后接 MCP。每步只改一个变量出问题范围就小。6. 术语落地之后把统一通道接进你的 Agent 工作流把术语理清、通道跑通之后真正的工作才刚开始。我的建议是先用统一 Key/API 通道把 Function Calling 跑通再考虑 MCP 服务化。因为 Function Calling 是基础MCP 是进阶跳过前者直接上后者你会分不清是工具描述写错了还是协议层出问题。具体到日常开发你可以这样安排模型对话用来快速验证某个模型的工具调用能力改改 prompt 和 tools 定义看它返回的arguments准不准接入文档用来查 Base URL 路径、鉴权头格式这些细节如果你要长期跑编码类 Agent比如让它连续读写文件、执行命令那 Coding Plan 更适合因为这类任务调用量大、对稳定性要求高。统一通道的价值在多模型对比时才明显。同一份tools定义你把model从gpt-4o换成claude-3-5-sonnet就能看出不同模型对同一个工具描述的理解差异。有的模型参数填得准有的会漏字段有的会把日期格式写错。这些差异只有实际跑过才知道光看文档看不出来。最后给一个实用技巧把你的工具描述 JSON 单独存成一个文件别硬编码在请求里。这样切换模型、调整参数时只改一处。Agent 开发里工具定义就是你的“接口契约”它稳定了上层逻辑才能稳定。术语盘点的终点不是记住定义而是你知道每一层该写什么代码、出问题该去哪一层找。