Agent Tool Design Best Practices/ 智能体工具设计最佳实践

Agent 工具设计是决定智能体应用成败的关键——工具就是 Agent 的「API 接口」：名字起得好，Agent 调得准；参数设计得合理，Agent 用得顺手；返回值结构清晰，Agent 推理不出错。好的工具设计能让 Agent 自主完成任务，差的设计让 Agent 像「用筷子喝汤」一样力不从心。

Agent 工具设计可以归纳为五个核心原则：

1. 命名即文档（Naming as Documentation）—— 工具名和参数名要「自解释」，让 LLM 一眼理解用途。

• 工具名采用 动词+名词 结构（如 search_products、send_email、get_weather），避免模糊命名（如 do_stuff、process_data）

• 参数名用全称而非缩写（如 user_email 而非 ue），布尔参数用 is_/has_ 前缀（如 is_active）

• 配合工具描述（description）给出使用场景示例，帮助 LLM 在功能相似的多个工具间做正确选择

1. 参数设计要「少而精」（Minimal & Precise Parameters）—— 参数越少，LLM 填对的可能性越高。

• 每个工具参数控制在 3-5 个以内，超过 5 个考虑拆分

• 必填参数（required）用 required=True 标记，可选参数提供合理的默认值

• 参数类型用精确的类型（integer 而非 number，array 而非 string 逗号分隔）让 LLM 输出更规范

• 用 enum/const 约束取值范围，如 status: {type: 'string', enum: ['active', 'inactive']}

1. 返回值结构要「稳定可预期」（Stable & Predictable Returns）—— 返回值格式直接影响 Agent 的下一步推理。

• 统一采用 {success: bool, data: any, error: string} 三级结构

• success=true 时 data 放有效载荷，success=false 时 error 放人类可读的错误原因

• 不要在返回体中掺杂无关元数据（如 metrics、trace_id），容易干扰 LLM 注意力

• 对列表查询类结果控制返回条数（<20条），避免上下文溢出

1. 工具职责要「单一」（Single Responsibility）—— 一个工具只做一件事，做好一件事。

• 查询类工具不写副作用（get_weather 不能包含天气预警推送）

• 操作类工具不混业务逻辑（send_email 只发邮件，不做内容审核）

• 如果 2 个工具调用总是成对出现，考虑合并为一个专用工具

1. 错误处理要有「Agent 友好型」错误信息（Agent-Friendly Errors）—— 错误信息是给 LLM 读的，不是给人读的。

• 错误信息要告诉 Agent 为什么失败 + 怎么修复（如 'User not found. Try searching users first.'）

• 区分可重试错误（rate_limit_exceeded）和不可重试错误（permission_denied），让 Agent 决定是否重试

• 避免暴露堆栈跟踪、SQL 语句等内部实现细节

• 测试一：工具命名与选择准确率（Tool Selection Accuracy）

• 操作：准备 50 个用户意图场景（如「查找最近的星巴克」「给张三发一封邮件」「查询今日北京天气」），每个场景对应一个预期使用的工具。让 Agent 执行并记录它选择了哪个工具，检查是否匹配预期。

• 工具：自定义 pytest 测试集 + OpenAI Function Calling / Anthropic Tool Use API；也可以使用 Braintrust（https://www.braintrust.dev）做托管的 Agent 评测

• 指标：Tool Selection Accuracy（TSA）= 正确选择工具数 / 总测试数，目标 >90%；分析误选分布（是命名歧义还是描述不足导致的）

• 测试二：参数填充正确率（Parameter Filling Accuracy）

• 操作：同样是 50 个场景，对每个工具调用检查其参数值是否正确。包括必填参数是否缺失、参数类型是否匹配、枚举值是否在允许范围。

• 工具：LangChain / LlamaIndex 的 Agent 执行日志 + 自定义参数校验脚本；也可以用 Vellum（https://www.vellum.ai）做 Prompt 版本管理和回归测试

• 指标：Parameter Filling Accuracy（PFA）= 参数完全正确的调用数 / 总调用数，目标 >85%；Parameter Missing Rate（必填参数遗漏率）<2%

• 测试三：返回值解析稳定性（Return Parsing Stability）

• 操作：准备 20 种不同的返回值格式（包括正常结果、空结果、分页结果、报错结果），让 Agent 逐个解析并根据返回值做后续决策，检查 Agent 是否都能正确处理。

• 工具：pytest + 模拟工具调用（mock tool responses）；使用 PromptLayer（https://www.promptlayer.com）做回放调试

• 指标：Return Handling Success Rate（RHSR）= 正确解析并执行后续步骤的次数 / 总测试数，目标 >95%

• 测试四：工具调用质量综合评测（E2E Tool Use Quality）

• 操作：构建 10 个端到端任务场景（如「搜索产品→获取详情→下单」的多步流程），用 BLEU/Rouge-L 或 LLM-as-a-Judge 评估整体完成质量

• 工具：Agent Evaluation 框架（如 LangSmith Eval、Weights & Biases Prompts）

• 指标：任务完成率（Task Completion Rate）>80%；平均工具调用轮次 <5 步；人工打分（1-5）>4.0

1. 「把工具设计成 REST API 的镜像」—— 直接把自己的后端 API 暴露成 Agent 工具，不做任何适配。后端 API 的参数可能很多（8-10个参数）、返回结构复杂、错误信息晦涩（如 status:500, error:'DB connection timeout'），LLM 根本不知道怎么填。对策：每写一个工具都要问自己——「一个 LLM 看到这个工具名和参数，能不查文档就知道怎么用吗？」把工具层想象成「面向 LLM 的 API 网关」，封装掉后端复杂度。

1. 「参数设计完美主义导致工具数量爆炸」—— 为了让参数「少而精」把逻辑拆得太细，结果 5 个功能拆了 20 个工具，LLM 在工具选择时晕头转向。对策：合理归并——如果一个工具在不增加参数的前提下能覆盖多个相近场景，就不要拆分。工具数量建议控制在 10-15 个以内（对一个 Agent 而言），超过 30 个时 LLM 的选择准确率会急剧下降。

1. 「忽略工具调用的安全问题」—— 工具给了 Agent「动手」的能力，但如果没有权限管控，一个 Prompt Injection 就能让 Agent 执行危险操作。对策：每条工具调用都应该通过行为护栏（Behavioral Guardrails）过滤——确认调用者身份、检查参数范围、限制执行频率。关键的写操作（删除数据、转账、发邮件）应该强制走 Human-in-the-Loop 审批。

• OpenAI Function Calling 官方指南 — 最佳参数设计实践和示例（JSON Schema 规范）: https://platform.openai.com/docs/guides/function-calling

• Anthropic Tool Use 文档 — 如何编写工具描述让 Claude 更好理解工具: https://docs.anthropic.com/en/docs/build-with-claude/tool-use

• Building Effective Agents（Anthropic）— Section「When to Use Agents」中关于工具设计的讨论: https://docs.anthropic.com/en/docs/build-with-claude/agentic

• LangChain Tool Design Guide — Tool 类的接口设计与自定义工具教程: https://python.langchain.com/docs/modules/agents/tools/custom_tools/