Treat the agent contract as versioned infrastructure

A production agent does not have one prompt. It has a request contract: model selection, system instructions, tool schemas, conversation state, retrieved context, output constraints, and runtime permissions. A change to any one of those surfaces can change behavior.

The infrastructure discipline belongs around that complete contract. Version it, test it, deploy it as one unit, and make it possible to roll back.

The system prompt is one layer

System instructions should define stable behavioral policy: role, decision rules, boundaries, and the response behavior that applies across requests. Other capabilities belong to their owning surfaces.

The Anthropic Messages API illustrates the boundary clearly: system is its own request field, while tools is a separate top-level array. Structured output is configured through output_config.format. MCP registration and memory-store paths are runtime concerns; placing prose about them in system does not create either capability.

Version the assembled contract

Store the components separately for review, then bind their versions in one application-owned manifest. The following file is a deployment manifest, not a provider API:

contract: support-agent/v7
provider: anthropic
model: provider-model-id

instructions: prompts/support-agent.md
tools: schemas/tools.json
output_schema: schemas/answer.json
retrieval_policy: config/retrieval.yaml
permission_profile: support-read-only

evaluation:
  suite: evals/support-agent.yaml
  gates:
    schema_valid_rate: 1.0
    critical_policy_rate: 1.0
    task_success_rate: 0.95

The manifest creates a release boundary. A production incident can identify the exact instructions, schemas, retrieval policy, permission profile, and model that generated a response.

Versioning only the Markdown prompt leaves important changes invisible. Renaming a tool argument, changing the retrieval limit, or switching the model can alter behavior without changing one line of system text.

Separate stable policy from request context

Stable system instructions should remain short enough to review as policy. Per-request material belongs later in the assembled context:

This separation improves ownership and cache reuse. It also prevents transient data from becoming an accidental global instruction.

Delimit untrusted content and state how it should be treated. Retrieved documents, web pages, and tool output are evidence, not authority. Higher-priority instructions reduce prompt-injection risk, while tool validation and sandboxing enforce the boundary outside the model.

Treat schemas as part of the prompt contract

Instructions and schemas constrain the same response from different directions. Prose explains semantic intent; a schema defines the machine-valid shape.

If a consumer requires JSON, validate it with the provider’s structured-output surface instead of relying on “return valid JSON” in prose. Keep only semantic rules in the system instructions:

Classify the request using only the supplied account evidence.

- Cite the evidence identifiers that support the decision.
- Escalate when required evidence is missing.
- Never infer an account status from wording alone.

The schema can require decision, evidence_ids, and escalation_reason. The prompt then explains when each value is correct rather than duplicating JSON syntax.

The same rule applies to tools. A tool description explains when the operation is appropriate; its input schema defines valid arguments. Test those two surfaces together.

Build evaluations around failure modes

Snapshot tests against exact prose are weak because model output is not a deterministic template. Evaluate observable contract behavior instead.

Critical safety and schema checks should require a 100% pass rate over the release suite. Quality gates can use an explicit threshold and confidence interval. A threshold such as 95% means something only when the dataset, grader, and sample count are versioned with it.

Deploy with a rollback unit

A safe release path has four artifacts:

1. A contract manifest that pins every behavioral surface.
2. An evaluation report linked to that manifest version.
3. Runtime telemetry tagged with the same version.
4. A rollback that restores the complete previous manifest.

Canary the new contract on a bounded traffic slice. Compare task success, schema validity, tool error rate, escalation rate, latency, and input tokens against the previous version. A prompt that improves one benchmark while doubling tool errors is not a successful release.

Do not mutate a production prompt in a provider console without recording the resulting version in source control. The console may be a useful editor, but it should not become an untracked control plane.

Design the prefix for caching

Anthropic prompt caching follows the request hierarchy: tools, then system blocks, then messages. Reusable content must form a stable prefix; changes before a cache breakpoint invalidate the material that follows.

For a five-minute cache, a cache write costs 1.25 times the base input-token price and a cache hit costs 0.1 times the base input-token price. A one-hour write costs 2 times the base input-token price. Cached input is cheaper, not free.

For N requests that all hit the same five-minute prefix after the first write, the prefix cost is:

1.25 × prefix tokens + (N - 1) × 0.10 × prefix tokens

At 1,000 requests, that is 101.15 prefix equivalents rather than 1,000. The savings depend on real cache hits, request timing, and an unchanged prefix.

Put stable tool definitions and system policy before volatile messages. Measure cache read and creation tokens in production rather than assuming the cache is effective.

Keep secrets and hard enforcement out of the model

System instructions are visible to the provider and can surface indirectly through model behavior. Do not place credentials or private keys in them.

Hard authorization belongs in application code, tool implementations, and the sandbox. The model can decide that a refund is appropriate; the refund tool must still verify identity, limits, and authorization before changing state.

Takeaways