agent-harness-design

Agent Harness Design

Use when designing or improving how an agent invokes tools, handles errors, and decides when to stop.

When to Use

• Designing tool definitions for a new agent or subagent
• Observing high retry rates or ambiguous tool invocations
• Agent is failing silently or completing without verifying outcomes
• Reviewing an existing agent harness for quality issues

Tool Design Rules

Naming

• Use explicit, stable names: read_file, run_tests, apply_patch
• No generic names: do_action, execute, handle
• One tool per distinct operation; do not overload parameters to compensate

Schema

Keep tool inputs narrow:

• Required fields only; no optional fields that change behavior
• Use enums for mode/type values — never free-text strings that require parsing
• Validate at the boundary; reject malformed input with a clear error, not a fallback

{
  "name": "run_tests",
  "parameters": {
    "path": { "type": "string", "description": "Path to test file or directory" },
    "filter": { "type": "string", "description": "Optional test name filter" }
  }
}

Output Shape

Every tool response must include:

• status: "success" | "warning" | "error"
• summary: one-line result (human-readable)
• next_actions: list of follow-up steps the agent should consider
• artifacts: file paths or IDs produced (empty list if none)

Catch-All Tools

Avoid run_bash / shell_exec style catch-all tools unless:

• The task is genuinely open-ended and the toolset cannot be pre-defined
• You explicitly document the risk and add an allowlist or preflight check

If you must use a catch-all, add a PreToolUse validation hook for dangerous patterns.

Error Path Rules

Every tool must define what happens on failure:

Case	Required response
Invalid input	Reject immediately with status: "error" and exact field name
Transient failure	Include retry_after hint and idempotency note
Non-recoverable	State stop: true and describe the manual resolution step