Back to Details

agent-harness-construction

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Harness Construction

Agent Harness 构建

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. 将大型指导内容移入按需加载的技能中。
  3. 优先使用文件引用而非内联长文档。
  4. 在阶段边界处压缩上下文，而非基于任意令牌阈值。

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：最适用于路径不确定的探索性任务。
  • 函数调用：最适用于结构化的确定性流程。
  • 混合模式（推荐）：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.
  • 过多语义重叠的工具。
  • 不透明的工具输出，无恢复提示。
  • 仅含错误信息而无后续步骤的输出。
  • 包含无关引用的上下文过载。