Designing Schema Evolution So Sub-Agent Handoffs Never Break

Reject at the boundary

Evaluate the contract before the downstream agent starts working. Validate right after receiving the payload, and if it doesn't conform, never launch the downstream at all. This is the one place that turns "silent breakage" into "explicit failure."

import jsonschema
 
def accept_handoff(payload: dict, schema: dict) -> dict:
    """The boundary where the downstream receives a deliverable. Stop immediately on mismatch."""
    try:
        jsonschema.validate(instance=payload, schema=schema)
    except jsonschema.ValidationError as e:
        # Always record which field, what was expected, and what arrived
        path = "/".join(str(p) for p in e.absolute_path) or "(root)"
        raise HandoffError(
            f"Handoff contract violation at '{path}': {e.message}"
        ) from e
    return payload
 
 
class HandoffError(Exception):
    """Raised when an upstream deliverable fails the downstream input contract."""

What matters here is recording "which field" failed and "why" in the error message.

A human reads sub-agent failure logs later. Staring at a log that says only validation failed at midnight is more draining than you'd think. Adding path shrinks root-cause analysis from minutes to seconds.

A realistic sequence for evolving the schema

Once operations begin, a request like "I want to add a confidence score to findings" is inevitable. That's where you hit the additionalProperties: False wall.

The approach I take is to bump schema_version and let old and new coexist. Don't apply a breaking change all at once — set up a migration window.

1. Define a V2 schema that adds the new field as optional (not in required)
2. Make the downstream validator accept both V1 and V2 (dual support via anyOf)
3. Switch the upstream to V2 output
4. Confirm via logs that every flow has moved to V2, then drop V1 acceptance

RESEARCH_HANDOFF_V2 = {
    **RESEARCH_HANDOFF_V1,
    "properties": {
        **RESEARCH_HANDOFF_V1["properties"],
        "schema_version": {"const": 2},
        "findings": {
            "type": "array", "minItems": 1,
            "items": {
                "type": "object",
                "required": ["claim", "source_url"],   # confidence is NOT required
                "properties": {
                    "claim": {"type": "string", "minLength": 10},
                    "source_url": {"type": "string", "format": "uri"},
                    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
                },
                "additionalProperties": False,
            },
        },
    },
}
 
ACCEPTED = {"anyOf": [RESEARCH_HANDOFF_V1, RESEARCH_HANDOFF_V2]}

Follow this order and the handoff survives even when upstream and downstream deploy at different times. Make a new field required from the start and a single moment of mismatch wipes out every existing flow. Add as optional first; remove last. That's the one principle I'd urge you never to compromise on.

Symptoms I actually saw in production

In real operation, it showed up like this:

• The downstream returns an empty deliverable, yet no agent throws
• Re-running sometimes fixes it and sometimes doesn't (it tracked the upstream's deploy progress)
• In a release-note generation pipeline for the App Store, the body text went entirely missing

That last one was a particularly scary symptom. In a flow that generates copy shipped to both Google Play and the App Store, the downstream was waving through a state of "the title arrived but the body key is absent." Before boundary validation, a human had to catch it during the pre-release review.

Once contract validation lived at the boundary, this kind of omission started stopping at the very first stage of the pipeline. The point of failure moved forward from "just before shipping" to "just after the handoff." That's the biggest peace of mind you can buy with design.

Three mechanisms to prevent recurrence

Finally, three mechanisms I build in so the same incident doesn't repeat.

First, have the upstream and downstream import the contract schema from the same file. Write the shape twice — once in each prompt — and one of them will always drift out of sync.

Second, embed schema_version in the deliverable itself. When you dig through logs later, you can see at a glance which contract produced that deliverable.

Third, split validation failures into "retryable errors" and "contract-violation errors." The former are transient (network, etc.) where retrying is meaningful. The latter are shape mismatches where retrying is pointless, so escalate to a human immediately.

When you're orchestrating several agents as an indie developer, plain boundary validation does more for a good night's sleep than clever orchestration does. Typed handoffs are an investment that compounds the more agents you add.

Thank you for reading.