★ FEATURED ARTICLE 1. 为什么你的 Agent 总是“聊得挺好一动手就废”很多人第一次做 AI Agent都会卡在同一个地方模型能说会道但让它读个文件、跑个命令、查个接口就开始胡编参数、乱调工具甚至把不存在的函数名都给你造出来。这不是模型不行而是 Function Calling 这条链路没搭好。Function Calling 说白了就是给大模型装上“手脚”。模型本身只会输出文本它不知道你的文件系统长什么样也不知道你的数据库有哪些表。你要做的是把“能做什么”用一份结构化的工具清单告诉它再把它吐出来的调用指令接住、校验、执行、把结果塞回去。这一整套流程就是 Agent 的工具调用骨架。我试过用最原始的方式手写 if-else 去解析模型输出结果模型稍微换个说法就崩了。后来才明白生产级的做法必须包含五个环节工具 Schema 注册、意图识别、参数校验、执行回传、错误重试。少一个Agent 就会在某个边界条件下翻车。这篇文章面向的是已经会用大模型 API、但还没把工具调用链路跑通的开发者。我会从工具定义 JSON 开始给你可复制的 Schema、调用循环伪代码以及通过 TaoToken 统一 Key 和 API 通道完成多模型切换的配置示例。目标很明确让你搭出一个能跑起来的 Agent 工具调用骨架而不是停留在“连上后就能用”的空话。适合谁看如果你正在做代码助手、自动化运维 Agent、数据分析 Agent或者单纯想搞明白 Cursor、Cline 这些产品背后的工具系统怎么设计这篇内容会对你有直接帮助。接下来我会按真实项目里的顺序一步步把这条链路拆开。2. TaoToken 统一调用链多模型切换的前置准备在讲工具注册之前得先把“模型从哪来”这件事解决掉。Function Calling 的架构里模型是决策中枢工具是执行末端。如果你每换一个模型就要改一遍 Base URL、Key 和请求格式那工具链根本没法稳定迭代。TaoToken 在这里扮演的角色是统一入口。它提供兼容 OpenAI 风格的 API 通道你可以用同一个 Key 去调用不同厂商的模型工具调用的请求结构保持一致。这对 Agent 开发特别重要因为 Function Calling 的 Schema 是跟着请求体走的如果每个模型厂商的参数格式都不一样你的工具注册层就得写一堆适配代码。先拿到访问凭证。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 的基础地址统一用 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数直接作为 Base URL 使用。这里有个关键点Function Calling 要求模型支持 tools 参数。不是所有模型都支持你在选模型的时候要确认这一点。TaoToken 的模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 可以快速验证某个模型是否能正确返回 tool_calls 字段。我一般会先用一个最简单的天气查询工具做冒烟测试确认模型能吐出结构化的调用指令再往里面加复杂工具。如果你打算长期做编码类 Agent比如类似 Claude Code 那种能读写文件、执行命令的场景可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对代码场景做了通道优化工具调用的往返延迟会低一些。不过前期验证阶段用普通 API Key 就够了。配置的时候我建议把 Base URL、Key、Model ID 这三件套写进环境变量不要硬编码在代码里。后面切换模型只需要改一个 Model ID工具注册层完全不用动。这就是统一调用链的价值工具 Schema 是稳定的模型是可替换的。3. 可复制的工具 Schema 与调用循环配置现在进入核心部分。Function Calling 的第一步是工具注册也就是把每个工具的能力、参数、约束写成 JSON Schema。这份 Schema 会随请求一起发给模型模型根据它来决定调不调、调哪个、传什么参数。先看一个生产级的工具定义。我以文件读取和命令执行为例这两个是代码 Agent 最常用的工具。注意 description 字段它不是随便写一句话而是要把使用场景、参数含义、边界条件都写清楚。模型在每次调用前都会重新读这段描述写得越明确参数幻觉越少。{ type: function, function: { name: read_file, description: 读取指定文件的文本内容。支持通过 start_line 和 end_line 指定行号范围行号从 1 开始计数。当文件较大时建议只读取需要的片段避免一次性加载整个文件导致上下文超限。如果不知道文件总行数可以先读取前 50 行判断结构。, parameters: { type: object, properties: { file_path: { type: string, description: 要读取的文件路径支持相对路径和绝对路径。相对路径基于当前工作目录。 }, start_line: { type: integer, description: 起始行号从 1 开始计数包含该行。默认为 1。 }, end_line: { type: integer, description: 结束行号包含该行。默认为 start_line 49即最多读取 50 行。 } }, required: [file_path] } } }再看命令执行工具。这个工具风险更高所以 description 里要明确写出安全约束和超时行为。{ type: function, function: { name: run_command, description: 在受控环境中执行 Shell 命令并返回标准输出。命令执行有超时限制默认 30 秒。禁止执行破坏性命令如删除根目录、格式化磁盘等。执行前会进行安全模式匹配命中危险模式会直接拒绝。如果需要执行多条命令请用 连接不要分多次调用。, parameters: { type: object, properties: { command: { type: string, description: 要执行的 Shell 命令例如 ls -la 或 python --version。 }, timeout: { type: integer, description: 超时时间单位秒默认 30最大 120。 } }, required: [command] } } }工具注册好之后接下来是调用循环。这是 Agent 的心脏把用户请求和工具列表发给模型模型返回 tool_calls你执行工具把结果作为 tool 角色消息追加回对话再发给模型直到模型不再请求工具、直接给出最终回答。下面这段伪代码把整个循环写清楚了你可以直接照着实现。# 调用循环伪代码 messages [{role: user, content: user_input}] tools [read_file_schema, run_command_schema] while True: response call_model( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], modelos.environ[MODEL_ID], messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message # 模型没有请求工具直接返回最终回答 if not msg.tool_calls: return msg.content # 把模型的工具调用请求追加进对话 messages.append(msg) # 逐个执行工具调用 for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) # 参数校验 valid, error validate_args(name, args) if not valid: result f参数校验失败: {error} else: try: result execute_tool(name, args) except Exception as e: result f工具执行异常: {str(e)} # 把执行结果作为 tool 消息追加 messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result) })这段循环里有三个容易出问题的地方。第一tool_call.function.arguments是字符串不是字典必须用json.loads解析而且模型偶尔会返回不合法 JSON要加 try-except。第二每个 tool 消息必须带上对应的tool_call_id否则模型无法把结果和请求对应起来。第三循环要有最大轮次限制防止模型陷入无限调用。参数校验层我单独写一个函数把必填检查、类型检查、枚举值检查都放进去。这一步能挡掉大部分模型幻觉比如它把start_line传成字符串1或者漏掉file_path。def validate_args(tool_name, args): schema TOOL_REGISTRY[tool_name] required schema[function][parameters].get(required, []) properties schema[function][parameters][properties] for key in required: if key not in args: return False, f缺少必填参数 {key} for key, value in args.items(): if key not in properties: return False, f未知参数 {key} expected properties[key][type] if expected string and not isinstance(value, str): return False, f参数 {key} 应为字符串 if expected integer and not isinstance(value, int): return False, f参数 {key} 应为整数 return True, None把这三块拼起来你就有了一个最小可用的 Function Calling 引擎。工具注册负责“告诉模型能干什么”调用循环负责“接住模型的指令并执行”参数校验负责“在执行前拦住错误”。接下来要做的是验证这条链路真的跑得通。4. 验证请求与成功结果从 tool_calls 到最终回答配置写完了得实际发一次请求确认链路通畅。我建议用一个最简单的场景做验证让模型读取一个已知内容的文件然后根据文件内容回答问题。这样你能同时看到工具调用和结果回传两个环节。先准备一个测试文件比如demo/hello.txt内容写三行第一行项目名称是 AgentDemo 第二行版本号是 1.0.0 第三行维护者是 dev-team然后构造请求。注意请求体里的tools字段就是前面注册的 Schema 数组tool_choice设为auto让模型自己决定。Base URL 用https://taotoken.net/apiModel ID 填你选定的支持 Function Calling 的模型。import os import json from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY] ) tools [read_file_schema, run_command_schema] response client.chat.completions.create( modelos.environ[MODEL_ID], messages[ {role: user, content: 请读取 demo/hello.txt 文件告诉我项目名称和版本号。} ], toolstools, tool_choiceauto ) print(json.dumps(response.choices[0].message.model_dump(), ensure_asciiFalse, indent2))如果链路正常你会看到返回的 message 里有一个tool_calls数组里面包含function.name为read_filefunction.arguments是一个 JSON 字符串类似{file_path: demo/hello.txt}。这说明模型正确识别了意图选择了对的工具并且生成了合法参数。接下来把工具执行结果回传。你手动执行读取或者用前面的引擎执行然后把结果作为 tool 消息追加再发一次请求。# 假设第一次返回的 tool_call tool_call response.choices[0].message.tool_calls[0] # 执行工具这里直接读文件模拟 with open(demo/hello.txt, r, encodingutf-8) as f: file_content f.read() # 构造第二轮请求 messages [ {role: user, content: 请读取 demo/hello.txt 文件告诉我项目名称和版本号。}, response.choices[0].message, { role: tool, tool_call_id: tool_call.id, content: file_content } ] final_response client.chat.completions.create( modelos.environ[MODEL_ID], messagesmessages, toolstools, tool_choiceauto ) print(final_response.choices[0].message.content)成功的话模型会输出类似“项目名称是 AgentDemo版本号是 1.0.0”的回答。注意这一轮返回的 message 里tool_calls应该是空的因为模型已经拿到了需要的信息直接生成最终回答。这里有个细节值得注意工具执行结果的内容格式会影响模型理解。如果你返回的是原始文件内容模型能直接读到如果你返回的是 JSON 包装模型也能解析但多一层结构。我一般对文本类结果直接返回原文对结构化数据返回 JSON 字符串并在工具 description 里说明返回格式。验证通过后你可以把tool_choice改成required强制模型必须调用工具测试它在没有合适工具时的行为也可以故意传一个不存在的文件路径看错误信息怎么回传。这些边界测试能帮你提前发现链路里的薄弱点。5. 常见报错排查401、local proxy failed、reading choices、OAuth链路跑通不代表稳定。实际开发中Function Calling 的报错往往集中在几个固定位置。我把踩过的坑按报错信息整理出来你对照着排查。401 Unauthorized这个最直接Key 不对或者没带上。检查Authorization头是不是Bearer 你的KeyKey 有没有多余空格。如果你用的是环境变量确认变量名没写错比如TAOTOKEN_API_KEY和TAOTOKEN_KEY是两个不同的变量。还有一种情况是 Key 被禁用或额度耗尽去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认状态。local proxy failed / connection refused这个报错通常出现在你本地配了代理但代理没启动或者端口不对。Function Calling 的请求走的是标准 HTTPS不需要额外代理配置。如果你在代码里设置了http_proxy或https_proxy环境变量先清掉再试。另外检查 Base URL 是不是写成了https://taotoken.net/api/带尾斜杠有些 HTTP 客户端会把尾斜杠拼成双斜杠导致路径错误。reading choices of undefined这是 JavaScript/TypeScript 里常见的报错意思是响应体里没有choices字段。原因通常是请求根本没成功返回的是一个错误对象但你的代码直接去读response.choices[0]。修复方法是先判断响应状态或者用可选链response?.choices?.[0]。在 Python 里对应的是response.choices为 None 或空列表同样要先检查。OAuth token expired / invalid_grant如果你用的是某些需要 OAuth 的模型通道token 过期会报这个。TaoToken 的 API Key 方式是静态 Key不涉及 OAuth 刷新所以如果你遇到这个报错说明你可能混用了其他通道的配置。确认 Base URL 是https://taotoken.net/api认证方式是 API Key 而不是 OAuth。tool_calls 为空但模型没回答这种情况一般是模型不支持 Function Calling或者tools参数格式不对。先确认模型 ID 是否在支持列表里然后用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 手动发一个带 tools 的请求看返回结构。如果模型返回的是普通文本而不是 tool_calls说明它没识别工具定义检查 Schema 的type是不是functionfunction.name有没有特殊字符。参数解析失败 JSONDecodeError模型返回的arguments不是合法 JSON。这在模型能力较弱时会出现比如它把参数写成单引号或者漏了引号。解决办法是在解析前做一次清洗比如把单引号替换成双引号或者用更宽松的解析器。更稳妥的做法是在 System Prompt 里强调“arguments 必须是合法 JSON”。工具执行超时命令执行类工具容易超时。检查你的超时设置默认 30 秒对大多数命令够用但npm install这种可能要几分钟。把超时做成参数让模型可以指定同时在工具 description 里说明默认值和最大值。排查的时候有个通用思路先确认请求有没有发出去再看响应体结构最后看工具执行环节。大部分问题出在第一步和第二步之间也就是认证和请求格式。把 Base URL、Key、Model ID 这三件套核对一遍能解决八成以上的报错。6. 把工具链跑稳之后下一步做什么工具调用骨架搭起来之后你会发现 Agent 的能力边界完全由工具集决定。我现在的做法是先把最常用的五六个工具做扎实比如文件读写、目录浏览、命令执行、HTTP 请求然后根据具体场景往里加。每加一个工具都要写清楚 description 和参数约束并且在测试用例里覆盖它的正常路径和异常路径。多模型切换这块统一调用链的价值会随着模型迭代越来越明显。今天用这个模型做推理明天换个模型做代码生成工具注册层完全不用动只改一个 Model ID。如果你在做长期编码类 AgentCoding Plan 的通道优化能省不少调试时间如果只是验证模型能力模型对话页面足够快速试错。最后留一个实用建议给调用循环加日志。每次工具调用的名称、参数、执行耗时、返回状态都记下来。这些日志在你排查“为什么 Agent 这次没调对工具”的时候比任何猜测都有用。工具链的稳定性不是一次写成的是靠这些日志一点点磨出来的。
阅读完成 · 觉得有帮助？
