Contract-Driven Agents: The Output Schema Patterns That Make Agentic Systems Actually Trustworthy

A typed output envelope functions like a message schema in an event-driven system — the agent is the producer, your orchestration layer is the broker, and every downstream service is a consumer that deserves a stable contract. The envelope should carry a discriminated union of result types (success, partial, error, deferred), a correlation ID that threads through your distributed trace, a policy_scope identifier that says which governance rules applied, and a structured payload whose shape is pinned to a versioned schema. If you're building in TypeScript, `zod` gives you runtime parse-and-validate for free at the boundary; in Java, a `@Valid` annotated record with a sealed interface hierarchy gives you compile-time exhaustiveness checking that survives refactors. The point isn't type safety as an aesthetic — it's that every unvalidated agent output is a trust boundary you've left open, and in a multi-agent pipeline, one malformed envelope cascades into every node downstream.

AIThe organizational dimension matters here too: typed contracts aren't just a runtime concern, they're the artifact that lets platform and product teams have a concrete conversation about what an agent actually promises to deliver. When the contract is a TypeScript interface checked into the same repo as the agent's tool definitions, disagreements about agent behavior become diffs, not Slack arguments. This is the same discipline that made REST API contracts workable at scale, applied to a surface area that's harder to reason about because the 'implementation' is a model whose behavior you don't fully control.

// TypeScript: Typed output envelope for contract-driven agents
import { z } from 'zod';

const PolicyScope = z.enum(['read_only', 'write_restricted', 'full_access']);

const AgentResultPayload = z.discriminatedUnion('status', [
  z.object({
    status: z.literal('success'),
    data: z.record(z.unknown()),
    confidence: z.number().min(0).max(1),
  }),
  z.object({
    status: z.literal('partial'),
    data: z.record(z.unknown()),
    missing_fields: z.array(z.string()),
  }),
  z.object({
    status: z.literal('error'),
    error_code: z.string(),
    recoverable: z.boolean(),
  }),
  z.object({
    status: z.literal('deferred'),
    requires_human_review: z.literal(true),
    reason: z.string(),
  }),
]);

const AgentOutputEnvelope = z.object({
  schema_version: z.literal('2.0'),
  correlation_id: z.string().uuid(),
  agent_id: z.string(),
  tool_invocations: z.array(z.string()),
  policy_scope: PolicyScope,
  result: AgentResultPayload,
  emitted_at: z.string().datetime(),
});

export type AgentOutputEnvelope = z.infer<typeof AgentOutputEnvelope>;

// At your agent boundary:
export function parseAgentOutput(raw: unknown): AgentOutputEnvelope {
  const parsed = AgentOutputEnvelope.safeParse(raw);
  if (!parsed.success) {
    throw new AgentContractViolation(parsed.error.flatten());
  }
  return parsed.data;
}

The CrewAI team's argument from the Data + AI Summit is essentially that direct credential access makes the agent the authorization layer, which it was never designed to be. The alternative is to build a thin data-access service layer — call it a tool gateway — where each tool exposes a typed request schema and returns a typed response schema, and the underlying database call lives entirely behind that boundary. In PostgreSQL terms, this maps naturally to a read-only role that can only invoke specific functions, each of which returns a well-defined composite type. The agent never sees a connection string; it sees a tool interface. When something goes wrong, your audit log shows which tool was called with which arguments, not which arbitrary SQL ran against which table.

This pattern also gives you a clean place to enforce row-level filtering, redact PII fields, and apply rate limiting per agent identity — all things that are nearly impossible to retrofit once you've given the agent direct database access. The tool gateway becomes the observable chokepoint where you can attach your OpenTelemetry spans, your policy checks, and your schema validators without touching the agent's reasoning loop at all. Source: [Stop giving your agents database credentials] — CrewAI (https://blog.crewai.com/stop-giving-your-agents-database-credentials/)

// TypeScript: Tool gateway with scoped contract — no credentials in agent scope
import { z } from 'zod';
import { Pool } from 'pg';

// Input/output contracts pinned at tool definition time
const GetCustomerSummaryInput = z.object({
  customer_id: z.string().uuid(),
  fields: z.array(z.enum(['name', 'account_status', 'tier'])),
});

const GetCustomerSummaryOutput = z.object({
  customer_id: z.string().uuid(),
  name: z.string().optional(),
  account_status: z.enum(['active', 'suspended', 'closed']).optional(),
  tier: z.enum(['free', 'pro', 'enterprise']).optional(),
});

export type GetCustomerSummaryInput = z.infer<typeof GetCustomerSummaryInput>;
export type GetCustomerSummaryOutput = z.infer<typeof GetCustomerSummaryOutput>;

// The tool: agent never touches a connection string
export async function getCustomerSummary(
  rawInput: unknown,
  pool: Pool, // injected by platform, not by agent
): Promise<GetCustomerSummaryOutput> {
  const input = GetCustomerSummaryInput.parse(rawInput);

  // Calls a stored function — not raw SQL
  const { rows } = await pool.query(
    'SELECT * FROM get_customer_summary($1, $2)',
    [input.customer_id, input.fields]
  );

  return GetCustomerSummaryOutput.parse(rows[0]);
}

The research from Charles Ye, Jasmine Cui, and Dylan Hadfield-Menell reframes prompt injection as fundamentally a role-boundary enforcement problem: the model is asked to behave differently depending on which 'role' a message came from, but at inference time those role tags are just more tokens, not enforced access control. This maps directly to the contract-driven agent problem — if your system prompt and your user message both arrive as unstructured strings, you're relying on the model to honor a privilege boundary that isn't structurally enforced anywhere in your pipeline. The fix isn't purely a model problem; it's an architecture problem. Source: [Prompt Injection as Role Confusion] — Simon Willison (https://simonwillison.net/2026/Jun/22/prompt-injection-as-role-confusion/#atom-everything)

AIIn practice, platform teams can implement a partial structural defense by building their context assembly layer to serialize the system prompt as a typed, signed block before agent invocation, and to treat any deviation from expected output schema post-invocation as a potential injection signal rather than just a validation failure. This connects directly to the output envelope pattern in block_1: if your agent's discriminated union suddenly resolves to a shape that doesn't match any variant — or if fields that should be absent under a read_only policy scope are suddenly populated — you have observable evidence that something in the input context manipulated the agent's reasoning. That's not a complete defense, but it's the kind of defense that surfaces in your observability stack rather than silently succeeding.

// TypeScript: Context envelope with role-boundary integrity check
import { createHmac } from 'crypto';
import { z } from 'zod';

const ContextEnvelope = z.object({
  system_prompt_hash: z.string(), // HMAC of the trusted system prompt
  system_prompt: z.string(),
  user_input: z.string(),
  assembled_at: z.string().datetime(),
  trust_level: z.enum(['system', 'user', 'tool_output']),
});

export function assembleContext(
  systemPrompt: string,
  userInput: string,
  signingKey: string,
): z.infer<typeof ContextEnvelope> {
  const hash = createHmac('sha256', signingKey)
    .update(systemPrompt)
    .digest('hex');

  return ContextEnvelope.parse({
    system_prompt_hash: hash,
    system_prompt: systemPrompt,
    user_input: userInput,
    assembled_at: new Date().toISOString(),
    trust_level: 'system',
  });
}

// Post-invocation: treat schema violations as security signals
export function validateOrFlag(
  rawOutput: unknown,
  expectedSchema: z.ZodTypeAny,
  correlationId: string,
) {
  const result = expectedSchema.safeParse(rawOutput);
  if (!result.success) {
    // Emit as security event, not just a format error
    emitSecurityEvent({
      type: 'AGENT_OUTPUT_CONTRACT_VIOLATION',
      correlation_id: correlationId,
      validation_errors: result.error.flatten(),
    });
    throw new InjectionSuspectError(correlationId);
  }
  return result.data;
}

Ampersend's implementation with Amazon Bedrock AgentCore Payments illustrates what happens when you take the 'agent as API consumer' model to its financial conclusion: the agent needs to be able to pay for services autonomously, but 'autonomously' can't mean 'without a contract.' The pattern they've built treats the payment as a tool call whose output is a typed payment intent — amount, currency, service identifier, authorization scope — that gets validated against a policy before execution. This is structurally identical to the scoped database query pattern in block_2: the agent declares what it wants to do, the platform validates that declaration against policy, and only then does the side effect happen. Source: [Building pay-per-intelligence for AI agents: How Ampersend uses Amazon Bedrock AgentCore Payments] — AWS Machine Learning Blog (https://aws.amazon.com/blogs/machine-learning/building-pay-per-intelligence-for-ai-agents-how-ampersend-uses-amazon-bedrock-agentcore-payments/)

AIThe broader implication for platform teams is that financial outputs are just the most consequential instance of a general principle: any agent action with an irreversible external side effect — sending an email, writing to a ledger, calling a paid API, triggering a deployment — needs to surface as a typed, inspectable output primitive before it executes, not after. This is where human-in-the-loop design stops being a philosophical position and becomes an engineering requirement. Your output schema needs a 'deferred/requires_human_review' variant (as shown in block_1) specifically because high-stakes actions should pause the pipeline at a decision point rather than proceeding optimistically through a governance gap.

// TypeScript: Payment intent as a typed, policy-gated agent output
import { z } from 'zod';

const PaymentIntentOutput = z.object({
  schema_version: z.literal('1.0'),
  intent_id: z.string().uuid(),
  correlation_id: z.string().uuid(),
  amount_usd_cents: z.number().int().positive().max(10_000), // policy-enforced cap
  beneficiary_service_id: z.string(),
  authorization_scope: z.enum(['single_use', 'session_bound']),
  reason: z.string().max(256),
  requires_human_approval: z.boolean(),
  expires_at: z.string().datetime(),
});

export type PaymentIntentOutput = z.infer<typeof PaymentIntentOutput>;

// Policy gate: runs before the payment rail is called
export async function validatePaymentIntent(
  intent: PaymentIntentOutput,
  policyConfig: { max_auto_approve_cents: number }
): Promise<'approved' | 'requires_human_review' | 'blocked'> {
  if (intent.amount_usd_cents > policyConfig.max_auto_approve_cents) {
    return 'requires_human_review';
  }
  if (!intent.beneficiary_service_id.startsWith('approved:')) {
    return 'blocked';
  }
  return 'approved';
}

The ByteByteGo organizational transformation piece surfaces a tension that's easy to miss when you're deep in schema design: technical contracts between agents and systems are only as reliable as the organizational contracts between teams. If your platform emits a 'deferred' output that requires human approval, but no team has SLA ownership of that approval queue, then your typed schema has created a formal accountability gap — you've made it visible, but you haven't made it owned. The engineering solution is to treat human review queues as first-class infrastructure: give them dashboards, SLOs, on-call rotations, and escalation policies, the same way you'd treat a message queue in a critical async workflow. Source: [AI-Native Leaders: The Organizational Playbook for Engineering Transformation at Scale] — ByteByteGo (https://blog.bytebytego.com/p/ai-native-leaders-the-organizational)

AIThis is where the contract-driven agent pattern completes its loop. The typed output envelope in block_1 gives you the schema. The tool gateway in block_2 gives you the access boundary. The context integrity check in block_3 gives you the security signal. The payment intent gate in block_4 gives you the financial governance point. But all four of those patterns emit events and decision points that need human organizations to act on. The platform engineer's job isn't done when the TypeScript compiles — it's done when the operational runbooks, team charters, and alerting SLOs are in place to handle what the schema surfaces.

// TypeScript: Human review queue as first-class infrastructure with SLO tracking
import { z } from 'zod';

const HumanReviewItem = z.object({
  review_id: z.string().uuid(),
  correlation_id: z.string().uuid(),
  agent_output: z.unknown(), // typed by consumer at read time
  reason: z.string(),
  owner_team: z.string(),
  slo_deadline: z.string().datetime(),
  escalation_policy_id: z.string(),
  created_at: z.string().datetime(),
  status: z.enum(['pending', 'approved', 'rejected', 'escalated']),
});

export type HumanReviewItem = z.infer<typeof HumanReviewItem>;

// Emit to review queue whenever agent output is 'deferred'
export async function enqueueHumanReview(
  envelope: AgentOutputEnvelope, // from block_1 schema
  ownerTeam: string,
  sloHours: number,
): Promise<HumanReviewItem> {
  const sloDeadline = new Date(
    Date.now() + sloHours * 60 * 60 * 1000
  ).toISOString();

  const item = HumanReviewItem.parse({
    review_id: crypto.randomUUID(),
    correlation_id: envelope.correlation_id,
    agent_output: envelope.result,
    reason: (envelope.result as any).reason ?? 'Requires human review',
    owner_team: ownerTeam,
    slo_deadline: sloDeadline,
    escalation_policy_id: `${ownerTeam}-escalation-v1`,
    created_at: new Date().toISOString(),
    status: 'pending',
  });

  // Emit SLO breach check as a scheduled event — not a hope
  await scheduleEscalationCheck(item.review_id, sloDeadline);
  return item;
}