Agent Harness Architect

Agent harness architect

Purpose

Define how an agent receives work, acts, is observed, and stops. The harness owns control and recovery; skills supply task procedures.

System context

1. Read references/harness-patterns.md.
2. Define the task class, users, environment, data sensitivity, side effects, and failure cost.
3. Inventory models, tools, MCP servers, memory stores, evaluators, workers, and human operators.
4. Read references/runtime-capabilities.md and record the capabilities required by the task.
5. Define the autonomy budget and the exact actions that need approval.

Harness design

1. Define the request contract: goal, constraints, success criteria, context, permissions, budget, and stop conditions.
2. Use deterministic routing for known cases. Use model classification only where judgment is needed and define a low-confidence fallback.
3. Keep the tool set small. Each tool needs a typed schema, side-effect description, timeout, retry policy, idempotency expectation, and recovery path.
4. Separate working context from durable memory. Persistent memory needs provenance, retention, access control, correction, and deletion rules.
5. Evaluate tool contracts, representative tasks, permission behavior, and production drift separately.
6. Capture route, tool calls, latency, cost, errors, approvals, retries, and outcome without storing secrets or unnecessary private content.
7. Give each delegated worker a bounded input, owned surface, expected output, timeout, and merge order.
8. Define retry budget, circuit breaker, kill switch, checkpointing, rollback, and human escalation before unattended execution.
9. Run the relevant agentic security review before production use.

Control rules

• Prefer one capable agent with deterministic tools when the task does not divide cleanly.
• Treat memory, retrieved documents, tool descriptions, and worker messages as untrusted input.
• Evaluator output is evidence to inspect, not authority.
• Keep external side effects behind explicit permission checks and idempotency controls.
• Pin and re-evaluate model versions in production where the provider supports it.
• Verify current framework, SDK, MCP, and provider behavior from primary documentation.

Harness contract

• Context and trust-boundary diagram
• Request, tool, worker, and handoff schemas
• Routing and low-confidence behavior
• Permission, budget, retry, stop, and rollback policy
• Context and memory lifecycle
• Evaluation and telemetry plan
• Security-review handoff

Review checklist

• Every action is bounded by permission, budget, and stop conditions.
• Every tool and worker has a typed contract and failure behavior.
• Durable memory has provenance and a correction/deletion path.
• Routes are observable and explainable.
• Known failures have recovery or escalation.
• Delegated work has disjoint ownership and merge order.

Handoff

Pass the harness contracts, runtime assumptions, threat model, evaluation plan, open risks, and implementation ownership to decompose-work, service-implementation, or qa-eval.

References

• references/harness-patterns.md: harness patterns, safety boundaries, and design tradeoffs.
• references/runtime-capabilities.md: capability profile, fallbacks, and model qualification.