Agent CI/CD must version behavior, policy, and state as one release

Agent CI/CD must version behavior, policy, and state as one release. A container digest is necessary, but it is not the deployable identity of an agent system. Behavior emerges from code, model binding, prompt and tool definitions, retrieval data, policy, evaluator versions, and the meaning of persisted state. Promoting only the image creates a release record that cannot explain what users actually experienced.

I treat an agent release as a compatibility set. It names the harness code, model and routing configuration, system instructions, tool schemas, policy bundle, state schema, evaluation dataset, and gate thresholds that were approved together. Some members can be immutable artifacts; others can be pointers to immutable versions. What matters is that the release resolves them all and that a production run records the resolved set rather than whichever “latest” values happen to exist during investigation.

This changes the pipeline. Unit tests still guard deterministic code and schemas. Integration evaluation then exercises representative trajectories against a pinned dataset. Shadow deployment sends real inputs through the candidate without serving its responses. Canary rollout exposes a small share of live traffic while monitoring quality, cost, latency, escalation, and containment. Full promotion proceeds in stages only when those gates hold. Evals are the contract, so the exact evaluator and dataset version belong to the evidence for the release.

State is the hard boundary. An agent may resume a plan, approval, memory, or pending external effect created by an older release. New code can parse the bytes while changing their meaning. A renamed tool, narrower policy, different prompt, or new termination rule may make the old checkpoint unsafe to continue. Agent state needs migration semantics because rollout and rollback both cross this boundary. The release needs an explicit answer: migrate, preserve a versioned reader, drain old work, or declare the state disposable.

Policy cannot float independently either. If a candidate behavior passes evaluation under one permission set but production resolves another, the evidence is invalid. The same applies to tool registries and retrieval indexes. A tool description change can redirect selection; a policy change can turn a previously blocked path into an allowed one; an index refresh can alter grounding without any code commit. Those are releases because they change behavior, even when no image is built.

Rollback therefore means restoring a compatible set, not pointing traffic at yesterday’s binary. The old code may require an old prompt, policy, tool contract, and state reader. In-flight work may need to finish on the release that started it while new work routes elsewhere. Durable execution supplies the run identity and checkpoints; release management supplies the compatibility promise under which they remain meaningful.

There is one precise concession: a stateless, read-only agent with no persistent memory, external effects, dynamic policy, or mutable retrieval source can use a much narrower release unit. Code, prompt, and model binding may be enough. The wider contract becomes necessary as soon as the system carries state across versions or can act under changing authority.

GitOps fits agents when Git records declarations rather than pretending one repository commit contains the whole runtime truth. I want a release manifest that can reconstruct a run, a gate record that can justify promotion, and a rollback plan that preserves state meaning. Agent CI/CD is reliable when “what changed?” has one answer across behavior, policy, and state.