agent-harness-construction

Design an agent action space with stable, explicit tool names, schema-first narrow inputs, and deterministic output shapes. Avoid catch-all tools unless isolation is impossible, and match tool granularity to risk: micro-tools for high-risk operations, medium tools for common loops.

Every tool response should include a status field (success, warning, or error), a one-line summary, actionable next_actions, and artifacts such as file paths or IDs. This structure lets the agent plan follow-up steps without parsing opaque output.

ReAct works best for exploratory tasks with uncertain paths, while function-calling suits structured deterministic flows. A hybrid approach is recommended: ReAct for planning combined with typed tool execution for reliability.

For every error path, include a root cause hint, a safe retry instruction, and an explicit stop condition. Avoid error-only output without next steps, since the agent needs recovery guidance to converge on completion.

Track completion rate, retries per task, pass@1 and pass@3, and cost per successful task. These metrics reveal whether changes to the action space, observation format, or recovery contract actually improve agent performance.

Use micro-tools for high-risk operations like deploys, migrations, and permission changes where isolation matters. Use macro-tools only when round-trip overhead is the dominant cost, and medium tools for common edit, read, and search loops.