Structured Output Contracts for Agent-to-Agent Communication

Define the Schema Before the Prompt

The instinct is to write the prompt first and then figure out the output format. Flip that. Start with the downstream consumer. What fields does it need? What types? What are the constraints? Write that as a Pydantic model or JSON Schema before you write the prompt.

from pydantic import BaseModel, Field
from typing import Optional, List

class ExtractedContact(BaseModel):
    name: str = Field(description="Full name of the contact")
    email: str = Field(description="Primary email address")
    company: Optional[str] = Field(default=None, description="Company name if present")
    tags: List[str] = Field(default_factory=list, description="Relevant classification tags")

Then write the system prompt referencing this schema. The schema is your source of truth — not the prompt.

Why Pydantic: Beyond type validation, Pydantic's .model_json_schema() generates a JSON Schema that you can inject directly into the system prompt or into a model's response_format parameter. The schema and the validation logic stay in sync automatically.

Enforce at the Boundary with Strict Mode

Several inference providers now support strict structured output modes that constrain the model's token sampling to only produce valid JSON matching your schema. This eliminates a class of hallucination at the format level.

• OpenAI (gpt-4o and newer): Set response_format={"type": "json_schema", "json_schema": {...}, "strict": True} via the API. The model's output is guaranteed to conform to the schema. See OpenAI's Structured Outputs for Multi-Agent Systems cookbook for multi-agent examples.
• Anthropic (Claude): Use strict tool use via input_schema to enforce valid parameters on tool calls. Combine with JSON output mode for guaranteed structure on final responses.
• PydanticAI: Wraps model calls with automatic output validation. If the model returns something that doesn't parse against your BaseModel, it retries with correction instructions automatically.

The key principle: Don't validate downstream. Validate at the boundary, immediately after the model response and before passing to the next agent.

# Validate at boundary, not downstream
raw_output = agent_a.run(input_data)
try:
    validated = ExtractedContact.model_validate_json(raw_output)
except ValidationError as e:
    # Retry, log, or route to dead-letter queue
    handle_schema_failure(raw_output, e)

Schema Versioning with Backward Compatibility

This is where most teams get burned. They update Agent A's output schema and don't realize Agent B is still expecting the old shape.

Treat output schemas like API versions:

1. Embed the schema version in the output:

{
  "_schema_version": "1.2",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tags": ["enterprise", "warm-lead"]
}

2. Follow backward compatibility rules:

• Non-breaking (minor bump): Adding optional fields with defaults
• Breaking (major bump): Removing fields, renaming fields, changing types, making optional fields required

3. Keep the version in your schema registry, not just your code. Whether you use a dedicated schema registry (Confluent, AWS Glue, Solace) or a simple schemas/ directory in your repo, the schema must be discoverable and diffable independently of any agent's code.

As Auxiliobits noted in November 2025, some teams end up with compound version identifiers like "v1.4-prompt-B + orchestration-v2 + model-2025-01-15" — which is technically correct but operationally a nightmare. Decouple schema versioning from prompt versioning from model versioning.

Dead-Letter Queues for Schema Failures

Schema validation failures in production shouldn't crash the pipeline. They should route to a dead-letter queue (DLQ) — a mechanism to capture and inspect bad outputs without losing the payload.

def route_message(raw_output: str, schema_class: BaseModel):
    try:
        return schema_class.model_validate_json(raw_output), None
    except ValidationError as e:
        dlq_entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "schema": schema_class.__name__,
            "raw_output": raw_output,
            "validation_errors": e.errors()
        }
        append_to_dlq(dlq_entry)
        return None, dlq_entry

Review your DLQ regularly. Schema failures are signal — they tell you when a model update changed output behavior, when a prompt regressed, or when a new edge case isn't covered by the current schema.