Testing, Change, and Release

A production agentic system can change without a code deployment. A provider can retire a model alias. A prompt edit can change tool choice. A retrieval policy can expose different evidence. A Skill, MCP server, sandbox image, policy rule, evaluator, or context-compaction template can alter behavior while the application binary remains the same.

Traditional release discipline still matters: tests, build provenance, deployment automation, staged rollout, monitoring, and rollback. But the releasable unit is larger than an artifact. It is the assembled configuration that shapes model-mediated behavior and the operational claim the organization is willing to support.

This chapter assumes the evaluation evidence, durable execution, security controls, governance decisions, and cost/capacity objectives defined elsewhere in Production Engineering. Its job is to connect them to the mechanics of change.

Thesis

A safe agentic release is a governed transition from one complete system configuration to another. It requires deterministic tests for contracts and invariants, versioned records of every behavior-shaping asset, compatibility checks for stored state and integrations, evaluation evidence for model-mediated behavior, staged exposure with rollback triggers, and a release decision that remains reconstructable after the system changes.

Release safety is not proven by a green build, a better benchmark score, or a model provider’s launch note. Those may be useful evidence. The release decision is stronger only when the team can explain what changed, which claims were tested, which users and effects are exposed, which rollback path is available, and which owner accepted the remaining uncertainty.

Define the releasable configuration

Start every material change with a configuration inventory. At minimum record:

Configuration element	Examples of release-relevant change
Application code and infrastructure	harness logic, orchestration, queues, sandboxes, deployment images, feature flags
Model configuration	provider, model identifier, API version, parameters, routing rules, fallback behavior
Prompts and context rules	system instructions, templates, compaction, retrieval filters, memory inclusion, tool descriptions
Tools and execution boundaries	schemas, argument validation, permissions, idempotency behavior, timeout and retry policy
Policies and guardrails	authorization rules, classifiers, thresholds, block or allow behavior, approval requirements
State and data	schema versions, migrations, memory stores, retrieval indexes, fixtures, cached summaries
Evaluation and test assets	task suites, graders, datasets, harness versions, golden traces, expected outputs
Dependencies and supply chain	SDKs, MCP servers, plugins, Skills, browsers, interpreters, containers, external APIs
Operating controls	observability, alerts, rollout gates, capacity limits, incident playbooks, runbooks

OpenAI’s trustworthy-agent-evaluations article emphasizes that a tested system includes prompts, tools, safeguards, budgets, and environment, not only a model name (OpenAI, 2026). Release records need the same completeness. A behavior change that is invisible to the release process is still a change to the user.

Classify changes by the claims they can invalidate:

• contract change: input, output, schema, authorization, idempotency, or state semantics change;
• behavior change: model, prompt, context, route, tool description, or policy changes expected decisions;
• data change: retrieval corpus, memory, labels, fixtures, or evaluation cases change;
• control change: guardrails, approvals, rate limits, observability, or rollout rules change;
• dependency change: provider, SDK, runtime, browser, tool server, or external API changes; and
• operating change: scale, geography, tenant, workload class, authority, or user population changes.

Not every edit needs a committee. But every material change should leave enough evidence for a future engineer to know what was promoted and why.

Use deterministic tests where determinism belongs

Variable model output is not an excuse for a flaky system. Many release failures are deterministic defects around the model:

• prompt template rendering, required variables, escaping, and length limits;
• schema validation, enum handling, numeric ranges, and structured-output parsing;
• tool argument normalization, authorization, ownership, and state-version checks;
• context-assembly inclusion, exclusion, ordering, redaction, provenance, and budget rules;
• routing eligibility, fallback conditions, timeout paths, and retry budgets;
• execution-boundary behavior for malformed, unauthorized, stale, duplicate, or late requests;
• checkpoint migration, resume compatibility, cancellation, and lease or fencing enforcement;
• telemetry fields, correlation identifiers, audit records, and release labels; and
• failure behavior when a model, evaluator, classifier, tool, or dependency is unavailable.

These tests should be ordinary unit, property, schema, contract, and integration tests. They should run quickly enough to protect everyday changes. They should not call an external model unless the purpose is explicitly integration coverage.

Use fixed fixtures to test the harness. A model transcript captured from a prior run can become a replay input for parsing, state transition, tool selection, and evidence handling. The test does not assert that a future model will produce the same words. It asserts that the deterministic system handles a known input safely.

Keep golden outputs narrow. Exact string comparisons are useful for rendered prompts, JSON schemas, policy records, and migration outputs. They are usually brittle for open-ended prose. For prose and task outcome quality, use the evaluation system’s task, trial, evaluator, and uncertainty machinery rather than hiding semantic judgment inside unit tests.

Test integration at effect boundaries

An agentic system fails at boundaries: identity, data, tools, sandboxes, external APIs, storage, queues, and human approval. Integration tests should exercise the contract, not only the happy path.

For each consequential interface, test:

• valid and invalid arguments, including boundary values and missing fields;
• authorization by principal, tenant, purpose, resource, destination, and current state;
• idempotency keys, duplicate attempts, unknown outcomes, late callbacks, and reconciliation hooks;
• timeout, retry, cancellation, and exhausted-budget behavior;
• partial responses, malformed responses, dependency errors, and degraded mode;
• logging, traces, metrics, audit fields, and sensitive-data redaction; and
• rollback, disable, or kill-switch behavior at that boundary.

Prefer controlled test tenants, service doubles, sandboxes, and replayable snapshots over real external effects. But a double must preserve the semantics that the release depends on. A fake payment API that always succeeds cannot test duplicate-effect prevention. A fake browser with unrestricted network access cannot test egress policy.

Semantic Versioning defines compatibility around a public API and breaking changes (SemVer 2.0.0). Agentic systems need that discipline for tool APIs, schemas, event formats, and external integrations. They also need explicit compatibility for behavior that SemVer does not cover: prompt assumptions, model-router eligibility, context contracts, stored memory, and evaluator interpretations.

Version behavior-shaping assets

Use stable identifiers for every asset that can change behavior. Labels such as latest, default, production prompt, or current policy are not sufficient release evidence.

Record:

• exact model identifier, provider, API version, inference settings, routing and fallback rules;
• prompt templates, tool descriptions, system instructions, context rules, and compaction logic;
• policy and guardrail versions, thresholds, classifier configurations, and failure behavior;
• tool, MCP server, plugin, Skill, sandbox, browser, interpreter, and dependency versions;
• retrieval corpus, memory store, embedding model, index build, filters, and freshness rule;
• state schemas, migration scripts, workflow definitions, checkpoint formats, and event versions;
• evaluation suites, datasets, fixtures, evaluators, rubrics, and gate thresholds; and
• feature flags, exposure rules, rollout cohorts, and exception records.

Provider APIs make versioning explicit in different ways. Anthropic requests carry an API version header and model identifiers that should be recorded with the release candidate (Anthropic API versioning; model overview). OpenAI’s model and evaluation surfaces are likewise product dependencies that should be pinned or identified in release evidence rather than treated as informal background (OpenAI API documentation). Exact provider fields and deprecation dates are volatile; keep them in release records or dated Field Notes when they matter.

Build provenance helps with the software part of the system. SLSA provenance records build metadata such as the artifact, builder, source, and dependencies (SLSA Provenance v1.1). Agentic release provenance should extend that idea to behavior-shaping configuration and evaluation evidence. The point is not bureaucracy. It is the ability to answer, after an incident or regression, “Which system did we actually release?”

Decide compatibility before rollout

Compatibility is a release decision, not a hope. Ask what old and new versions must safely share:

• requests, responses, webhooks, and external API contracts;
• tool arguments and results;
• events, traces, logs, metrics, and audit records;
• database schemas, retrieval indexes, vector stores, caches, and memory records;
• checkpoints, durable timers, in-flight attempts, approvals, and child runs;
• prompts, context fields, citations, summaries, and derived views;
• evaluation tasks and expected evidence; and
• user-visible claims, explanations, controls, and support workflows.

For each changed boundary, choose an explicit path:

Compatibility path	Use when	Risk to manage
Backwards compatible	Old producers or consumers can continue safely	Hidden semantic drift despite unchanged shape
Dual read or dual write	Old and new state must coexist during migration	Divergence, doubled cost, and cleanup failure
Pinned continuation	In-flight work must finish under the old configuration	Provider deprecation, security fixes, and operational complexity
Migrated continuation	Stored work can resume after tested migration	Corrupt state, changed approvals, and stale assumptions
Explicit rejection or escalation	Compatibility cannot be guaranteed	User disruption and manual backlog
Breaking release	The operating claim intentionally changes	Communication, support, and rollback limits

Long-running runs make compatibility concrete. A checkpoint created under one prompt, policy, tool schema, approval scope, and model route may not be safe under another. The release should either pin eligible runs to the old configuration, migrate them through tested code, or stop them with a truthful explanation. Do not silently reinterpret an old approval under a new policy or new target.

Evaluation compatibility matters too. A candidate can appear better because the evaluator, task set, environment, or scoring rubric changed. When the measurement system changes, record whether the release decision compares against a fixed baseline, a migrated baseline, or a new claim.

Assemble release evidence

A release candidate should have a single evidence record. It does not need to be one tool or dashboard, but it should answer the release question without scavenging chat history.

Record:

candidate configuration and immutable identifiers
change summary and material-change classification
affected users, tenants, workloads, data, authority, and integrations
deterministic test results
integration, contract, migration, and replay results
evaluation gate results and known validity limits
security, privacy, capacity, and observability checks
compatibility decision and migration/rollback plan
rollout stages, blast-radius limits, and stop criteria
decision owner, reviewers, exceptions, rationale, and timestamp
monitoring links and post-release review outcome

The Evaluation Systems chapter owns the design of quality gates. This chapter requires their results to be tied to the candidate configuration. Anthropic’s current evaluation article treats automated evals, transcript review, CI, production monitoring, and human review as complementary evidence sources rather than one all-purpose proof (Anthropic, 2026). A release record should preserve that distinction.

Different transitions need different depth:

• a prompt typo in a read-only internal assistant may need smoke tests and sampled review;
• a model route change for a high-volume support agent may need paired evaluations, latency/cost checks, and a canary;
• a new write-capable tool may need security tests, authorization review, idempotency tests, staged exposure, and risk sign-off; and
• a checkpoint schema migration may need restore tests, dual-version resume tests, and a rollback or quarantine plan.

Do not change a gate threshold after seeing a bad result and call it a test update. That is a policy or release decision. Preserve the old evidence, name the new rationale, and rerun any affected comparisons.

Stage exposure deliberately

Progressive delivery reduces blast radius and creates evidence under real conditions. Useful stages include:

Stage	Purpose	Typical guard
Development and CI	Catch deterministic defects and obvious behavior regressions	Unit, contract, migration, replay, and small evaluation suites
Internal dogfood	Expose real use while consequence is limited	Known users, clear feedback path, limited authority
Shadow mode	Compare candidate decisions without committing effects	Read-only execution, no user-visible action, privacy controls
Canary	Expose a small eligible slice to real effects	Tight metrics, fast rollback, limited tenants or workload classes
Staged rollout	Increase exposure after hold criteria pass	Stepwise cohorts, monitoring windows, stop points
General availability	Support the claim broadly	Runbooks, support, capacity, governance, post-release review

Kubernetes Deployments provide one concrete infrastructure example of rollout status, pausing, rolling back, and revision history (Kubernetes). Agentic systems need additional gates because behavior may change through non-deployment configuration. A canary for code is not enough if all traffic already uses a new model alias or prompt through shared runtime configuration.

Feature flags are useful when they are governed. The OpenFeature specification separates flag providers, evaluation context, hooks, and results so flag decisions can be consistent and observable across implementations (OpenFeature). A flag should identify what behavior changes, who is eligible, which evidence justifies widening, when it expires, and how it fails. A stale permanent flag becomes another untested product mode.

Rollout slices should match risk, not convenience. Consider slicing by:

• tenant, user group, geography, language, workload class, and authority level;
• read-only versus write-capable behavior;
• reversible versus irreversible effects;
• low-cost versus high-cost tasks;
• dependency path, model route, context size, and tool set; and
• users with strong support channels before users with weak recourse.

Hold criteria should include positive and negative evidence: accepted-outcome rate, hard policy failures, security denies, correction rate, latency tails, cost per accepted outcome, unknown outcomes, rollback readiness, user reports, support contacts, and incident signals. Activity alone is not evidence of readiness.

Design rollback before needing it

Rollback is a product behavior. It should be designed, tested, and assigned before rollout begins.

For every release, decide:

• what can be disabled immediately through flags, routing, quotas, or kill switches;
• whether the old model, prompt, tool, policy, dependency, and state schema remain available;
• whether new data can be read by the old version;
• what happens to in-flight runs, pending approvals, timers, child work, and unknown outcomes;
• which external effects cannot be undone and which compensation or notification is required;
• how caches, memories, retrieval indexes, and derived summaries are invalidated or quarantined;
• how monitoring confirms rollback stopped the harm; and
• who can order rollback, roll-forward, pause, or partial containment.

Rollback is often incomplete. A bad prompt may have written summaries into memory. A new tool may have sent messages. A migration may have transformed state the old code cannot read. A model change may have created user expectations or support commitments. In those cases the safer path may be roll-forward, quarantine, compensation, or manual review.

Test rollback with the same seriousness as release. Exercise:

• rollback after schema migration;
• rollback while long-running tasks are waiting;
• rollback after a canary created external effects;
• rollback after a guardrail or evaluator changed;
• rollback with a provider unavailable or a model deprecated;
• rollback during overload when queued work is already stale; and
• rollback when the candidate and baseline share corrupted data.

Do not rely on redeploying old code as the only answer. If behavior is controlled by prompts, flags, data, model routes, and provider settings, the rollback procedure must control those too.

Learn from change in production

Release work is not done when exposure reaches 100 percent. Compare expected and observed behavior:

• Did the release affect accepted outcomes, corrections, escalations, incidents, cost, latency, or capacity as predicted?
• Which slices improved, regressed, or lacked enough evidence?
• Did any guardrail, evaluator, test, or alert produce false confidence?
• Were rollback triggers clear and actionable?
• Did feature flags, prompts, and temporary exceptions receive owners and expiry dates?
• Did production failures become new tests, evaluation cases, or release criteria?

Google SRE release-engineering chapters emphasize automation, small changes, gradual rollout, monitoring, and rollback as release-engineering disciplines rather than final paperwork (Google SRE, 2016). DORA’s four key metrics track deployment frequency, lead time for changes, change failure rate, and failed-deployment recovery time (DORA). They are useful release-process signals, but they do not replace AI-specific evidence. A team can deploy quickly and still release ungoverned model behavior.

Track agentic release health with additional measures:

• unversioned prompt or policy edits;
• stale flags and hidden rollout modes;
• releases without complete configuration records;
• in-flight runs blocked by compatibility issues;
• rollbacks that failed because state or provider assumptions changed;
• production failures not added to tests or evaluations;
• exceptions older than their expiry;
• candidate behavior observed outside intended rollout slices; and
• user corrections, appeals, or support issues linked to release changes.

The goal is a change system that learns. Every regression should either improve prevention, improve detection, clarify an accepted risk, or narrow the operating claim.

Trade-offs

Choice	Benefit	Cost or risk
Pin every behavior-shaping asset	Strong reproducibility and rollback evidence	Operational load, provider deprecations, and slower security updates
Use model/provider aliases	Easier updates and less configuration churn	Silent behavior drift and weaker release attribution
Many small releases	Smaller diff and faster diagnosis	More coordination overhead and hidden cumulative drift
Large bundled releases	Fewer ceremonies and easier cross-system coordination	Harder attribution, rollback, and evidence coverage
Strict compatibility requirements	Protects in-flight work and integrations	Slows breaking improvements and migration cleanup
Aggressive staged rollout	Faster learning under real conditions	More user exposure before confidence is strong
Heavy pre-release gates	Fewer known regressions escape	Slow feedback and incentive to bypass gates
Rollback-first strategy	Fast containment for reversible changes	False confidence when state or external effects cannot rewind
Roll-forward-first strategy	Handles irreversible migrations and provider drift	Requires fast diagnosis and strong release engineering

No one cadence fits every system. Match release rigor to consequence, reversibility, exposure, uncertainty, and the organization’s ability to detect and respond.

Failure modes

The invisible prompt release

A prompt changes through an admin screen, improves one demo, and enters production without a version, evaluation run, or rollback path. A later incident cannot be tied to the edit.

The green build around a broken agent

Unit tests pass because they cover only code paths. A tool schema, model route, context rule, or evaluator changed and no integration or behavioral evidence covered the real system.

The benchmark-only promotion

A candidate model scores higher on a general benchmark, but the product’s tool use, latency, refusal behavior, context length, security controls, and target languages were not tested.

The stale feature flag

A canary flag becomes permanent. Years later, one tenant still runs an old prompt and policy combination that no current test or operator understands.

The rollback that cannot read state

A release migrates checkpoints or memories. When behavior regresses, the old version cannot safely resume new runs, so “rollback” creates more failures.

The silent provider change

The system relies on a model alias, SDK default, hosted tool, or external API behavior that changes outside the team’s release record. Operators see drift but cannot reconstruct the candidate.

The unbounded canary

A canary is small by traffic percentage but includes high-authority tasks. One failure creates real external harm before metrics look significant.

The forgotten evaluator change

The team changes a grader prompt and celebrates a release improvement. The system did not improve; the measurement instrument moved.

Fieldbook guidance

1. Treat the release candidate as a complete behavior-shaping configuration.
2. Keep deterministic tests strict for contracts, state, policies, and boundaries.
3. Use evaluation gates for model-mediated behavior and preserve their validity limits.
4. Version every prompt, model route, tool contract, policy, data source, evaluator, and dependency that can change behavior.
5. Decide compatibility for stored state, in-flight work, integrations, evaluations, and user promises before rollout.
6. Stage exposure by consequence and authority, not only by traffic percentage.
7. Define rollback, roll-forward, kill-switch, quarantine, and compensation paths before widening release.
8. Preserve a release record that ties candidate configuration, evidence, decision owners, exceptions, and monitoring together.
9. Feed production failures back into tests, evaluations, guardrails, and release criteria.

Checklist

• Does the release record identify the full candidate configuration, not only code or model name?
• Are prompts, model settings, context rules, tool schemas, policies, evaluators, data sources, dependencies, and flags versioned?
• Do deterministic tests cover schema, authorization, state, migration, replay, logging, failure, and rollback behavior?
• Do integration tests exercise effect boundaries, dependency failure, duplicate attempts, late callbacks, and sensitive-data handling?
• Are evaluation results tied to the exact candidate and baseline configuration?
• Has the team classified material changes and named the claims they can invalidate?
• Is compatibility decided for APIs, stored state, checkpoints, in-flight work, evaluations, and user-visible behavior?
• Are rollout slices, hold criteria, blast-radius limits, and stop triggers explicit?
• Can the team disable, roll back, roll forward, quarantine, or compensate safely for the changed behavior?
• Do observability and incident records carry release and configuration identifiers?
• Are temporary flags, exceptions, pinned versions, and migration paths assigned owners and expiry conditions?
• Will production failures become maintained tests, evaluation cases, or revised release criteria?

References and how they are used

• Anthropic API versioning and models overview - Anthropic-maintained product documentation for Claude APIs and model identifiers, used to show why provider API versions and model identifiers are release inputs that must be recorded. The documentation is product-specific and volatile, so exact deprecation dates and interface details belong in release records or dated Field Notes rather than timeless chapter claims.
• Anthropic, “Demystifying evals for AI agents” - Anthropic engineering article used to support a staged evidence cadence that combines automated evals, transcript review, CI, production monitoring, and human review. It reports provider experience, not an independent release-engineering standard.
• DORA, “DORA metrics: the four keys” - DORA delivery-performance material used for release-process health measures such as deployment frequency, lead time, change failure rate, and recovery time. These metrics do not by themselves prove responsible AI behavior or product quality.
• Google SRE, “Release Engineering” - Google SRE chapter used to support automation, small changes, gradual rollout, monitoring, rollback, and post-release learning as release-engineering disciplines. It comes from large-service reliability practice and is not agent-specific.
• Kubernetes Deployments - Kubernetes project-maintainer documentation used as a concrete example of rollout status, pausing, rolling back, and revision history for deployed application versions. Infrastructure rollout mechanics must be extended with agent-specific checks for prompts, models, state, tools, and evaluation evidence.
• OpenAI, “A shared playbook for trustworthy third party evaluations” - OpenAI research and engineering article used to justify treating the tested and released system as a complete configuration including prompts, tools, safeguards, budgets, and environment rather than a model name alone. The piece focuses on third-party evaluations, so this chapter adapts the configuration principle to release records.
• OpenAI Evals API documentation - OpenAI-maintained API documentation for OpenAI evaluation tooling and model surfaces, used to show that those surfaces are release dependencies whose configuration should be pinned or identified. Product documentation changes over time, so exact API fields should be captured in release records or Field Notes.
• OpenFeature specification - CNCF specification used to ground feature flags in provider, flag, context, hook, and result concepts rather than scattered ad hoc conditionals. The specification supports governed exposure mechanics but does not guarantee safe rollout by itself.
• Semantic Versioning 2.0.0 - public specification used for compatibility language around public APIs, schemas, and tool contracts. SemVer does not cover model behavior drift, prompts, datasets, policies, memories, or evaluator interpretation.
• SLSA Provenance v1.1 - supply-chain specification used as a model for reconstructable build and artifact provenance. Agentic release records need additional fields for behavior-shaping configuration, evaluation evidence, rollout decisions, and operating claims.