AI Architecture Pattern 02: Prompt And Context Contract

It worked. Then someone else touched it.

Pattern 01 gave us a grounded RAG assistant that explains payment status using trusted, read-only context. One team built it end to end — the transaction data, the policy retrieval, the answer format — so nothing ever had a chance to drift. It just worked.

Then the dispute-handling team wanted in.

They wired their dispute-status data into the same assistant, because why build a second one? Their payload looked reasonable: a transaction ID and a status. But the original prompt template also expected payment_method and policy_hint — fields the dispute team never knew existed, because nothing ever wrote them down as required.

The result wasn’t a graceful error. It was a KeyError, thrown from deep inside a Python f-string, with a stack trace that told the dispute team nothing about which field was missing or why it mattered.

This is Pattern 02: Prompt And Context Contract.

The pattern in one sentence

Treat every prompt’s inputs and outputs as a versioned contract — validate before you render, validate before you return — so an integration mismatch becomes a clear, actionable error instead of a silent failure two teams deep.

What I built

Same payment-support assistant, same synthetic transaction data as Pattern 01. The new piece is a contract layer sitting in front of the prompt:

flowchart TB
    U[Customer or Support Agent] --> UI[Web or Support Portal]
    UI --> API[AI Assistant API]
    API --> ASSISTANT[Contract-Aware Assistant]
    TXN[Transaction Data Team] --> ENVELOPE[Context Envelope]
    DISPUTE[Dispute Data Team] --> ENVELOPE
    ENVELOPE --> ASSISTANT
    ASSISTANT --> GETCONTRACT[Get Prompt Contract Version]
    REGISTRY[(Bedrock Prompt Management)] --> GETCONTRACT
    GETCONTRACT --> VALIDATEIN[Validate Input Against Contract]
    VALIDATEIN -->|Fails| VIOLATION[Return Contract Violation]
    VALIDATEIN -->|Passes| RENDER[Render Prompt Template]
    RENDER --> LLM[LLM]
    LLM --> VALIDATEOUT[Validate Output Against Contract]
    VALIDATEOUT -->|Fails| VIOLATION
    VALIDATEOUT -->|Passes| RESPONSE[Structured Response With Contract Version]
    RESPONSE --> UI
    VIOLATION --> UI

The contract itself (PromptContractVersion) is a small, immutable dataclass: a template string, a list of typed input fields, a list of typed output fields, and a version number. It’s grounded in Amazon Bedrock Prompt Management — checked directly against AWS’s official docs before writing this: real Bedrock gives you named-variable templates ({{variable}} syntax) and numbered, immutable versions, created via a real two-step flow (CreatePrompt makes a mutable draft, CreatePromptVersion snapshots it). What real Bedrock does not give you is any check that a variable is required or correctly typed — it just substitutes placeholders. The required-field/type validation in this pattern is engineering built on top of that primitive, not a Bedrock feature. This pattern’s code ships a local mock of the real API (BedrockPromptManagementClient) so you can run the whole thing with zero AWS credentials, then swap in boto3 later without touching the validation logic at all.

What broke, and why

Without a contract, the call site looked like this (using Bedrock’s real {{variable}} syntax):

render_template(template, variables)
# where template contains: "...{{payment_method}}...{{status}}..."

Nothing here declares what variables is supposed to contain. The dispute team’s payload —

{ "transaction_id": "txn_disputed_card_004", "status": "dispute_open" }

— crashes with KeyError: 'payment_method', and that’s the best failure mode. A slightly different template might have silently substituted an empty string instead and shipped a broken sentence to a customer.

With a contract, the same payload is checked before anything renders:

{
  "type": "contract_violation",
  "answer": "I cannot answer because the supplied context does not match the prompt contract.",
  "reason": "payment_method: Required input field is missing from the supplied context.; policy_hint: Required input field is missing from the supplied context.",
  "next_step": "Fix the calling code to supply every required field, or use a contract version that matches what this caller actually has.",
  "contract_version": 1
}

That’s an error the dispute team can actually act on — no debugger required.

Fixing it for real: a new version, not an edit

The fix isn’t to patch the original template in place. It’s to author a new contract version that explicitly adds the dispute fields as optional inputs:

def build_v2_contract(client):
    client.create_prompt(
        contract_id=CONTRACT_ID,
        template=(
            "Explain the {{payment_method}} payment status '{{status}}' for transaction "
            "{{transaction_id}} to the customer in one short paragraph. If a dispute is open, "
            "mention dispute reference {{dispute_reference}} and its stage {{dispute_stage}}. "
            "Cite policy: {{policy_hint}}"
        ),
        input_fields=[
            # ...the original four fields, plus:
            ContractField("dispute_reference", "string", required=False),
            ContractField("dispute_stage", "string", required=False),
        ],
        output_fields=[...],
    )
    return client.create_prompt_version(CONTRACT_ID)

That’s create_prompt (write the draft) followed by create_prompt_version (snapshot it) — two calls, matching how Bedrock actually separates “still editing” from “locked in for production.”

Version 1 keeps working for any caller that hasn’t migrated. Version 2 is what the dispute team’s integration actually uses. The diff between the two versions is the changelog — visible, reviewable, and attributable, instead of a silent edit buried in a prompt string somewhere.

Not just banking

The payments story is one concrete face on a general problem. Swap “dispute team” for any second caller of a shared prompt and the failure looks the same:

• Support-ticket triage bot — a billing-system integration sends tickets without the priority field the routing prompt assumes. Without a contract: mis-routed tickets or a crash. With one: a named error, fixed at the integration boundary.
• Healthcare intake assistant — a new clinic’s form omits allergy_list, a field the original clinic always populated. A contract forces that gap to be an explicit decision (required or defaulted), never a silent omission.
• E-commerce order-lookup chatbot — a marketplace-seller integration doesn’t send warehouse_id, a field only your in-house fulfillment system ever populated. A new contract version adds it as optional, and those orders take a fallback path instead of failing.
• HR onboarding bot — a contractor-onboarding flow reuses the employee-onboarding prompt, but contractors don’t have a manager_id at hire time. Two contract versions, both live at once, solve it without breaking either flow.

The mechanics are identical every time: validate before you render, and add a version instead of editing one out from under someone.

More than one way to build this

This isn’t the only way to enforce a contract on AWS. What we built — Bedrock Prompt Management — gives immutable versions and an audit trail, called by ARN, with no per-version charge. AWS API Gateway’s own request validators are a real AWS-native alternative, but they solve a different problem: they reject a malformed payload at the gateway, before it ever reaches Lambda or Bedrock — genuinely useful, but with no concept of a prompt template or a v1-versus-v2 history the way Prompt Management has.

If you’re already using Pydantic or Instructor elsewhere in your codebase, both have real, current, actively-maintained Bedrock support — but that support is documented by the libraries themselves (Pydantic AI’s Bedrock model docs), not by AWS. No AWS blog, docs page, or workshop names either library specifically. Three real options, three different jobs — this series builds the AWS-managed one because that’s what it teaches, not because the others are wrong.

There’s also a second AWS-native production path worth naming: Jinja2 templates stored in S3, rendered locally in Lambda, with Bedrock Converse called against a plain model ID instead of a prompt-version ARN. Rollback here means pointing at a different S3 key instead of an env-var ARN swap — you own the version storage and the rollback logic yourself, which is the right trade if you want zero cloud-service dependency on the prompt layer, or portability across clouds. validate_input() is identical either way; only where the template itself lives changes.

The wider contract-enforcement field, honestly mapped (6 real options, 2 built):

Bedrock Guardrails and API Gateway validators are listed for completeness, not as competitors — they enforce different surfaces (what the model is allowed to say, and malformed payloads at the edge, respectively) than this pattern’s input/output contract.

A newer, related AWS tool — and why it’s not on the table above

AWS shipped an Advanced Prompt Optimization and migration tool in the Bedrock console in May 2026: give it a prompt, example inputs, ground-truth answers, and an evaluation metric, and it runs your original prompt against an AWS-optimized rewrite across up to five models side by side — reporting which version wins on quality, cost, and latency (multimodal inputs supported too).

It isn’t in the table above because it answers a different question than every option there. Every row in this pattern’s field is about contract shape and versioning — is the required field present, is it the right type, which version is a caller pinned to. Advanced Prompt Optimization never touches shape or versioning at all — it’s asking whether the prompt’s wording is actually good, holding shape constant. You could run it against either version of this pattern’s contract template and it would tell you nothing about whether payment_method was required — that’s not its job.

Genuinely useful, worth a closer look — just a different pattern’s question, not this one’s. (AWS News Blog · What’s New, 2026-05)

What it actually costs

Prompt Management itself adds zero cost on top of the model’s own token rate — the same Nova Micro default as Pattern 01.

When to use this pattern

• More than one team or service calls the same prompt or assistant.
• The input shape is expected to change over time as new data sources get added.
• Downstream systems — UI, audit logs, support routing — depend on specific output fields always being present.
• A silent wrong answer would genuinely be worse than an immediate, clear error.

When not to use this pattern alone

A presence-and-type check catches “the field is missing” and “the field is the wrong type.” It does not catch “the field is present, correctly typed, and still wrong” — that’s Pattern 03: Structured Output And Validation, the very next step in this series. It also doesn’t judge whether the answer itself is good — that’s Pattern 04: Evaluator Optimizer.

Who’s using this in the real world

This isn’t a made-up problem, and versioned contracts aren’t new — they’re how real companies keep multiple callers on one API without breaking anyone.

Stripe has maintained backward compatibility with every API version it’s shipped since 2011, using date-based versioning: new callers get the latest version, existing integrations stay pinned to whichever version they started on. Old code never breaks on an upgrade. (stripe.com/blog/api-versioning)

Twilio Segment’s Protocols product validates every event against a JSON Schema “tracking plan” and can block malformed events outright — and its Event Versioning feature lets multiple teams run different schema versions side by side via an explicit version key on each event. Same mechanism, different domain. (twilio.com/docs/segment/protocols/tracking-plan/create)

Honest note: a published customer case study specifically for Bedrock Prompt Management’s versioning feature wasn’t found at the time of writing — the mechanism above (Stripe, Segment) is the same idea proven at scale in adjacent systems, not an AWS-specific customer story yet.

Try it yourself

Full code, tests, and diagrams: patterns/02-prompt-and-context-contract in the ai-series-demo repo.

git clone https://github.com/narenmak17/ai-series-demo.git
cd ai-series-demo/patterns/02-prompt-and-context-contract
python -m unittest discover -s tests
python -m app.demo

No AWS account, no API keys, no cost. Eight tests, all green, in under a millisecond.

What’s next

Pattern 03: Structured Output And Validation keeps the same single LLM call but turns the output side into something that must validate against a real schema — not just “is the field there,” but “is the field shaped correctly.” If Pattern 02 was about catching a missing field before it crashes a format string, Pattern 03 is about catching a malformed answer before it reaches a customer.

Have questions or feedback? Drop a comment below or connect on LinkedIn.