Agent 工具设计最佳实践面向 LLM 的接口契约、描述工程与工具集合收敛【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本篇技术指南以 Agent-Skills-for-Context-Engineering 仓库中 tool-design 技能及其最佳实践参考为核心系统讲解如何为 Agent 系统设计可靠的工具接口从工具哲学、描述工程三原则、命名与枚举规范到错误消息设计、响应格式优化、工具集合收敛与测试评估。读者学完后将掌握一套可直接套用的工具设计检查清单、可落地的错误消息 JSON 结构与响应格式模式并能结合仓库中的源码工具schema 构建器、描述生成器、质量评估器对现有工具集进行审计与迭代。工具哲学工具是 Agent 与世界的接口契约工具是 Agent 与外部世界之间的主要接口。与传统面向开发者的 API 不同工具的使用者不是能读懂底层系统文档的程序员而是从描述中推断意图、从自然语言请求生成调用的语言模型。这一根本差异要求我们重新思考工具接口的设计与文档方式传统 API调用方是人类开发者会阅读文档、理解约定、构造合理请求Agent 工具调用方是语言模型必须仅凭一段描述块推断出完整契约且在调用前无法提出澄清问题。本仓库 tool-design 技能 将这一思想概括为把每个工具都设计成确定性系统与非确定性 Agent之间的契约。描述中任何歧义都会成为潜在故障模式且这种歧义无法通过提示工程修复。设计的最终目标是让 Agent 能够无需大量试错即可发现、理解并正确使用工具工具定义中的每一处歧义都是潜在的失败点每个含义不清的参数名都会迫使 Agent 猜测每个缺失的示例都会让 Agent 在边界情况下失去指引。在仓库的研究基础设施中该机制被登记为 tool-contract-description工具描述必须像可执行契约一样说明用途、激活条件、参数、返回结构与可操作的恢复错误其失败模式包括工具选择错误、格式错误的调用与不可恢复的错误。描述工程三原则原则一回答四个基本问题每个工具描述都应清晰回答四个问题工具做什么用具体术语精确说明工具达成的效果避免 helps withcan be used for 这类含糊语言何时使用给出具体触发条件与上下文既包括直接触发信号也包括表明工具适用性的间接信号接受什么输入用类型、约束、默认值说明每个参数及其控制的内容返回什么描述输出格式与结构包括成功响应与错误条件的示例。仓库中的 ToolDescriptionEvaluator 将上述要求转化为了可自动打分的质量判据——clarity清晰度、completeness完整性、accuracy准确性、actionability可操作性、consistency一致性五个维度各输出 0.0~1.0 的得分。其中_check_clarity会扫描描述中是否出现help、assist、thing、stuff、handle等模糊词以及it、this、that等指代不清的词_check_completeness则校验描述是否包含工具名、Parameters、Returns、Errors四个必需区块。这意味着回答四个基本问题在仓库中是可被机器验证的硬性标准。原则二保持一致结构同一代码库内所有工具描述应保持结构一致。当 Agent 遇到新工具时它能依据从其他工具学到的模式预测特定信息的位置从而降低认知开销、避免格式不一致引发的错误。推荐的结构包括首句简要描述、带使用上下文的详细说明、带清晰类型信息的参数区、描述输出结构的返回区以及列出可能失败模式并给出恢复指引的错误区。该结构在仓库中被固化为 TOOL_DESCRIPTION_TEMPLATE 模板——## {tool_name}、### When to Use、### Parameters、### Returns、### Errors五个区块由 generate_tool_description 统一渲染从工具规格对象直接生成可注入 Agent 上下文的 Markdown 描述。原则三包含具体示例示例弥合了抽象描述与实际使用之间的鸿沟应包含展示常见参数组合的典型调用示例边界情况及其处理方式的示例错误响应及相应恢复动作的示例。好示例要具体而非泛泛。不要写 Use an ID like 123而要写 Use format: CUST-###### (e.g., CUST-000001)不要写 Provide a date而要写 Format: YYYY-MM-DD (e.g., 2024-01-15)。仓库中的 ToolSchemaBuilder 通过add_trigger与add_example方法把何时使用与示例结构化触发词渲染为 When ... 列表示例则以Input / Output键值对形式进入描述最终由generate_usage_context组装成使用场景区。命名规范参数命名参数名应做到自解释——无需额外说明即可表明用途好customer_id、search_query、output_format、max_results、include_details差x、val、param1、info。偏好完整单词而非缩写但id、url等广泛理解的缩写除外同类概念在不同工具间应使用一致的命名。枚举值当参数接受枚举值时所有工具应使用一致的命名。对于布尔风格选项肯定选项使用include_前缀模式include_history、include_metadata否定选项使用exclude_前缀模式exclude_archived、exclude_inactive。对于类别型取值使用一致的术语体系例如统一采用format: concise | detailed避免有的工具用short | long、有的工具用brief | complete造成混乱。一致性同样体现在整体 schema 层面SKILL.md 要求工具名遵循动词-名词模式get_customer、create_order参数名跨工具保持统一始终是customer_id绝不一会儿id一会儿identifier返回字段名保持一致——一致性降低 Agent 的认知负担提升跨工具泛化能力。错误消息设计双重受众错误消息服务两类需求不同的受众调试问题的开发者需要堆栈追踪、内部状态等详细技术信息从失败中恢复的 Agent需要可操作的指引说明出了什么问题以及如何纠正。设计时应以 Agent 恢复为主要考量用清晰的语言说明具体哪里出错了提供描述 Agent 下一步应做什么的解决指引为输入错误提供修正后的格式并给出有效输入的示例。错误消息结构仓库给出的推荐错误结构如下包含错误码、类别、消息、期望格式、解决方案与是否可重试六个字段{ error: { code: INVALID_CUSTOMER_ID, category: validation, message: Customer ID CUST-123 does not match required format, expected_format: { description: Customer ID must be 9 characters, pattern: CUST-######, example: CUST-000001 }, resolution: Provide a customer ID matching pattern CUST-######, retryable: true } }这一结构在仓库源码中已模板化。ErrorMessageGenerator 内置了三种错误模板NOT_FOUND含 resolution 与 example、INVALID_INPUT明确报出具体字段Invalid {field}: {received_value}与期望格式、RATE_LIMITED给出retry_after秒数与等待重试指引并支持传入上下文变量渲染出结构化 JSON 错误。仅返回 failed 的错误消息对 Agent 而言是零恢复信号。常见错误模式校验错误指明收到了什么、期望什么格式、如何纠正限流错误指明等待时间与重试指引未找到错误建议替代方法或验证步骤系统错误说明是否适合重试并建议替代方案。响应格式优化Token 与准确率的权衡冗长的响应信息全面但消耗大量上下文 Token简洁的响应占用最少 Token 却可能缺少必要细节。最优方案是提供格式选项让 Agent 按需请求合适的详细程度。格式选项模式def get_customer_response(format: str concise): Retrieve customer information. Args: format: Response format - concise for key fields only, detailed for complete customer record if format concise: return { id: customer.id, name: customer.name, status: customer.status } else: # detailed return { id: customer.id, name: customer.name, email: customer.email, phone: customer.phone, address: customer.address, status: customer.status, created_at: customer.created_at, history: customer.history, preferences: customer.preferences }何时使用每种格式concise 格式用于快速验证或简单查询、只需确认的场景以及首次检索之后的后续工具调用detailed 格式当基于客户数据做决策时、当输出将成为其他处理的输入时、当完整性上下文对正确性必不可少时。仓库中的 SKILL.md 进一步补充应在工具描述中明确文档化两种格式各自的使用时机让 Agent 学会自行选择同时指出轨迹层面的大规模响应格式选择与观察掩码这类问题属于 context-optimization 技能的职责边界——工具设计关注的是单个工具层面的格式选项而不是跨调用累积的 Token 权重问题。工具集合设计管理工具蔓延随着 Agent 系统成长工具集合趋于膨胀。更多工具带来更多能力但也制造选择难题。研究表明工具描述重叠会导致模型混淆。核心洞见是如果一个人类工程师都无法明确说出这种情况下该用哪个工具那么 Agent 更不可能做得更好——这正是 SKILL.md 中合并原则consolidation principle的表述把工具集缩减到每个工具只有一个无歧义用途为止因为 Agent 通过比较描述来选择工具任何重叠都会引入选择错误。合并指南合并工作流中的顺序步骤把单一工作流中代表顺序步骤的工具合并为一个处理完整工作流的工具。例如不要分别实现list_users、list_events、create_event而是实现一个在单次调用中查找可用时间并完成排期的schedule_event保留行为根本不同的工具即使共享部分功能在不同上下文中使用的工具也应保持分离以防混淆保持工具间边界清晰即使工具处于相似领域也应通过精心设计将功能重叠降到最低。工具选择指引设计工具集合时要考虑 Agent 做出正确选择需要哪些信息。若多个工具都可能适用于某场景应在描述中澄清区别使用命名空间创建逻辑分组帮助 Agent 在工具空间中导航。仓库中给出的分组示例数据库操作路由到db_*命名空间网络交互路由到web_*没有命名空间时Agent 必须在扁平列表中逐个评估每个工具随着数量增长选择准确率会下降。对于 MCPModel Context Protocol多服务器环境SKILL.md 有专门要求始终使用全限定工具名ServerName:tool_name否则多服务器注册同名工具如两个服务器都暴露search时 Agent 可能报 tool not found 或无法消歧# Correct: Fully qualified names Use the BigQuery:bigquery_schema tool to retrieve table schemas. Use the GitHub:create_issue tool to create issues. # Incorrect: Unqualified names Use the bigquery_schema tool... # May fail with multiple servers从合并到架构化约减将合并原则推到极致就是移除大多数专用工具、改用少数原语级通用能力——仓库以 Architectural Reduction Case Study 记录了生产环境的证据该案例的原始素材归档于 docs/vercel_tool.md并被研究管线登记为 claim-tool-design-vercel-d0-reduction一个生产环境 text-to-SQL Agent 原本使用 17 个专用工具GetEntityJoins、LoadCatalog、SearchSchema、SyntaxValidator、ExecuteSQL、FormatResults等假设模型会在复杂 schema 中迷失、做出错误 join 或臆造表名缩减后仅保留两个原语工具ExecuteCommand在沙箱中执行任意 bash 命令与ExecuteSQLAgent 用grep、cat、find、ls直接导航 YAML/Markdown/JSON 语义层文件对比结果为平均执行时间从 274.8s 降至 77.4s快 3.5 倍、成功率从 80% 提升到 100%、平均 Token 用量减少约 37%、平均步数减少约 42%。旧架构最差案例为 724 秒、100 步、145,463 Token 且失败新架构完成同一查询仅用 141 秒、19 步、67,483 Token 且成功。该案例揭示的机理architectural_reduction.md文件系统是经过 50 多年打磨的强抽象标准 Unix 工具文档完善、行为可预测、模型理解深刻专用工具当时在解决模型本可自行处理的问题——预过滤上下文、约束可评估的选项、包裹模型并不需要的校验逻辑每个护栏都成了维护负担。但约减并非普遍适用当底层数据杂乱无文档、领域需要模型不具备的专业知识、安全约束必须限制 Agent 动作、或流程确实受益于结构化编排时不应约减。该参考文档还给出了文件系统 Agent的完整实现模式沙箱创建、execute_command工具描述、ToolLoopAgent最小装配以及五维评估框架维护开销、失败分析、文档质量、约束必要性、模型能力。测试工具设计评估标准工具设计应围绕五个标准评估SKILL.md 的表述为 unambiguity、completeness、recoverability、efficiency、consistency清晰度Clarity/UnambiguityAgent 能否确定何时使用该工具完整性Completeness描述是否包含所有必要信息可恢复性RecoverabilityAgent 能否从错误中恢复效率Efficiency工具是否支持合适的响应格式一致性Consistency工具是否遵循命名与 schema 约定。Agent 测试模式通过向 Agent 呈现代表性请求并评估其产生的工具调用来测试工具准备覆盖多样化 Agent 请求的测试用例让 Agent 为每个请求构造工具调用对照预期模式评估调用正确性识别常见失败模式依据发现优化工具定义。仓库还提供了一种用 Agent 优化工具的闭环模式SKILL.md把观察到的工具失败反馈给另一个 Agent 诊断并改进描述。optimize_tool_description模式的提示词要求分析失败原因、缺失信息与歧义并输出改进后的描述——Agent 使用工具产生失败数据Agent 再用这些数据改进描述从而持续降低未来失败率。反模式清单反模式坏示例好做法含糊描述Search the database for customer information.什么库有什么信息查询格式Retrieve customer information by ID or email. Use when user asks about specific customer details, history, or status. Returns customer object with id, name, email, account_status, and optional order history.隐晦参数名x、val、param1customer_id、max_results、include_history缺失错误处理通用错误或无错误处理提供具体错误类型、消息与解决指引命名不一致同类概念一会儿id、一会儿identifier、一会儿customer_id跨工具对相似概念保持统一命名SKILL.md 的 Gotchas 还补充了几类高频陷阱MCP 命名空间冲突、描述腐化底层 API 演进后描述过期——应把描述当代码管理版本化、API 变更时审查、对照当前行为测试、过度合并单个工具超过 8-10 个参数或服务根本不同的用例时应拆分、参数爆炸过多可选参数淹没 Agent 决策应提供合理默认值、把相关选项分组为格式预设、把少用参数移入options对象、以及缺失错误上下文每个错误响应都应包含非法值、期望格式与具体示例。部署前检查清单在部署新工具前逐项核验对应 SKILL.md 的八项审计清单Name动词-名词命名目录含多领域时加命名空间前缀Description说明工具做什么、何时使用、返回什么Schema每个参数都有类型、约束、默认值与示例值Return shape成功与错误载荷均已文档化且机器可读Recovery每个错误都告诉 Agent 重试前应修改什么Overlap没有其他工具具有相同的激活场景Consolidation decision相邻的窄工具已合并除非确需独立调用Token impact大响应支持 concise 模式或文件引用模式。原文档的核验要点同样保留描述是否清楚说明工具做什么与何时使用参数是否有描述性名称与清晰的类型信息返回值是否文档化结构并给出示例错误情况是否覆盖可操作消息工具是否遵循既有命名约定示例是否演示常见用法响应体量差异大时是否提供格式选项。从原则到代码仓库内的可执行落地上述所有原则在仓库中并非停留在文档层面而是有完整的可运行实现可供直接调用skills/tool-design/scripts/description_generator.pyToolSchemaBuilder流式构建器set_description设置简短与详细描述add_parameter声明参数类型、必填、默认值、枚举set_returns定义返回 schemaadd_error登记带恢复指引的错误条件add_trigger/add_example补充激活场景与输入输出示例build()返回满足ToolSpec协议的结构化规格generate_tool_description将规格渲染为工具名 / 何时使用 / 参数 / 返回 / 错误五段式 Markdown 描述可直接注入 Agent 上下文ToolDescriptionEvaluator对描述在清晰度、完整性、准确性、可操作性、一致性五个维度自动打分——模糊词检测、必需区块校验、描述与规格的腐化检测工具名或参数名缺失即扣分、可操作信号扫描、命名风格一致性检查ErrorMessageGenerator按NOT_FOUND、INVALID_INPUT、RATE_LIMITED模板生成结构化、可解析、可执行的可恢复错误消息。推荐的典型工作流用ToolSchemaBuilder定义工具规格 →generate_tool_description生成渲染描述 →ToolDescriptionEvaluator.evaluate打分审计 →ErrorMessageGenerator.generate产出错误模板。这使得描述工程四问、一致性结构、具体示例、可恢复错误等原则可以零成本地在每次迭代中被机器校验而不是靠人工凭感觉审查。总结工具设计本质上是面向语言模型的接口工程描述是注入 Agent 上下文、直接引导其推理的提示工程错误消息是 Agent 自我纠错的恢复信号而工具集合的整体形态合并、命名空间、乃至原语化约减决定了模型能否做出正确选择。仓库中的最佳实践参考、技能定义、生产案例与可执行工具共同构成了一个完整闭环——设计、生成、评估、测试、迭代——帮助你在更多工具与更少工具之间找到经得起验证的平衡点从最简单架构出发只在被证明必要时增加复杂度并持续追问每个工具是在赋能模型还是在约束模型。延伸阅读tool-design 技能定义本主题的完整技能入口含激活条件、核心概念、审计清单与相邻技能边界Architectural Reduction Case Study17 工具 vs 2 原语工具的生产对比证据与实现模式描述生成与评估工具可运行的 schema 构建器、描述生成器与五维评估器Vercel d0 案例原文归档text-to-SQL Agent 约减案例的完整记录相关技能context-fundamentals工具定义如何消耗注意力预算、context-optimization轨迹级 Token 优化、evaluation工具集效果的整体评估【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考