1. 电商客服 Agent 工具调用失败的真实场景复盘假设你在做一个电商智能客服 Agent上线前测试一切正常查订单、查物流、处理退款都能跑通。上线第一天却收到大量投诉——用户说「我查我昨天买的耳机物流」Agent 回复「请提供你的订单号」但用户明明已经在 APP 登录上下文里就有用户 ID 和近三个月的订单列表用户问「我的退款什么时候到账」Agent 调用订单查询工具返回一整串 JSON然后总结半天告诉用户「你的退款正在处理」白白烧掉推理成本还有用户说「取消我的订单」Agent 直接调用取消接口没有任何二次确认最后平台赔钱才解决纠纷。排查两天后发现大部分问题根本不是模型推理能力差而是工具和函数本身设计有问题参数描述模糊、错误反馈缺失、权限规则不清晰、输出冗余杂乱。就像你给外卖员的地址只写了「北京市朝阳区」外卖员找不到餐厅不是他笨是你根本没写清楚地址。这就是当前 AI Agent 落地的最大痛点Agent 工具调用的平均成功率并不高其中大部分失败案例源于工具和函数设计的不合理而非模型能力不足。AI Agent Harness Engineering代理执行层工程作为专门解决这一问题的方向核心就是设计一套面向大模型的工具和函数规范让 Agent 能「看得懂、拿得对、用得好」各类工具。读完这篇你会掌握工具Tools与函数Functions的核心区别与设计边界一套可直接落地的「Agent 优先」工具和函数设计方法论可复用的代码框架、评估模型与最佳实践工具设计的未来趋势与行业标准演进方向。下面所有示例都可以直接复制到你的项目里跑起来。2. 概念地图先搞清楚我们在讨论什么2.1 核心概念定义概念定义类比AI Agent HarnessAgent 的执行层「马具」负责管理工具注册、参数校验、权限控制、调用调度、错误处理、结果格式化的整套工程体系外卖平台的调度系统管理所有骑手的派单、路线规划、异常处理工具Tools面向特定场景的能力封装由一组相关的函数组成具备独立的场景边界、权限规则与调度逻辑「外卖配送工具」包含接单、取餐、送餐、确认送达四个环节函数Functions原子级的执行单元对应单一的操作逻辑有明确的输入输出规范与错误处理规则「取餐」这个原子动作需要输入商家地址、餐品编号输出取餐结果2.2 工具 vs 函数核心属性对比对比维度工具Tools函数Functions抽象层级场景级面向业务需求原子级面向执行操作职责范围覆盖一类完整的用户需求完成单一的具体操作输入输出支持多参数输入、多结果聚合固定参数输入、单一结果输出调用主体由 Harness 层调度Agent 仅需选择工具由 Agent 直接调用需指定参数错误处理粒度场景级错误返回整体修复建议操作级错误返回参数级修复建议权限控制粒度场景级权限比如「退款工具需用户确认」操作级权限比如「调用支付接口需二次验签」2.3 知识体系整体框架AI Agent 工具和函数设计可以分为四层基础层是核心概念定义、设计目标与评估标准、常见误区澄清规范层是函数设计规范、工具设计规范、错误处理规范实现层是元数据自动生成框架、调度逻辑实现、监控与迭代体系进阶层是跨模型兼容设计、工具自动优化、标准化工具市场。本文会从基础层一路讲到实现层进阶层给出方向。3. 基础理解工具设计的核心是「以 Agent 为第一用户」很多开发者犯的第一个错误就是用传统 API 设计的思路做 Agent 工具传统 API 是给人类开发者用的只要文档写得全开发者能看懂就行但 Agent 工具是给大模型用的大模型的理解逻辑和人类完全不一样。人类能读懂模糊的表述比如「uid 是用户标识」但大模型会疑惑uid 是数字还是字符串是 10 位还是 15 位从哪里获取人类能自行过滤冗余信息比如 API 返回 20 个字段人类能快速找到自己需要的 3 个但大模型会被冗余信息干扰甚至漏掉关键内容人类遇到错误会自己排查比如参数错了会去查文档但大模型需要你直接告诉它怎么修复。所以工具设计的第一原则就是 Agent First所有的设计都以大模型的理解逻辑为核心人类开发者的体验放在第二位。3.1 工具设计的核心评估指标我们可以用一个数学模型量化工具设计的质量工具调用成功率 S 由三个核心因子相乘得到S C × R × P其中 C 是参数匹配准确率计算方式为参数匹配正确的个数除以总参数个数取值范围 0 到 1R 是返回结果可理解率计算方式为 1 减去模型无法解析的字段占比取值范围 0 到 1P 是调用时机准确率计算方式为符合调用前置条件的次数除以总调用次数取值范围 0 到 1。以电商客服工具为例优化前 C 约 0.65、R 约 0.72、P 约 0.68整体成功率约 31.8%优化后三个指标分别提升到 0.96、0.98、0.97整体成功率达到约 91.3%效果提升非常明显。这三个指标就是你后续迭代工具时的抓手。3.2 常见设计误区澄清误区一功能越全越好。很多开发者喜欢做「万能工具」一个工具支持 10 种场景结果 Agent 完全不知道什么时候该调用调用时机准确率暴跌 30% 以上。最佳实践是一个工具对应一个单一的场景比如「查询未来 7 天天气」和「查询历史气象数据」要拆成两个独立的工具。误区二参数越少越好。为了减少参数错误有些开发者把参数做得非常少比如「查询订单」工具只需要一个 user_id结果返回用户所有订单Agent 要花大量 token 筛选推理成本涨了 2 倍。最佳实践是必填参数必须完整可选参数明确标记默认值。误区三返回信息越全越好。有些开发者把数据库里的所有字段都返回给 Agent比如查询订单返回 20 个字段结果 Agent 经常把「创建时间」当成「支付时间」错误率提升 40%。最佳实践是返回结果分层模型可见的仅保留 3 到 5 个核心字段人类可见的返回完整格式化内容。4. 层层深入从函数到工具的全流程设计规范4.1 第一层原子函数设计规范函数是工具的最小执行单元函数设计的核心是「无歧义、可预期、易修复」。4.1.1 函数命名规范必须采用「动词 核心对象 约束条件」的结构语义唯一禁止使用模糊词汇。反例是 get_data、query_order、deal_refund 这类命名正例是 get_e_commerce_user_order_by_order_id、query_7days_weather_by_city_name、apply_after_sales_refund_by_order_id。命名长度建议在 15 到 40 个字符之间过短语义模糊过长增加模型推理成本。4.1.2 参数设计规范每个参数必须包含 5 个核心要素语义、类型、格式约束、取值范围、获取来源。下面是一个可直接复制的 Pydantic 参数模型from pydantic import BaseModel, Field from enum import Enum class QueryType(str, Enum): ALL ALL PAY PAY LOGISTICS LOGISTICS AFTER_SALES AFTER_SALES class OrderQueryParams(BaseModel): order_id: str Field( description订单编号格式为OD开头加12位数字例如OD123456789012必须从用户的问题中提取如用户未提供请询问用户, min_length14, max_length14, patternr^OD\d{12}$ ) user_id: str Field( description用户唯一标识10位数字从当前对话上下文的用户profile中获取无需向用户询问, min_length10, max_length10, patternr^\d{10}$ ) query_type: QueryType Field( description查询类型可选值为ALL(全部信息)、PAY(支付信息)、LOGISTICS(物流信息)、AFTER_SALES(售后信息)默认值为ALL, defaultQueryType.ALL )关键设计要点优先使用枚举类型限制取值范围避免模型输入无效值枚举类型能把参数匹配准确率提升 25% 以上明确标注参数的获取来源是从上下文取、从用户输入取还是有默认值能避免 Agent 无意义的询问用户减少对话轮次所有参数尽量扁平化不要超过 2 层嵌套大模型对嵌套参数的解析错误率是扁平参数的 3 倍。4.1.3 输出设计规范输出必须采用分层结构分为模型可见内容和人类可见内容两部分from pydantic import BaseModel from typing import Optional, Dict, Any class FunctionResponse(BaseModel): model_visible_content: Dict[str, Any] Field( description给大模型解析的结构化内容仅保留核心字段长度不超过1000token ) human_visible_content: str Field( description给用户展示的自然语言内容格式友好支持markdown ) error_code: Optional[str] Field(defaultNone, description错误码成功时为None) error_msg: Optional[str] Field(defaultNone, description错误描述成功时为None) fix_suggestion: Optional[str] Field(defaultNone, description给大模型的修复建议错误时必填)一个成功返回的示例{ model_visible_content: { order_id: OD123456789012, pay_status: 已支付, logistics_status: 运输中, estimate_arrival_time: 2024-05-20 18:00:00 }, human_visible_content: 订单详情\n订单编号OD123456789012\n商品名称无线蓝牙耳机\n支付状态已支付\n物流状态运输中\n预计送达2024-05-20 18:00:00, error_code: null, error_msg: null, fix_suggestion: null }关键设计要点模型可见内容仅保留 Agent 推理需要的核心字段不要返回冗余信息比如订单的创建时间、商家 ID 这些不需要的字段一律去掉人类可见内容要做格式化处理支持换行、markdown 等提高用户体验这部分内容 Agent 不需要解析直接返回给用户即可。4.1.4 错误处理规范错误返回必须包含三个核心要素错误码、错误描述、修复建议禁止只返回「参数错误」「系统异常」这类模糊信息{ model_visible_content: {}, human_visible_content: 抱歉查询订单失败请你提供订单编号后我再为你查询, error_code: PARAM_MISSING, error_msg: 缺少必填参数order_id, fix_suggestion: 请询问用户提供订单编号格式为OD开头加12位数字例如OD123456789012 }常见错误码与修复建议模板错误码错误场景修复建议模板PARAM_MISSING缺少必填参数请从用户输入或对话上下文中提取{参数名}如不存在请询问用户提供格式为{格式要求}PARAM_INVALID参数格式错误你提供的{参数名}格式错误正确格式为{格式要求}请重新获取后调用PERMISSION_DENIED无调用权限该操作需要用户确认请先询问用户是否确认执行{操作名称}用户同意后再调用RESOURCE_NOT_FOUND资源不存在未找到对应{资源名称}请检查{参数名}是否正确或询问用户重新提供RATE_LIMIT_EXCEEDED调用频率超限该工具调用频率过高请等待10秒后再尝试或建议用户稍后再查询4.2 第二层工具设计规范工具是多个相关函数的小封装面向特定的业务场景核心是明确场景边界、权限规则与调度逻辑。4.2.1 工具元数据规范每个工具必须包含以下元数据下面是一个可直接复制的模板tool_meta { name: e_commerce_order_query_tool, display_name: 订单查询工具, description: 用于查询电商用户的订单相关信息包括支付状态、物流进度、售后信息, applicable_scenarios: [ 用户查询某个订单的详情, 用户询问订单的物流进度, 用户询问订单的支付状态, 用户询问订单的售后进度 ], not_applicable_scenarios: [ 用户查询所有订单列表, 用户申请退款/售后, 用户修改订单地址/信息 ], permission_required: False, pre_conditions: [ 必须获取到用户要查询的订单编号或用户明确要查询最近的一笔订单 ], functions: [ get_e_commerce_user_order_by_order_id, get_e_commerce_user_latest_order ] }关键设计要点适用场景和不适用场景必须用肯定句描述不要用否定句比如不要写「不用于查询订单列表」要写「仅用于查询单个订单的详情」大模型对肯定指令的遵循率比否定指令高 32%明确标注前置条件避免 Agent 在参数不足的情况下调用工具权限要求明确敏感工具比如退款、取消订单、支付必须标注需要用户确认。4.2.2 工具调度逻辑设计工具内多个函数的调度逻辑可以按以下顺序执行Agent 触发工具调用后先校验前置条件是否满足不满足则返回错误加修复建议给 Agent满足则判断需要调用的函数校验函数参数合法性不合法则返回参数级修复建议合法则执行函数判断是否需要调用其他函数需要则继续调用并聚合多个函数的返回结果最后返回分层结果给 Agent。4.3 第三层Harness 层核心实现下面是一个轻量级的 Harness 框架自动处理工具注册、参数校验、权限控制、结果格式化可直接复制使用from typing import List, Dict, Any, Callable from pydantic import ValidationError import functools class Harness: def __init__(self): self.tools: Dict[str, Dict] {} self.functions: Dict[str, Callable] {} def register_function(self, func: Callable): 注册原子函数 self.functions[func.agent_meta[name]] func return func def register_tool(self, tool_meta: Dict): 注册工具 self.tools[tool_meta[name]] tool_meta return tool_meta def call_function(self, function_name: str, parameters: Dict, user_context: Dict None) - Dict: 调用函数 if function_name not in self.functions: return { model_visible_content: {}, human_visible_content: 抱歉我暂时无法完成这个操作, error_code: FUNCTION_NOT_FOUND, error_msg: f函数{function_name}不存在, fix_suggestion: 请选择其他可用的工具或转人工客服处理 } func self.functions[function_name] # 注入上下文参数 if user_context: for k, v in user_context.items(): if k in func.agent_meta[parameters][properties] and k not in parameters: parameters[k] v # 参数校验 try: param_model func.__annotations__[params] validated_params param_model(**parameters) except ValidationError as e: err e.errors()[0] param_name err[loc][0] param_desc func.agent_meta[parameters][properties][param_name][description] return { model_visible_content: {}, human_visible_content: 抱歉参数有误请重新提供, error_code: PARAM_INVALID, error_msg: f参数{param_name}格式错误: {err[msg]}, fix_suggestion: f请重新获取{param_name}{param_desc} } # 执行函数 try: return func(validated_params) except Exception as e: return { model_visible_content: {}, human_visible_content: 抱歉系统异常请稍后再试, error_code: INTERNAL_ERROR, error_msg: str(e), fix_suggestion: 请等待10秒后再尝试调用或建议用户转人工客服处理 }注册一个函数的示例harness Harness() harness.register_function def get_e_commerce_user_order_by_order_id(params: OrderQueryParams) - Dict: order_info query_order_from_db(params.order_id, params.user_id) return { model_visible_content: { order_id: order_info.order_id, pay_status: order_info.pay_status, logistics_status: order_info.logistics_status, estimate_arrival_time: order_info.estimate_arrival_time }, human_visible_content: format_order_for_human(order_info), error_code: None, error_msg: None, fix_suggestion: None }5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth在把工具集接入大模型平台时最常见的报错集中在鉴权与请求链路上。下面按真实报错逐条对照排查。5.1 401 UnauthorizedKey 没生效或 Base URL 写错报错原文通常是Error code: 401 - {error: {message: Invalid API key provided}}。排查顺序先确认环境变量里读到的 Key 是否为空再确认 Base URL 是否指向正确的接口地址。如果你用的是兼容 OpenAI 协议的平台Base URL 应写成https://taotoken.net/api注意末尾不要多加/v1或斜杠否则会拼出//v1/chat/completions这种路径导致 401 或 404。# 检查环境变量是否真的注入 echo $OPENAI_API_KEY | head -c 8 echo $OPENAI_BASE_URL如果 Key 是从控制台复制的注意不要带前后空格和换行。重新生成一个 Key 再试是最快的排除法。5.2 local proxy failed本地代理配置残留报错原文类似APIConnectionError: Connection error. local proxy failed。这通常是本地 shell 里残留了HTTP_PROXY/HTTPS_PROXY环境变量或者客户端配置里写了代理地址。排查方式env | grep -i proxy如果有输出先unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再重试。同时检查~/.openai/config.json或项目里的.env是否硬编码了代理。清掉后重启终端和 IDE。5.3 reading choices响应结构解析失败报错原文常见KeyError: choices或TypeError: NoneType object is not subscriptable。这说明客户端拿到了响应但结构里没有choices字段。原因通常是请求打到了错误的端点比如把/api当成了/v1/chat/completions或者返回的是错误 JSON 被当成了正常响应。排查时先把原始响应打印出来import openai client openai.OpenAI( api_key你的Key, base_urlhttps://taotoken.net/api ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: ping}] ) print(resp.model_dump_json(indent2))如果打印出来是{error: ...}说明鉴权或模型名有问题如果正常返回带choices说明是客户端版本太旧升级openai包即可。5.4 OAuth 相关报错Claude Code / Codex 登录态冲突如果你在 Claude Code 或 Codex CLI 里配置了自定义 Base URL却仍然报 OAuth 相关错误通常是旧的登录态缓存没清。以 Claude Code 为例检查~/.claude/settings.json或项目级.claude/settings.json确认三件套齐全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Codex 则检查~/.codex/auth.json确保OPENAI_BASE_URL和OPENAI_API_KEY都指向同一套配置。三件套Base URL Key Model ID缺一不可只改其中一项就会出现 OAuth 回退到默认登录态的情况。改完后重启 CLI必要时删除~/.claude或~/.codex下的缓存目录再登录。5.5 工具调用返回空模型名与工具协议不匹配如果请求成功但tool_calls始终为空先确认你用的模型是否支持 function calling。部分轻量模型不支持工具调用协议会直接把工具描述当普通文本忽略。换用支持工具调用的模型 ID 再测同时确认tools字段的 JSON Schema 是合法的parameters里不要出现$ref这类模型不认识的字段。6. 语义一致 CTA把工具集真正跑起来工具设计规范讲完最后一步是把它接到真实模型上验证。你需要三样东西一个可用的 API Key、正确的 Base URL、以及支持工具调用的模型 ID。先到 TaoToken API Keys 生成 Key然后在代码里把 Base URL 写成https://taotoken.net/api。如果你只是想先验证工具 schema 能不能被模型正确解析可以直接在 模型对话 里贴一段工具描述试跑看模型是否会按预期选择工具、填参数。长期做编码类 Agent 或需要多轮工具编排的场景建议用 Coding Plan把工具调用链的调试成本压下来。接入细节和参数说明都在 接入文档 里控制台在 Console。一个最小可跑的验证脚本把上面的 Harness 和工具 schema 接进去import openai, json from harness import harness # 上面定义的 Harness 实例 client openai.OpenAI( api_key你的Key, base_urlhttps://taotoken.net/api ) tools_schema [{ type: function, function: { name: get_e_commerce_user_order_by_order_id, description: 根据订单编号查询电商用户的订单详情仅用于查询单个订单, parameters: OrderQueryParams.model_json_schema() } }] resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 帮我查一下订单OD123456789012的物流}], toolstools_schema, tool_choiceauto ) msg resp.choices[0].message if msg.tool_calls: call msg.tool_calls[0] args json.loads(call.function.arguments) result harness.call_function(call.function.name, args, user_context{user_id: 1234567890}) print(result[human_visible_content]) else: print(模型未触发工具调用检查 schema 或模型是否支持 function calling)跑通后你会看到模型自动提取订单号、注入上下文里的 user_id、调用函数并返回格式化结果。如果这一步报 401 或 reading choices回到第 5 节按报错逐条排查。工具设计的迭代没有终点每次线上失败日志都是下一版 schema 的输入。
