Deploy Your First Agent
What a deploy of an agent ships, the nine steps in three phases, one running example (SupportBot v7) and the checklist that says each step is done; the six pages that teach the steps.
Last updated
After this section you can
- Name the seven release units an agent deploy ships and the two that change without one
- Map each of the nine steps to the page that teaches it and the artifact it produces
- Define the running example and the numbers every later page in this part derives from it
Deploy Your First Agent
What a deploy of an agent ships, the nine steps that make it safe to run, and the checklist that says each step is done.
A deploy ships seven things, not one, and two more change without a deploy at all. Nine steps take SupportBot from a function to a service you can roll back; this page is the order, and each step lives on its own page.
Each box is one step and the test that says it is done; the checklist links each one to its page.
Seven release units; two more change without a deploy
| Unit | What breaks | How often |
|---|---|---|
| Code | Crashes, endless loops, unbounded cost | Weekly, through CI |
| Prompt | Quality drops with no error | Hourly to weekly, by a domain expert |
| Tool definitions | The agent takes actions it should not | Rarely, and versioned |
| Secrets | An outage, or a leaked key | On rotation or after an incident |
| State store | Amnesia on restart; runs cannot resume | Every run writes to it |
| Observability | No way to say why it answered | With each new metric or dashboard |
| Runtime | Fine for a few users, fails under load | When the platform or the load changes |
| Model version | Answers change; a retired model fails | When you change it, or the vendor retires it |
| Knowledge index | Fluent answers from stale documents | When the source documents change |
Cadences are typical engineering practice, not measurements.
A release unit is one part that changes on its own clock, with its own owner and rollback. The last two rows change without a deploy: a model version is a setting, and the knowledge index is the search index over your documents.
One unit welds the fastest lever to the slowest process: a copy change then waits for review, CI and a release.
Both still change answers, so both go through the eval gate: a fixed set of test cases that a change must pass before release.
Who asks what. The product manager asks which tasks the agent may attempt and what success rate ships. The site reliability engineer (SRE) asks which alert fires before a customer complains.
One running example, with its numbers fixed
- Run
- one user request, question to final answer, with every model and tool call in it.
- FAQ path
- one call to the cheap tier, the smallest current model (
claude-haiku-5-5), answered from the knowledge base, with no tool. - Action path
- a loop of calls to the main tier (
claude-sonnet-5-5) that uses tools to change something. - Digest
- the content hash of one built image. A tag can move to another image; a digest cannot.
- Grace period
- how long a platform waits for in-flight work before it stops a replica in a rollout.
Model names as of 2026-10-08. The tier names stay; check the model table on the day you build.
SupportBot v7 is the v6 pipeline from Your First Agentic System with two tools, lookup_order and create_refund_request, in a loop capped at 8 steps. v6 is a function: a question in, a string out, and no tools. The loop is what makes it an agent.
Later pages derive their numbers from these two paths; a volume that is not SupportBot's is labelled as an input. The action path's p99 of 75 seconds is a design input.
Three phases: each one unlocks the next
- Make it run Steps 0 to 2. A service with a contract and a trace id on every log line, packaged as one image. Service and Container covers steps 1 and 2.
- Make it survive Steps 3 to 5. Secrets leave the code, the runtime survives a killed replica, and run state leaves the process. Config and Secrets, Where It Runs and The Run Ledger cover steps 3, 4 and 5.
- Make it safe to change Steps 6 to 8. One digest per release, an eval gate on every change, and a rollback you have run before launch. Promotion and the Eval Gate covers steps 6 and 7; The First 24 Hours covers step 8.
Each phase unlocks the next. A service that keeps its state in process memory cannot run on a second replica, and a run is lost when its replica is replaced mid-run. Without a gate and a rollback, every change is a gamble.
Once the product runs, four service levels watch it: task success, p95 time to answer, escalation rate and cost per resolved task. Day-2 Operations owns them.
The checklist: done means a test you can run
| Step | Done when | Read it in |
|---|---|---|
| 0 · Seven units a list, with owners | Someone can name who changes the prompt | This page |
| 1 · Service app with probes and a drain | A request returns an answer and a trace id | Service and Container |
| 2 · Image Dockerfile and compose file | A colleague starts it with one command | Service and Container |
| 3 · Config settings and secret references | No secret in the repo; boot fails without a key | Config and Secrets |
| 4 · Runtime deploy contract and manifests | It survives a replica killed mid-request | Where It Runs |
| 5 · State runs and steps tables | Rate limits hold when a second replica runs | The Run Ledger |
| 6 · Environments the promotion ladder | A promotion changes one digest | Promotion and the Eval Gate |
| 7 · Pipeline CI with the eval gate | A prompt that lowers the eval score cannot merge | Promotion and the Eval Gate |
| 8 · Launch dashboards, alerts, rollback | You have run the rollback once | The First 24 Hours |
A step that fails its row's test is not done, however green the build. Tools to buy are in Agent Tech Stack; what to measure is in Metrics & Dashboards.
- Calling the container image the deploy. The image is one of seven units.
- Keeping the prompt in the code, so every copy change waits for a release. A prompt registry fixes it: Deployment & Rollout.
- Skipping step 5 because the demo works. One replica with state in memory looks fine until the second replica.
“What does a deploy of an agent ship, and which part changes without one?”
Seven things: the code, the prompt, the tool definitions, the secrets, the state store, the observability and the runtime. Two more change with no deploy: the model version and the knowledge index. Lead with the split: one unit welds the fastest lever to the slowest process.
The trap is answering “the container image”, which is only one of the seven.
A product manager wants to reword the refund language in the system prompt on Friday. Which release unit is that, and what must it not require?
The prompt unit. It needs no code change, image or runtime release. It still passes the eval gate and gets a version, so a bad wording rolls back to the last version.
The image is green and the pods are healthy, yet the deploy changed nothing a user can see. Name two units that did not ship, and how you would notice.
The prompt and the tool definitions: the deploy carried code, and their versions stayed put. Compare those versions on recent runs, before and after the deploy.
Your team finished steps 0 to 4 and says the agent is deployed. What does step 5 protect that the first five do not, and when would you first notice its absence?
Step 5 keeps run state outside the process, so a replaced replica takes no run with it. You would first notice its absence at the first rolling restart or scale-out, when a run stops mid-task. Stateless vs Stateful explains why; Agent Durability covers resumes that must not repeat a refund.
- Seven release units ship with a deploy; the model version and the knowledge index change without one, and both still need the eval gate.
- SupportBot v7 is v6 plus two tools in a loop of at most 8 steps: a FAQ is one cheap-tier call, an action a loop of main-tier calls.
- Nine steps in three phases, each with one done test; after step 8, Day-2 Operations owns the four service levels.