任务型Agent工具详细设计：从Function Call到MCP的配置骨架与验证

1. 任务型 Agent 工具层到底难在哪任务型 Agent 的工具层设计说白了就是解决一个问题大模型怎么知道有哪些工具、每个工具要什么参数、调用完结果怎么回填到下一步。听起来简单真动手写的时候你会发现坑集中在三个地方——工具怎么注册、参数怎么描述、调用链路怎么验证。我见过不少团队一开始直接用 Function Call 硬编码工具少的时候还行超过十个工具之后 prompt 里塞满 JSON Schematoken 直接爆炸模型还经常选错工具。后来 MCP 出来了大家又开始纠结要不要全量迁移。其实这两种范式不是替代关系而是不同阶段的工程选择。这篇内容面向正在做任务型 Agent 工具层落地的开发者尤其是那些已经跑通了单工具调用、但还没搞定多工具编排和链路验证的人。我会从 Function Call 和 MCP 两种范式的配置骨架讲起给出可以直接复制的工具注册片段然后带你跑通一次完整的工具调用闭环最后把常见的报错和排查路径列清楚。全程用 TaoToken 作为模型接入层因为它同时支持 Function Call 和 MCP 协议的工具调用省得你在多个平台之间来回切。2. 前置准备TaoToken 接入与工具层环境在开始写工具注册代码之前先把模型接入层搭好。TaoToken 的 API 地址是 https://taotoken.net/api兼容 OpenAI 的接口格式所以 Function Call 和 MCP 两种调用方式都能走同一套鉴权。你需要先拿到一个 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新的 key权限选默认的对话和工具调用就行。创建完之后复制出来后面配置里要用。环境变量建议这样设置避免把 key 硬编码到代码里export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Python装一下 openai 的 SDK 就行版本建议 1.30 以上对工具调用的支持比较完整pip install openai1.30.0Node.js 环境的话用官方的 openai 包版本 4.x 以上npm install openai^4.60.0这里有个细节要注意TaoToken 的 base_url 末尾不要加/v1SDK 内部会自己拼路径。我试过手动加/v1反而会 404这个坑踩过一次就记住了。工具层本身不需要额外装框架Function Call 用 SDK 原生支持就行MCP 的话需要装一个 MCP 的客户端库。Python 用mcp包Node 用modelcontextprotocol/sdk。下面两节分别给配置骨架。3. Function Call 工具注册配置骨架Function Call 的核心是给模型一份工具描述清单模型根据用户输入决定调哪个工具、传什么参数。配置骨架分三块工具定义、工具注册、调用分发。3.1 工具定义用 JSON Schema 描述参数每个工具需要 name、description、parameters 三个字段。description 要写清楚这个工具干什么、什么时候用模型靠这个判断。parameters 用 JSON Schema 描述必填项放 required 数组里。tools [ { type: function, function: { name: submit_optimize_task, description: 提交一个优化任务适用于需要长时间异步执行的场景。调用后返回 task_id后续用 query 工具查询进度。, parameters: { type: object, properties: { task_name: { type: string, description: 任务名称用于标识这次优化 }, task_desc: { type: string, description: 任务描述说明优化目标和约束 }, priority: { type: string, enum: [low, normal, high], description: 任务优先级默认 normal } }, required: [task_name, task_desc] } } }, { type: function, function: { name: query_optimize_task, description: 查询优化任务的执行状态和结果。需要传入 submit 阶段返回的 task_id。, parameters: { type: object, properties: { task_id: { type: string, description: 提交任务时返回的任务 ID } }, required: [task_id] } } } ]这里有个经验description 里最好把调用时机和前置条件写进去。比如 query 工具要说明「需要传入 submit 返回的 task_id」这样模型在多轮对话里不容易漏掉上下文。3.2 工具注册把函数和 schema 绑定定义完 schema 之后需要一个映射表把工具名和实际执行的函数绑起来。这样模型返回 tool_call 的时候你能根据 name 找到对应的处理函数。import json def submit_optimize_task(task_name, task_desc, prioritynormal): # 实际业务逻辑这里模拟返回 task_id task_id ftask_{hash(task_name) % 10000} return {task_id: task_id, status: submitted} def query_optimize_task(task_id): # 模拟查询逻辑 return {task_id: task_id, status: running, progress: 0.6} TOOL_REGISTRY { submit_optimize_task: submit_optimize_task, query_optimize_task: query_optimize_task, } def dispatch_tool_call(tool_name, arguments_json): if tool_name not in TOOL_REGISTRY: return {error: funknown tool: {tool_name}} args json.loads(arguments_json) return TOOL_REGISTRY[tool_name](**args)这个 registry 模式的好处是新增工具只需要加一个函数和一条注册记录不用改调用逻辑。工具多了之后可以按业务域拆成多个 registry用前缀区分。3.3 调用分发处理模型的 tool_calls 返回模型返回的 message 里如果有 tool_calls 字段说明它决定调工具了。你需要遍历 tool_calls逐个执行然后把结果作为 roletool 的消息追加回对话历史。from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] ) def run_agent_turn(messages): response client.chat.completions.create( modelgpt-4o, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message messages.append(msg) if msg.tool_calls: for call in msg.tool_calls: result dispatch_tool_call( call.function.name, call.function.arguments ) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse) }) # 工具执行完再请求一次让模型基于结果继续 return run_agent_turn(messages) return msg.content注意 tool_call_id 必须和模型返回的 id 对应上否则下一轮请求会报错。这个字段很多人第一次写会漏掉。4. MCP 工具注册配置骨架MCP 的思路和 Function Call 不一样。Function Call 是模型厂商绑定的MCP 是开放协议工具跑在独立的 server 上客户端通过标准协议去发现和调用。配置骨架分两块server 端声明工具client 端连接和调用。4.1 MCP Server 端声明工具MCP server 用装饰器的方式声明工具比手写 JSON Schema 简洁一些。Python 的 mcp 包提供了server.tool()装饰器。from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent server Server(optimize-tools) server.tool() async def submit_optimize_task(task_name: str, task_desc: str, priority: str normal) - str: 提交一个优化任务返回 task_id 用于后续查询。 Args: task_name: 任务名称 task_desc: 任务描述 priority: 优先级low/normal/high task_id ftask_{abs(hash(task_name)) % 10000} return json.dumps({task_id: task_id, status: submitted}) server.tool() async def query_optimize_task(task_id: str) - str: 查询优化任务状态需要 submit 返回的 task_id。 return json.dumps({task_id: task_id, status: running, progress: 0.6}) async def main(): async with stdio_server() as (read, write): await server.run(read, write, server.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())MCP 的 tool 描述是从函数签名和 docstring 自动生成的所以 docstring 要写清楚参数含义。这点和 Function Call 手写 schema 不同省事但要求你养成写 docstring 的习惯。4.2 MCP Client 端连接与调用客户端这边需要先建立连接然后 list_tools 拿到工具清单再 call_tool 执行。TaoToken 的 API 层支持把 MCP server 注册进来这样模型侧就能直接看到这些工具。from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client server_params StdioServerParameters( commandpython, args[optimize_server.py], env{TAOTOKEN_API_KEY: os.environ[TAOTOKEN_API_KEY]} ) async def run_mcp_client(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools.tools]) result await session.call_tool( submit_optimize_task, {task_name: test, task_desc: 验证调用链路} ) print(调用结果:, result.content)MCP 的好处是工具 server 可以独立部署、独立升级客户端不用改代码。坏处是多了一层进程通信调试的时候链路更长出问题要分清楚是 server 端还是 client 端。5. 验证一次完整的工具调用闭环配置写完之后必须跑一次端到端的验证确认从用户输入到工具执行再到结果回填整条链路是通的。下面给一个最小验证脚本Function Call 和 MCP 都能用。5.1 Function Call 闭环验证messages [ {role: system, content: 你是一个任务助手可以提交和查询优化任务。}, {role: user, content: 帮我提交一个优化任务名称叫数据清洗描述是把用户表里的空值补全。} ] final run_agent_turn(messages) print(最终回复:, final)预期结果是模型先返回一个 tool_call 调 submit_optimize_task你的 dispatch 执行后返回 task_id模型再基于这个结果生成自然语言回复。如果模型直接回复文字没调工具检查 tools 参数有没有传对或者 description 写得不够明确。5.2 MCP 闭环验证MCP 的验证分两步。先单独验证 server 端工具能跑通再验证 client 能通过协议调到。# 单独测试 server 端 python optimize_server.py # 另开终端用 mcp 自带的 inspector npx modelcontextprotocol/inspector python optimize_server.pyinspector 会打开一个网页界面你能看到所有注册的工具手动填参数调用确认返回结果正确。这一步过了再跑 client 端的脚本。5.3 验证成功的标志一次完整的工具调用闭环跑通你会看到这几个信号模型返回的 message 里有 tool_calls 字段dispatch 函数被调用且参数解析正确工具返回结果被追加到 messages 里 roletool模型基于工具结果生成了最终回复。四个信号缺一个都说明链路有问题。6. 本篇常见错误排查工具调用跑不通报错信息往往很模糊。下面列几个高频问题和排查路径。报错 invalid tool_call_id说明你追加 tool 消息的时候 id 对不上。检查是不是用了自己生成的 id 而不是模型返回的 call.id。Function Call 里这个 id 必须原样回传。报错 tool not found模型调了一个你没注册的工具名。检查 tools 数组里的 name 和 registry 的 key 是否完全一致大小写敏感。MCP 的话检查 server 端有没有成功启动list_tools 能不能拿到。模型不调工具直接回复文字通常是 description 写得太泛模型觉得不需要调工具。把 description 改成明确的动作描述比如「当用户需要提交优化任务时调用此工具」而不是「用于优化任务」。参数解析失败 JSONDecodeError模型返回的 arguments 不是合法 JSON。这种情况在模型能力弱的时候会出现可以在 dispatch 里加一层 try-except解析失败时返回错误信息让模型重试。MCP 连接超时检查 server 进程有没有起来stdio 模式下 server 不能有额外的 stdout 输出否则会污染协议通道。所有日志走 stderr。工具执行结果太长导致 token 超限异步工具返回的原始结果可能很大建议在工具层做一次截断或摘要只把关键字段回传给模型。完整结果可以存到外部用 id 引用。排查的时候建议打开 SDK 的 debug 日志能看到完整的请求和响应体比猜快得多。7. 下一步把工具层接到你的 Agent 里工具注册和调用链路验证通过之后下一步就是把它接到实际的 Agent 编排逻辑里。如果你还在选模型接入层TaoToken 的模型对话接口可以直接测 Function Call 和 MCP 两种模式不用改代码就能切换对比。地址是 https://taotoken.net/api控制台里创建 key 之后就能用。长期做编码类 Agent 的话可以看看 Coding Plan工具调用频次高的时候配额更划算。接入文档里有完整的工具调用示例包括多轮工具编排和错误重试的写法照着改比自己从头写省时间。工具层设计这件事我的经验是先把单工具闭环跑通再扩到多工具。别一上来就搞复杂的工具池和意图路由那是工具超过二十个之后才需要考虑的问题。Less code, more intelligence 这句话在工具层同样适用能交给模型判断的就别写死逻辑。