agent-harness-construction

name	agent-harness-construction
description	设计和优化 AI 智能体操作空间、工具定义和观察格式，以获得更高的完成率。
origin	ECC

智能体工具构建

在改进智能体如何规划、调用工具、从错误中恢复并收敛到完成时使用此技能。

核心模型

智能体输出质量受限于：

1. 操作空间质量
2. 观察质量
3. 恢复质量
4. 上下文预算质量

操作空间设计

1. 使用稳定、明确的工具名称。
2. 保持输入模式优先且狭窄。
3. 返回确定性输出形状。
4. 除非不可能隔离，否则避免全能工具。

粒度规则

• 对高风险操作（部署、迁移、权限）使用微工具。
• 对常见编辑/读取/搜索循环使用中等工具。
• 仅当往返开销是主要成本时才使用宏工具。

观察设计

每个工具响应应包括：

• status：success|warning|error
• summary：单行结果
• next_actions：可操作的后续步骤
• artifacts：文件路径 / ID

错误恢复合同

对于每个错误路径，包括：

• 根本原因提示
• 安全重试指令
• 明确停止条件

上下文预算编制

1. 保持系统提示最小且不变。
2. 将大型指导移动到按需加载的技能。
3. 优先引用文件而非内联长文档。
4. 在阶段边界压缩，而非任意令牌阈值。

架构模式指导

• ReAct：最适合路径不确定的探索性任务。
• 函数调用：最适合结构化确定性流。
• 混合（推荐）：ReAct 规划 + 类型化工具执行。

基准测试

跟踪：

• 完成率
• 每项任务的重试次数
• pass@1 和 pass@3
• 每项成功任务的成本

反模式

• 具有重叠语义的工具过多。
• 没有恢复提示的不透明工具输出。
• 只有错误没有下一步的错误输出。
• 过载不相关引用的上下文。