Agent Handoffs: Structured Returns Beat Prose

The hardest part of multi-agent workflows is the handoff. Agent A finishes. Agent B starts. What does B know that A learned? If A returns prose, B has to re-read and re-interpret. Information leaks at every handoff.

Structure The Return

I make every subagent return a structured result. Not a paragraph. A dictionary with known keys. The orchestrator reads specific fields and decides the next step deterministically.

# Subagent returns this, not a paragraph
return {
    'status': 'complete',  # or 'blocked', 'needs_input'
    'files_changed': ['app/routes/posts.py'],
    'tests_added': 3,
    'tests_passing': True,
    'deviations': [],  # rules 1-3 auto-fixes
    'next_suggested': 'integration_test',
    'commit_hash': 'a1b2c3d',
}

Now the orchestrator can branch: if status is blocked, escalate. If deviations is non-empty, log them in the summary. If tests passing is false, re-spawn with a fix task. The logic is readable code, not prompt acrobatics.

Why Prose Loses

Prose returns force the orchestrator to parse natural language. That parsing is another LLM call, which costs money, adds latency, and fails non-deterministically. Structured returns let you skip the interpretation layer entirely.

The Discipline

Define the return schema in the orchestrator's prompt to the subagent. Make the schema part of the task itself. If the agent returns prose, it violated the contract and you respawn. After two weeks the subagents follow the schema without reminders.

See structured outputs with tool use for patterns. Structured handoffs are the thing that turns multi-agent from theater into a real pipeline.