1. 从一次“工具调用失败”说起Agent 的手脚为什么总是不听使唤做 AI Agent 智能体开发最让人抓狂的不是模型不会聊天而是它明明“想”去查天气、算价格、读文件结果要么不调用工具要么参数拼错要么调用完拿不到结果。Function Calling 和 MCP 工具调用本质上就是给智能体装上“手脚”。可很多同学跑通一个 demo 后一上多工具编排就翻车模型返回的tool_calls解析不了、MCP Server 连不上、401 报错、reading choices空指针……这些问题我在实际项目里几乎每周都遇到。这篇是 AI Agent 智能体开发实战系列的第 2 篇聚焦 Function Calling 与 MCP 工具调用的落地链路。我会给你一套可复制的 TaoToken 统一 Key 配置片段、一个 MCP 工具注册示例以及一次从模型请求到工具返回的端到端验证动作。适合谁适合已经会写 Python、想让自己的智能体真正“动手干活”的开发者。核心检索词就三个AI Agent、Function Calling、MCP 工具调用。读完你能跑通完整闭环而不是停留在“连上后就能用”的空话。先说结论Function Calling 负责让模型输出结构化的调用意图MCP 负责把工具的实现标准化而统一 Key 负责让你不用在多个模型供应商之间来回切换。三者拼起来才是一个能上生产的智能体工具层。2. TaoToken 前置准备统一 Key 如何接管 Function Calling 与 MCP 工具调用2.1 为什么 Agent 开发需要一个统一 Key做过智能体的都知道Function Calling 对模型能力有要求MCP 工具调用又常常需要换模型做对比测试。今天用 A 家的模型跑通工具调用明天想换 B 家看准确率结果 Key、Base URL、模型名全要改一遍代码里到处是硬编码。更麻烦的是MCP 的 Host 端比如 Claude Code、Cline 这类客户端配置模型时如果每家都填一套维护成本直接爆炸。TaoToken 在这里扮演的角色是“统一入口”一个 Key、一个 Base URL就能访问多种模型并且兼容 OpenAI 风格的接口。这意味着你写 Function Calling 的代码不用改MCP 客户端里填的配置也不用改只换 Model ID 就能横向对比不同模型在工具调用上的表现。对智能体开发来说这是实打实的效率提升。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意这个不加 UTM。你注册后在控制台生成 Key后面所有配置都用它。2.2 拿 Key 与确认模型 ID进入控制台后在 API Keys 页面创建一个新 Key复制保存。然后去模型列表确认你要用的 Model ID。Function Calling 场景建议选支持 tools 参数的模型MCP 工具调用场景则要确认该模型在客户端里能被正确识别。这一步别偷懒Model ID 写错是最常见的 401 和 404 来源。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite2.3 环境变量与依赖安装我习惯把 Key 放环境变量避免写进代码提交到仓库。先装依赖pip install openai httpx然后设置环境变量Linux/macOSexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api这里有个坑要提醒Base URL 结尾不要多加/v1OpenAI SDK 会自己拼路径。我见过有人写成https://taotoken.net/api/v1结果请求变成/api/v1/v1/chat/completions直接 404。2.4 统一 Key 在 MCP 客户端里的位置如果你用的是 Claude Code 或 Cline 这类支持 MCP 的客户端模型配置通常需要三件套Base URL、API Key、Model ID。以 Claude Code 为例它的配置走环境变量或 settings 文件Base URL 填https://taotoken.net/apiKey 填你生成的Model ID 填控制台里确认过的。这三件套缺一不可尤其是 Model ID写错会直接导致 OAuth 或鉴权失败。注意MCP 工具调用本身不依赖模型供应商但 Host 端调用模型来决策“调哪个工具”时走的就是这套统一 Key。所以配置对了Function Calling 和 MCP 工具调用才能共用同一条链路。3. 可复制配置Function Calling 与 MCP 工具注册的完整片段3.1 Function Calling 的客户端初始化先写一个最小的客户端初始化把统一 Key 接进去import os import json from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) MODEL_ID 你的Model ID # 从控制台模型列表确认这段代码和官方 OpenAI SDK 用法完全一致区别只在base_url。这就是统一 Key 的价值你的 Function Calling 逻辑一行不用改。3.2 工具 Schema 定义Function Calling 的核心是工具描述。模型对工具的理解 100% 来自description和parameters。下面定义一个查天气和一个算价格的工具tools [ { type: function, function: { name: get_weather, description: 获取指定城市的当前天气。当用户询问天气、气温、是否下雨时使用。示例get_weather(city北京), parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海, } }, required: [city], additionalProperties: False, }, }, }, { type: function, function: { name: calc_price, description: 计算商品折扣后价格。示例calc_price(price100, discount0.8), parameters: { type: object, properties: { price: {type: number, description: 原价}, discount: {type: number, description: 折扣0-1之间}, }, required: [price, discount], additionalProperties: False, }, }, }, ]additionalProperties: False和required是生产环境的硬要求能大幅降低参数解析失败率。3.3 MCP 工具注册示例MCP 的标准化价值在于工具由外部 Server 提供Host 通过 JSON-RPC 2.0 调用。下面是一个本地 MCP Server 的工具注册片段以 Python 的 mcp 库为例from mcp.server import Server from mcp.types import Tool, TextContent app Server(demo-tools) app.list_tools() async def list_tools(): return [ Tool( nameread_file, description读取指定路径的文本文件内容。示例read_file(path/tmp/a.txt), inputSchema{ type: object, properties: { path: {type: string, description: 文件绝对路径} }, required: [path], }, ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name read_file: with open(arguments[path], r, encodingutf-8) as f: return [TextContent(typetext, textf.read())] raise ValueError(fUnknown tool: {name})这个 Server 暴露的read_file工具任何支持 MCP 的 Host 都能接入。你不需要为每个客户端写适配代码这就是 MCP 作为“AI 工具 USB-C”的意义。3.4 客户端配置文件片段如果你用 Cline 或 Claude Code配置通常是一个 JSON 或 settings 文件。以 MCP 客户端配置为例{ mcpServers: { demo-tools: { command: python, args: [/path/to/server.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }模型侧的三件套Base URL、Key、Model ID在客户端设置里单独填。这样 MCP 工具调用和模型请求共用同一个统一 Key链路清晰。4. 端到端验证从模型请求到工具返回的完整闭环4.1 第一轮请求让模型决定调哪个工具messages [ {role: user, content: 北京天气怎么样顺便帮我算下原价200打8折多少钱。} ] response client.chat.completions.create( modelMODEL_ID, messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message print(tool_calls:, msg.tool_calls)如果配置正确你会看到模型返回两个tool_calls分别对应get_weather和calc_price。这一步验证的是 Function Calling 的意图识别和参数结构化。4.2 执行工具并回传结果def execute_tool(tool_call): name tool_call.function.name args json.loads(tool_call.function.arguments) if name get_weather: result f{args[city]}: 晴, 26°C elif name calc_price: result str(args[price] * args[discount]) else: result fError: unknown tool {name} return { role: tool, tool_call_id: tool_call.id, content: result, } messages.append(msg) for tc in msg.tool_calls: messages.append(execute_tool(tc))注意tool_call.function.arguments是 JSON 字符串必须先json.loads。这是新手最容易漏的一步直接当 dict 用会报TypeError。4.3 第二轮请求拿到最终回答final client.chat.completions.create( modelMODEL_ID, messagesmessages, toolstools, ) print(final.choices[0].message.content)预期输出类似“北京当前晴气温 26°C原价 200 打 8 折后是 160 元。” 到这里从模型请求到工具返回的完整闭环就跑通了。4.4 MCP 工具调用的验证动作如果你走 MCP 链路验证方式略有不同在 Host 端发起一次对话观察 Host 是否通过 JSON-RPC 向 Server 发送tools/call。你可以在 Server 里加一行日志app.call_tool() async def call_tool(name: str, arguments: dict): print(f[MCP] call_tool name{name} args{arguments}) ...然后在 Host 里问“读一下 /tmp/a.txt”如果日志打印出来且返回了文件内容说明 MCP 工具调用链路通了。这一步验证的是 Host-Client-Server 三层架构的连通性。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见的原因是 Key 没设对或 Base URL 写错。检查两点环境变量TAOTOKEN_API_KEY是否真的被读取可以print(os.environ.get(TAOTOKEN_API_KEY))确认以及 Base URL 是否是https://taotoken.net/api而不是带/v1的版本。如果 Key 是从控制台复制的注意别把前后空格带进去。5.2 local proxy failed这个报错通常出现在 MCP 客户端里意思是 Host 尝试连接本地 Server 失败。排查顺序Server 进程是否启动、command和args路径是否正确、Python 环境是否有 mcp 库。我踩过的坑是args里用了相对路径客户端工作目录不同导致找不到文件改成绝对路径就好了。5.3 reading choices 空指针Cannot read properties of undefined (reading choices)这个报错本质是请求没返回预期结构。常见原因Model ID 写错导致返回错误对象、Base URL 拼错导致 404、或者请求体里tools格式不合法。先打印完整 response 看结构再逐项核对三件套Base URL、Key、Model ID。5.4 OAuth 相关报错Claude Code 这类客户端在配置模型时可能走 OAuth 流程。如果报 OAuth 失败先确认 Base URL 和 Key 是否填在正确的位置。有些客户端把模型配置和 MCP 配置分开别填串了。另外 Model ID 必须是控制台里真实存在的写一个不存在的 ID 会直接鉴权失败。5.5 工具调用参数解析失败如果json.loads(tool_call.function.arguments)抛异常说明模型输出的参数不是合法 JSON。这时候检查你的 Schema 是否设置了additionalProperties: False以及description里有没有给示例。描述越清晰参数越稳。6. 继续把 Agent 的手脚练稳跑通一次闭环只是开始。真正上生产你还要处理并行工具调用、重试熔断、结果缓存这些工程问题。我的建议是先把统一 Key 这条链路固定下来再逐步加工具。每加一个工具就用本篇的验证动作跑一遍确认tool_calls解析、执行、回传三步都正常。如果你在排障或接入阶段卡住了直接去看 API Keys 和接入文档那里有最全的配置说明 API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型在 Function Calling 上的表现可以去模型对话页面直接试 模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你打算长期做编码类 Agent 或复杂工具编排Coding Plan 会更省心 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后一个实用技巧把工具 Schema 和 MCP Server 的list_tools输出做一次 diff确保两边描述一致。我遇到过 Host 端缓存的旧 Schema 和 Server 新工具不匹配导致模型调了一个不存在的工具名排查了半天。工具描述对齐比调 prompt 更能提升 Agent 的稳定性。