agent-interface-design

Agent 界面设计

示例只教会一条路径，也悄然排除了其他路径：向模型展示三种调用工具的方式，它往往就只会给出这三种方式。设计良好的界面能一次性展示整个可能空间。参数说明可能的操作，描述说明预期行为，剩下需要写的内容就很少了。

步骤

1. 重新设计工具之前，先弄清楚它实际上是如何被误用的。阅读对话记录、日志或用户的投诉。误用首先是界面问题，其次才是文档问题；解决办法通常是重命名或调整类型，而不是增加一段说明。
2. 将含义融入参数：
   • 用枚举代替自由文本。例如，状态采用 pending | in_progress | completed，无需一句说明文字，就能展现完整的状态机。
   • 根据意图而非实现来命名，让正确的调用本身读起来就很恰当。
   • 在类型系统允许的范围内，让无效状态无法表示。无法表达错误的参数，无需针对该错误添加警告。
3. 将行为说明放在工具自身的描述中，置于使用位置，且只放在那里。在全局前言中重复相同指引，正是代码库产生矛盾的原因。
4. 把想添加用法示例的冲动当作诊断信号：这通常说明参数定义不够明确。先改进界面。只有当格式确实无法推断时才保留示例，例如专用的查询语法。
5. 确定哪些工具应常驻，哪些应可按需发现。大多数轮次都需要的工具应放在上下文中；很少需要的工具应能按需查找，这样在需要之前就不会产生任何开销。
6. 最后，指出设计仍然允许哪种错误，并说明这种错误是否代价足够低，可以接受；还是需要明确的防护措施。

防护措施

• 如果描述必须解释某个参数的含义，就说明这个参数需要更合适的名称。
• 不可逆且风险高的操作例外：这类情况下，明确的限制和确认比优雅更重要。
• 在找到所有现有调用方之前，绝不重新设计签名。
• 目标不是简洁，而是表达清晰。删掉承载真实行为的描述，结果比描述稍长更糟。