Contract-Driven Agents: How to Keep Human and AI Workflows Consistent When They Share the Same Data

The Bayer pharmaceutical research assistant evolved from keyword search into a system that drafts regulatory documents — a domain where the cost of a missing or malformed field in a structured output is measured in months of rework, not a retry. The architectural lesson is that once an agent is generating artifacts that feed regulated human workflows, the output schema is a contract with legal and operational weight, not a convenience. Treating it like an internal implementation detail is how teams end up with agents that pass unit tests but fail in production handoffs. Source: [Building Reliable Agentic AI Systems] — Sarang Sanjay Kulkarni (https://martinfowler.com/articles/reliable-llm-bayer.html)

AIThe pattern that connects this to the broader mixed-autonomy problem is that most teams version their prompts and their models but leave the output schema implicit in downstream parsing code. When you make the schema explicit, versioned, and enforced at the boundary — before a human ever sees the output — you get observability on schema violations as a first-class signal, not a mystery buried in a support ticket.

// TypeScript — Zod contract enforced at agent output boundary
import { z } from 'zod';

const RegulatoryDraftSchema = z.object({
  studyId: z.string().min(1),
  indication: z.string().min(1),
  safetySignals: z.array(z.string()).min(1),
  draftStatus: z.enum(['draft', 'pending_review', 'approved']),
  generatedAt: z.string().datetime(),
  humanReviewRequired: z.boolean(),
});

export type RegulatoryDraft = z.infer<typeof RegulatoryDraftSchema>;

export function enforceAgentOutputContract(raw: unknown): RegulatoryDraft {
  const result = RegulatoryDraftSchema.safeParse(raw);
  if (!result.success) {
    // Emit to observability layer before throwing
    metrics.increment('agent.output.schema_violation', {
      fields: result.error.issues.map(i => i.path.join('.')),
    });
    throw new ContractViolationError(result.error);
  }
  return result.data;
}

The InvokeGuardrailChecks API operates without requiring a pre-provisioned guardrail resource, which removes the infrastructure coupling that previously made inline safety checks expensive to add mid-workflow. The numeric score return — rather than a hard block — is the architecturally interesting part: it means you can design your supervisor node to treat a high-risk score as a human-in-the-loop escalation trigger rather than an automatic rejection, which is exactly the right behavior in mixed-autonomy workflows where context matters. Source: [Safeguard your agentic AI applications with the Amazon Bedrock Guardrails InvokeGuardrailChecks API] (https://aws.amazon.com/blogs/machine-learning/safeguard-your-agentic-ai-applications-with-the-amazon-bedrock-guardrails-invokeguardrailchecks-api/)

AIThe connection to contract-driven design is direct: a safety check is a behavioral contract assertion — it says 'this node's output must not violate these constraints.' The difference from a schema validator is that it evaluates semantics, not structure. Running both in sequence at the same boundary gives you structural and behavioral contract enforcement as a unified layer, which is the governance architecture that mixed-autonomy workflows actually need.

// TypeScript — inline guardrail check at tool-call boundary
import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';

interface GuardrailResult {
  action: 'PASS' | 'ESCALATE' | 'BLOCK';
  scores: Record<string, number>;
}

async function assertSafetyContract(
  client: BedrockRuntimeClient,
  content: string,
  escalationThreshold = 0.7,
  blockThreshold = 0.95
): Promise<GuardrailResult> {
  const response = await client.send({
    // InvokeGuardrailChecks — detect-only, no resource dependency
    content: [{ text: { text: content } }],
    source: 'OUTPUT',
  } as any);

  const scores: Record<string, number> = {};
  let maxScore = 0;

  for (const assessment of response.assessments ?? []) {
    for (const [key, val] of Object.entries(assessment)) {
      scores[key] = (val as any).score ?? 0;
      maxScore = Math.max(maxScore, scores[key]);
    }
  }

  if (maxScore >= blockThreshold) return { action: 'BLOCK', scores };
  if (maxScore >= escalationThreshold) return { action: 'ESCALATE', scores };
  return { action: 'PASS', scores };
}

The observation that the hard part of engineering has moved from writing code to deciding whether to trust it reframes review as the highest-leverage governance checkpoint in an AI-accelerated team. The practical consequence for platform teams is that your review process needs to be contract-aware: reviewers need to know which output schemas, data access patterns, and error contracts are in force for a given service before they can meaningfully evaluate an agent-generated change. Without that shared contract surface, reviews become slow and subjective — reviewers argue style while structural violations slip through. Source: [Agentic Code Review] — Addy Osmani (https://addyosmani.com/blog/agentic-code-review/)

AIThis connects directly to the typed output contract pattern in block_1: if your agent is generating service code alongside data models, the same Zod or Pydantic schema that enforces agent output at runtime can also serve as the review checklist artifact — reviewers verify that generated code reads and writes through the validated types, not around them. That gives you a concrete, non-subjective anchor for review in an agentic workflow.

// TypeScript — contract-aware review checklist generator for agent PRs
interface ContractChecklist {
  schemaAdherence: boolean;
  errorPropagationRespected: boolean;
  dataAccessPatternValid: boolean;
  breakingChangeDetected: boolean;
  notes: string[];
}

async function generateReviewChecklist(
  diff: string,
  schemas: string[],
  adrs: string[]
): Promise<ContractChecklist> {
  const systemPrompt = `You are a contract auditor for a platform engineering team.
  Evaluate the diff against the provided schemas and ADRs.
  Return only a JSON object matching the ContractChecklist interface.
  Flag any implicit contract violations, not just syntax errors.`;

  const userPrompt = `
Schemas:\n${schemas.join('\n---\n')}
ADRs:\n${adrs.join('\n---\n')}
Diff:\n${diff}`;

  const raw = await llm.invoke(systemPrompt, userPrompt);
  return ContractChecklistSchema.parse(JSON.parse(raw));
}

Samsung's real-time pricing architecture exposes a class of data consistency failure that's easy to overlook in agent design: the agent is correct, the schema is valid, but the data it read was already stale by the time it generated the output. The fix — Lambda response streaming combined with CloudFront for aggregation latency reduction — addresses the problem at the infrastructure layer, not the agent layer. For agentic platform engineers, the lesson is that output contracts need to account for the temporal validity of the data that fed the generation, not just the structural validity of what came out. Source: [How Samsung achieved real-time pricing with AWS Lambda Response Streaming] (https://aws.amazon.com/blogs/architecture/how-samsung-achieved-real-time-pricing-with-aws-lambda-response-streaming/)

AIThis pattern surfaces cleanly in Earth AI's nature restoration work as well: the pipeline converts satellite raster data into vector inventories that human landowners act on. If the raster input was captured six months ago, the human makes a conservation decision on outdated ground truth. In both cases — pricing and conservation — the output contract is technically satisfied while the semantic contract with the human decision-maker is violated. Adding a `sourceTimestamp` assertion to your agent output schema is a one-line fix that prevents an entire class of silent governance failures.

// TypeScript — output contract with data freshness assertion
import { z } from 'zod';

const AgentOutputWithFreshnessSchema = z.object({
  payload: z.record(z.unknown()),
  sources: z.array(z.object({
    systemId: z.string(),
    fetchedAt: z.string().datetime(),
    freshnessMs: z.number(),
  })),
  contractVersion: z.string(),
  humanReviewRequired: z.boolean(),
}).refine(
  (data) => data.sources.every(s => s.freshnessMs < 30_000),
  { message: 'One or more data sources exceeded freshness TTL of 30s' }
);

export type AgentOutputWithFreshness = z.infer<typeof AgentOutputWithFreshnessSchema>;

export function attachFreshnessMetadata(
  payload: Record<string, unknown>,
  sources: Array<{ systemId: string; fetchedAt: Date }>
): AgentOutputWithFreshness {
  const now = Date.now();
  return AgentOutputWithFreshnessSchema.parse({
    payload,
    sources: sources.map(s => ({
      systemId: s.systemId,
      fetchedAt: s.fetchedAt.toISOString(),
      freshnessMs: now - s.fetchedAt.getTime(),
    })),
    contractVersion: '1.2.0',
    humanReviewRequired: false,
  });
}

Google's Earth AI framework converts satellite raster maps into vector inventories specifically to create an artifact that humans can interrogate — you can look at a vector polygon and say 'that's wrong, that's a drainage ditch not a hedgerow,' in a way you can't interrogate a raw probability map. That design decision is a contract engineering choice: the team chose a representation that makes the AI's output disputable by domain experts, which is the right architecture for any mixed-autonomy system where a human carries liability for the final decision. Source: [From pixels to planning: Earth AI for nature restoration] (https://research.google/blog/from-pixels-to-planning-earth-ai-for-nature-restoration/)

AIThe pattern here generalizes cleanly: in any domain where an AI agent produces outputs that feed human decisions with real-world consequences, the contract should favor auditability over compression. A structured vector with named attributes beats a confidence score. A Zod-validated regulatory draft with explicit field provenance beats a prose summary. The shape of the contract should make it easy for a human to find the error, not just trust the output.

// TypeScript — ecological feature contract with topology assertions
import { z } from 'zod';

const EcologicalFeatureSchema = z.object({
  featureId: z.string().uuid(),
  featureType: z.enum(['hedgerow', 'copse', 'wetland', 'field_margin']),
  geometry: z.object({
    type: z.literal('Polygon'),
    coordinates: z.array(z.array(z.tuple([z.number(), z.number()]))),
  }),
  areaHectares: z.number().positive(),
  detectionConfidence: z.number().min(0).max(1),
  requiresHumanVerification: z.boolean(),
  captureDate: z.string().datetime(),
}).refine(
  (f) => f.detectionConfidence < 0.85 ? f.requiresHumanVerification === true : true,
  { message: 'Low-confidence detections must be flagged for human verification' }
);

export type EcologicalFeature = z.infer<typeof EcologicalFeatureSchema>;

// Enforce: any feature feeding carbon accounting must pass this contract
export function validateForCarbonAccounting(features: unknown[]): EcologicalFeature[] {
  return features.map((f, i) => {
    const result = EcologicalFeatureSchema.safeParse(f);
    if (!result.success) {
      throw new ContractViolationError(
        `Feature at index ${i} failed carbon accounting contract: ${result.error.message}`
      );
    }
    return result.data;
  });
}