What a contract must specify

Each agent needs inputs and outputs with schemas—not prose. Tool calls need timeouts, idempotency expectations, and allow-listed endpoints. Shared state needs a single writer or a conflict policy. If two agents can both mutate the same structure, you have a race, not a design.

Contracts also cover failure: what happens when a tool returns 429, when retrieval is empty, or when a human rejects a step. Those paths belong in the workflow definition, not in ad-hoc exception handlers. Version contracts alongside prompts and models so a rollback is a configuration change, not archaeology.

State machines over improvisation

I model workflows as states and transitions with guards. An agent “step” maps to a transition with preconditions: only run when retrieval confidence exceeds a threshold, or when a prior approval record exists. That makes traces replayable and bugs localisable.

Avoid unconstrained “planner” loops that rewrite the graph at runtime unless you persist the rationale and cap iteration depth. Freedom inside a bounded step is fine; freedom to redefine the journey is how you lose auditability.

Acceptance criteria per agent

Every agent role gets measurable checks: format validators, golden-output comparisons, or human review queues for high-risk actions. The system is “done” when those checks pass on a regression set—not when the demo looks good on Tuesday.

Criteria should attach to releases: which harness version, which dataset snapshot, which policy pack. That is how you answer “what changed?” when behaviour shifts in production.

Handover between agents

Define handover payloads explicitly—what the next agent may assume, what it must re-validate, and what must never cross the boundary (e.g. raw PII). Implicit context passing through unstructured blobs is where subtle bugs and leakage creep in.