Deployment Walkthrough

This walkthrough turns a lab-derived agent into a production candidate. It is framework-agnostic: the same gates apply whether the implementation uses direct TypeScript, Python, LangGraph, AutoGen, Mastra, CrewAI, or a custom mini-runtime.

Download the deployment walkthrough review checklist before using this chapter for a release review.

For complete examples, use the Capstone Projects after this chapter.

The goal is not to deploy faster. The goal is to deploy with enough control that the team can inspect, stop, replay, and improve the system after real users arrive.

Scope

Use this walkthrough for systems that can read private data, call tools, write memory, send messages, create drafts, execute workflow steps, or influence business decisions.

For throwaway demos, keep the process lighter. For production, do not skip the gates that match the system’s authority.

Deployment Readiness Questions

Use these questions before promoting a lab, pattern implementation, or capstone into a service:

The release is not ready when the only proof is “the demo worked.” It is ready when a second engineer can deploy, inspect, stop, and replay it.

Release Pipeline

Use this diagram as the deployment control path. A production agent release needs local evidence, eval gates, canary observation, rollback controls, and incident-to-eval feedback.

1. Local Development

Local development should prove the runtime contract before cloud infrastructure exists.

Required local evidence:

Suggested local commands:

npm test
npm run typecheck
npm run book:build

For Python framework variants, add the project-specific virtual environment, install, test, and eval commands to the lab README.

2. Configuration And Secrets

Configuration should make deployment behavior explicit without exposing secrets.

Use these environment groups:

Rules:

• commit .env.example, not .env;
• keep secrets in the deployment platform’s secret manager;
• fail startup when required secrets are missing;
• log which configuration version loaded, not secret values;
• treat prompt, model, tool, policy, and eval versions as release inputs.

3. Persistence And Checkpointing

Persistence depends on authority. A read-only answer can often be stateless. A workflow that waits for approval, retries tools, or creates side effects needs durable state.

Choose the minimum persistence boundary that supports recovery:

Checkpoint every externally visible step:

1. accepted request;
2. planned action;
3. policy decision;
4. approval request or approval result;
5. tool call attempt;
6. side-effect result;
7. final response;
8. eval or post-run quality result.

Retries should read the checkpoint and decide whether to continue, compensate, or stop. They should not replay side effects blindly.

4. Observability Export

Agent observability must explain one run and aggregate many runs.

Export these events:

Do not store raw secrets, credentials, payment data, or private content unless the retention policy explicitly allows it. Prefer references to encrypted records when raw content is not needed for debugging.

5. Eval Gate In CI

CI should block risky changes before deployment.

Tie eval subsets to change type:

A minimal CI gate should run:

npm test
npm run typecheck

Add project-specific eval commands next to the implementation. The gate should fail closed: if the eval dataset cannot load, the release should stop.

GitHub Actions Gate

A minimal GitHub Actions workflow should separate ordinary tests from release-blocking agent checks.

name: agent-release-gate

on:
  pull_request:
  workflow_dispatch:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run typecheck --if-present
      - run: npm run eval:release --if-present
      - run: npm run trace:contract --if-present

For Python agents, add setup-python, dependency install, unit tests, and eval commands. Keep production secrets out of pull-request jobs. CI should use synthetic fixtures, mock tools, redacted traces, and staging credentials only when explicitly approved.

The release gate should publish a small evidence summary: commit SHA, eval dataset version, passed checks, failed checks, trace contract result, and release owner. A green CI badge is not enough when the agent can call tools or affect users.

6. Rollout

Roll out by capability, not by hope.

Use stages:

1. local run with deterministic fixtures;
2. staging run with synthetic data;
3. internal run with read-only authority;
4. limited tenant or cohort;
5. expanded traffic with dashboards and alerts;
6. full release after trace and eval review.

At each stage, record:

• release version;
• model and prompt version;
• tool schema version;
• policy version;
• eval dataset version;
• trace export status;
• rollback owner.

Rollout Decision Flow

Use this flow at each rollout stage. The goal is to make expansion a decision based on evidence, not a default next step.

7. Rollback And Kill Switch

Every production agent needs a fast disable path.

Define kill switches at several layers:

Rollback should not require a code deploy for common failures. Tool disablement, model rollback, prompt rollback, and policy tightening should be operational controls.

8. Production Runbook

Create a runbook before launch.

Minimum runbook:

service:
owner:
on-call:
runtime:
framework:
release:
model versions:
prompt versions:
tool registry:
policy version:
memory stores:
checkpoint stores:
trace dashboard:
eval dashboard:
known failure modes:
rollback command:
kill switch:
incident channel:
post-incident eval process:

The runbook should link to the framework selection ADR, production readiness worksheet, eval suite, and deployment dashboard.

9. Concrete Runtime Path

Use this path when a lab or capstone becomes a service. It keeps framework code behind product-owned contracts.

Minimum service contract:

POST /runs
input: actor, tenant, task, request payload, idempotency key
output: run_id, trace_id, status, response or escalation
side effects: none before policy, approval, and idempotency checks

For queue or workflow deployments, keep the same contract even if transport changes. The request envelope, state record, trace ID, policy decision, and eval result should look the same across HTTP, worker, and scheduled jobs.

10. Cloud Deployment Shapes

Different cloud shapes can host the same agent contract. Pick the simplest shape that preserves state, policy, traces, and rollback.

Cloud deployment should not change the agent’s authority model. If a local run requires approval before sending email, the cloud worker must require the same approval. If the local trace redacts tool arguments, the cloud trace must redact them too.

11. Research RAG Deployment Notes

Research RAG systems need extra deployment controls because retrieval can expose forbidden, stale, or unsupported material.

Required runtime controls:

Deployment sequence:

1. deploy retrieval in read-only mode;
2. compare retrieved candidates with source-filter output;
3. enable answer synthesis for internal users only;
4. gate release on citation faithfulness, forbidden-source omission, and stale-source rejection;
5. add dashboards for missing evidence, stale-source hits, forbidden-source attempts, and citation failures;
6. keep a kill switch that disables synthesis and returns approved source lists only.

This path connects directly to the Research RAG Agent capstone and the native LangGraph slice under native-framework-examples/langgraph-research-rag/.

Framework-Specific Deployment Notes

Complete When

The system is deployable when:

• local setup is reproducible;
• secrets and config are separated;
• persistence matches authority;
• traces are exported and redacted;
• evals block risky changes;
• rollout stages are documented;
• rollback works without code changes for common failures;
• the runbook names owners, dashboards, and incident actions.

Until then, the system may be useful, but it is not production-ready.