Contract-Driven Agents: How Platform Teams Can Enforce LLM Output Schemas Without Strangling Agent Autonomy

Think of the LLM as a contractor and the schema as the building code. You don't hand a contractor a stencil and tell them to only cut where the stencil allows — you let them build, then an inspector checks the output against code. The validation node in your agentic pipeline is that inspector. It runs Zod or Pydantic against the raw model output, emits a structured validation event to your observability layer, and branches: pass goes downstream, soft violation triggers a repair loop with the original output and the validation error as context, hard violation goes to a human-in-the-loop gate. This keeps the generation step clean and gives you a seam where you can swap schemas without touching the agent itself. [AI Synthesis] The pattern also composes cleanly with per-phase provenance logging — each validation event carries the schema version, the agent ID, the raw output hash, and the validation verdict, giving you a complete audit trail that governance teams can query independently of the agent execution logs.

import { z } from 'zod';

const AgentOutputSchema = z.object({
  intent: z.enum(['search', 'summarize', 'escalate']),
  payload: z.record(z.unknown()),
  confidence: z.number().min(0).max(1),
  reasoning_trace: z.string().optional(),
});

type ValidationVerdict =
  | { status: 'pass'; data: z.infer<typeof AgentOutputSchema> }
  | { status: 'soft_violation'; errors: z.ZodIssue[]; raw: unknown }
  | { status: 'hard_violation'; errors: z.ZodIssue[]; raw: unknown };

function validateAgentOutput(
  raw: unknown,
  hardFailFields: string[] = ['intent']
): ValidationVerdict {
  const result = AgentOutputSchema.safeParse(raw);
  if (result.success) return { status: 'pass', data: result.data };

  const errors = result.error.issues;
  const isHard = errors.some(e => hardFailFields.includes(e.path[0] as string));

  return isHard
    ? { status: 'hard_violation', errors, raw }
    : { status: 'soft_violation', errors, raw };
}

The CloudFormation custom resource resiliency problem is a useful structural analogy here. AWS built a powerful extension mechanism but left multi-region coordination as the customer's problem — and the failure mode only surfaces when you actually need the resilience. Schema contracts in agentic pipelines have the same latent risk: they work fine in single-agent, single-region dev environments and then expose their gaps the moment you have a multi-agent chain spanning services with independent deployment cycles. Source: Building multi-Region resiliency for AWS CloudFormation custom resource deployment — AWS Architecture Blog (https://aws.amazon.com/blogs/architecture/building-multi-region-resiliency-for-aws-cloudformation-custom-resource-deployment/). The fix is to treat the validator registry itself as a versioned, replicated service — schemas are named artifacts with semver, stored in a central registry, and pulled by version tag at agent startup rather than baked into the agent's deployment artifact. This lets you update a contract without redeploying every agent that touches it, and it gives your observability layer a clean join key between validation events and schema versions.

// Schema registry client — pulls versioned schemas at agent init
import Ajv, { ValidateFunction } from 'ajv';

const ajv = new Ajv();

interface SchemaEntry {
  version: string;
  schema: object;
}

class AgentSchemaRegistry {
  private validators = new Map<string, ValidateFunction>();

  async load(schemaId: string, version: string): Promise<void> {
    const res = await fetch(
      `https://schema-registry.internal/schemas/${schemaId}/${version}`
    );
    const entry: SchemaEntry = await res.json();
    this.validators.set(`${schemaId}@${version}`, ajv.compile(entry.schema));
  }

  validate(schemaId: string, version: string, data: unknown): boolean {
    const key = `${schemaId}@${version}`;
    const validate = this.validators.get(key);
    if (!validate) throw new Error(`Schema ${key} not loaded`);
    return validate(data) as boolean;
  }

  errors(schemaId: string, version: string) {
    return this.validators.get(`${schemaId}@${version}`)?.errors ?? [];
  }
}

OpenAI's announcement that GPT-5.6 Luna achieved an 80% price reduction — enabled in part by using Sol to optimize the forward pass and load balancing — is a direct signal that the cost curve for mid-tier capable models is collapsing faster than most infrastructure teams have priced into their agent budgets. Source: Advancing the price-performance frontier with GPT-5.6 — Simon Willison (https://simonwillison.net/2026/Jul/30/luna-price-drop/#atom-everything). The practical implication for contract validation is that you can now afford to run a repair loop with a Luna-class model on every soft violation without materially affecting your per-session cost — the repair call is cheap enough that it's economically equivalent to a database retry. The architectural pattern that falls out of this is a three-tier validator: a synchronous Zod/Pydantic structural check that costs nothing, a repair prompt to a cheap model for recoverable violations, and an async human-in-the-loop escalation path for semantic violations that the model consistently fails to self-correct — each tier only activates when the previous one fails, which keeps both latency and cost bounded.

interface RepairLoopConfig {
  maxAttempts: number;
  repairModelId: string; // e.g. 'gpt-5.6-luna'
  frontierModelId: string; // e.g. 'gpt-5.6-terra'
}

async function repairWithBudget<T>(
  rawOutput: unknown,
  schema: z.ZodSchema<T>,
  originalPrompt: string,
  config: RepairLoopConfig
): Promise<{ result: T } | { escalate: true; history: unknown[] }> {
  let current = rawOutput;
  const history: unknown[] = [];

  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
    const parsed = schema.safeParse(current);
    if (parsed.success) return { result: parsed.data };

    const errors = parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
    const repairPrompt = [
      `The following JSON failed schema validation:`,
      JSON.stringify(current, null, 2),
      `Errors: ${errors.join('; ')}`,
      `Return only the corrected JSON conforming to the schema. No prose.`
    ].join('\n');

    current = await callModel(config.repairModelId, repairPrompt);
    history.push({ attempt, errors, output: current });
  }

  return { escalate: true, history };
}

Gergely Orosz's decision to pull his podcast from Spotify over reliability failures is a blunt reminder that users don't distinguish between infrastructure problems and product problems — they just experience the degradation and leave. Source: The Pulse: Quitting Spotify Podcasts over reliability — Pragmatic Engineer (https://blog.pragmaticengineer.com/the-pulse-quitting-spotify-podcasts-over-reliability/). Agentic tools that produce inconsistent or silently malformed outputs will face the same churn dynamic — users won't file bug reports, they'll stop using the tool. The connection to last week's dominant theme — hierarchical supervisor topology and human-in-the-loop gates at domain boundaries — is direct: those governance structures are only effective if the schema contracts feeding them are trustworthy. A supervisor that makes routing decisions based on an agent output that passed structural validation but drifted semantically is making decisions on corrupt data without knowing it. [AI Synthesis] This is the core case for treating schema contracts as observable, versioned, SLA-backed infrastructure rather than as static config files — they are the reliability interface between agents, and degradation in that interface compounds upstream faster than any single component failure.

// Validation metrics emitter — plugs into your existing observability stack
import { MetricsClient } from './metrics';

type ValidationOutcome = 'pass' | 'soft_repair' | 'hard_escalation';

interface ValidationEvent {
  agentId: string;
  schemaId: string;
  schemaVersion: string;
  outcome: ValidationOutcome;
  repairAttempts?: number;
  durationMs: number;
}

function emitValidationEvent(
  metrics: MetricsClient,
  event: ValidationEvent
): void {
  const tags = {
    agent_id: event.agentId,
    schema_id: event.schemaId,
    schema_version: event.schemaVersion,
    outcome: event.outcome,
  };

  metrics.increment('agent.validation.total', tags);
  metrics.histogram('agent.validation.duration_ms', event.durationMs, tags);

  if (event.outcome === 'soft_repair' && event.repairAttempts) {
    metrics.histogram('agent.validation.repair_attempts', event.repairAttempts, tags);
  }

  if (event.outcome === 'hard_escalation') {
    metrics.increment('agent.validation.escalation', tags);
    // downstream: alert rule fires if escalation_rate > 0.05 over 5m window
  }
}