Back to Details

agent-harness-construction

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Harness Construction

Agent执行框架构建

Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.
当你需要优化Agent的规划、工具调用、错误恢复以及任务收敛完成的能力时，可使用本技巧。

Core Model

核心模型

Agent output quality is constrained by:
  1. Action space quality
  2. Observation quality
  3. Recovery quality
  4. Context budget quality
Agent的输出质量受以下因素限制：
  1. 动作空间质量
  2. 观测结果质量
  3. 错误恢复质量
  4. 上下文预算质量

Action Space Design

动作空间设计

  1. Use stable, explicit tool names.
  2. Keep inputs schema-first and narrow.
  3. Return deterministic output shapes.
  4. Avoid catch-all tools unless isolation is impossible.
  1. 使用稳定、明确的工具名称。
  2. 优先遵循Schema定义输入，保持输入范围窄而明确。
  3. 返回确定性的输出结构。
  4. 除非无法实现隔离，否则避免使用通用万能工具。

Granularity Rules

粒度规则

  • Use micro-tools for high-risk operations (deploy, migration, permissions).
  • Use medium tools for common edit/read/search loops.
  • Use macro-tools only when round-trip overhead is the dominant cost.
  • 高风险操作（部署、数据迁移、权限修改）使用微工具。
  • 常见的编辑/读取/搜索循环使用中型工具。
  • 仅当往返开销为主要成本时才使用宏工具。

Observation Design

观测结果设计

Every tool response should include:
  • status
    : success|warning|error
  • summary
    : one-line result
  • next_actions
    : actionable follow-ups
  • artifacts
    : file paths / IDs
每个工具响应都应该包含：
  • status
    : success|warning|error
  • summary
    : 单行结果摘要
  • next_actions
    : 可执行的后续操作建议
  • artifacts
    : 文件路径 / ID

Error Recovery Contract

错误恢复约定

For every error path, include:
  • root cause hint
  • safe retry instruction
  • explicit stop condition
每个错误路径都应该包含：
  • 根因提示
  • 安全重试指引
  • 明确的停止条件

Context Budgeting

上下文预算管控

  1. Keep system prompt minimal and invariant.
  2. Move large guidance into skills loaded on demand.
  3. Prefer references to files over inlining long documents.
  4. Compact at phase boundaries, not arbitrary token thresholds.
  1. 保持系统提示词简洁且固定不变。
  2. 将大段引导内容迁移到按需加载的skill中。
  3. 优先引用文件，而非内联长文档。
  4. 在阶段边界进行上下文压缩，而非随意按Token阈值压缩。

Architecture Pattern Guidance

架构模式指引

  • ReAct: best for exploratory tasks with uncertain path.
  • Function-calling: best for structured deterministic flows.
  • Hybrid (recommended): ReAct planning + typed tool execution.
  • ReAct：最适合路径不确定的探索性任务。
  • Function-calling：最适合结构化的确定性流程。
  • 混合模式（推荐）：ReAct规划 + 类型化工具执行。

Benchmarking

基准测试

Track:
  • completion rate
  • retries per task
  • pass@1 and pass@3
  • cost per successful task
追踪以下指标：
  • 任务完成率
  • 单任务重试次数
  • pass@1 和 pass@3
  • 单任务成功执行成本

Anti-Patterns

反模式

  • Too many tools with overlapping semantics.
  • Opaque tool output with no recovery hints.
  • Error-only output without next steps.
  • Context overloading with irrelevant references.
  • 工具数量过多，语义重叠。
  • 工具输出不透明，无恢复提示。
  • 仅输出错误信息，无后续操作指引。
  • 加载无关引用内容，导致上下文过载。