Deployment & Operations — How Agents Actually Run

Every domain so far explained what the pieces are. This page answers the architect's next question: where does this code physically run, who starts it, and how do you assemble it in an enterprise cloud project?

The five runtime forms — recognize which one a scenario implies

The first two run Claude Code itself; the last three run your own harness built on the Claude API or Agent SDK. That's the whole taxonomy — every "how do we ship this?" conversation starts by picking a row.

Headless mode — the agent with nobody at the terminal

Headless means Claude Code running non-interactively: you pass the prompt as an argument, it does the work, prints machine-readable output, and exits. Same engine, same tools, same CLAUDE.md loading — but no human to approve anything, which is why the flags below exist:

claude -p "Triage the new GitHub issues: label severity, close duplicates." \
  --output-format stream-json \
  --allowedTools "Read,Grep,Bash(gh issue:*)" \
  --max-turns 15

• -p (print mode) is the headless switch — prompt in, result out, exit code for the pipeline.
• --output-format json / stream-json makes the output parseable by the calling system (CI step, another program).
• --allowedTools pre-approves: with no human watching, permissions are the gate — pre-approve exactly what the job needs, nothing more. It does not remove other tools; to restrict, add --tools (limits the built-in set), --disallowedTools or permissions.deny rules.
• --max-turns is the budget: a runaway loop in CI burns money silently; the ceiling makes it terminal.

In a CI pipeline it's just a step:

# .github/workflows/triage.yml — an agent as a CI step
on:
  issues: { types: [opened] }
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - run: |
          claude -p "Triage issue #${{ github.event.issue.number }}: apply severity label." \
            --allowedTools "Bash(gh issue:*)" \
            --max-turns 10
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

The API key comes from the pipeline's secret store — never from a file in the repo. This one YAML block is the entire "AI in CI/CD" story the exam gestures at.

The harness as a service — it's just a program

When the agent must serve users or systems (rows 3–5), you deploy your own harness: an ordinary containerized service that happens to call the Claude API. Nothing about it is exotic — it follows the same operational rules as any ordinary web service: config in the environment, logs to stdout, no state baked into the container.

# app.py — the support agent as a plain web service (FastAPI)
# shape-only sketch — production adds auth, a typed/validated request model, size limits, error handling
from anthropic import Anthropic
from fastapi import FastAPI

app = FastAPI()
client = Anthropic()                       # reads ANTHROPIC_API_KEY from the environment

@app.post("/support")
def handle(ticket: dict):
    result = run_agent_loop(client, ticket)   # the Domain-1 loop, verbatim
    return {"resolution": result.text, "state": result.terminal_state}

import os
from typing import Literal

from anthropic import Anthropic
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel, Field

from app.agent import AgentStopped, run_agent_loop  # your loop module
from app.auth import Principal, verify_caller  # your identity-provider check (401 inside)

MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-5")
app = FastAPI()
client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment (secret manager → env)


class Ticket(BaseModel):
    order_id: str = Field(min_length=1, max_length=40)
    message: str = Field(min_length=1, max_length=4000)


class Resolution(BaseModel):
    resolution: str
    state: Literal["resolved", "escalated", "needs_customer"]


@app.post("/support", response_model=Resolution)
def handle(ticket: Ticket, caller: Principal = Depends(verify_caller)) -> Resolution:
    if not caller.can_access_order(ticket.order_id):
        raise HTTPException(status_code=403, detail="Not allowed")
    try:
        result = run_agent_loop(client, MODEL, ticket, trusted_identity=caller)
    except AgentStopped:  # max_tokens, refusal, or iteration limit
        raise HTTPException(status_code=502, detail="The agent could not finish")
    return Resolution(resolution=result.text, state=result.terminal_state)

Containerize it, and every platform question becomes a standard one: where do containers run, where do secrets live, where do logs go. Which brings us to the concrete version.

Deploy an agent as an authenticated cloud service

Yes: deploy the harness as a backend service with an HTTPS API. The caller sends a task to your endpoint; your application authenticates the caller, authorizes the task, and runs or queues the agent loop. The caller does not need to know how the loop is implemented. Any compatible application can integrate, but only callers you authorize should be able to start runs or retrieve results.

Concrete use case: your company hosts an order-support agent on GCP. Your website, another internal service, and an approved partner all need to submit support tasks. The agent runs on Cloud Run and calls the model provider and approved order tools. The example below is architecture guidance, not a deployment performed by this lesson.

Website → website backend ─┐
Internal service ──────────┼→ HTTPS entry + authentication
Approved partner backend ─┘       ↓
                          Tenant/action authorization + quotas
                                  ↓
                          POST /v1/agent-runs
                                  ↓
                          durable run record + queue
                                  ↓
                          Cloud Run worker: harness + agent loop
                                  ├→ model API (server credential)
                                  ├→ approved tools (scoped identity)
                                  └→ checkpoint/results store

Caller → GET /v1/agent-runs/{run_id} → authorized status/result

Three credentials that must not be confused

There may also be credentials for order/refund tools. Permission to start an agent is not permission to refund every order. Carry verified caller/tenant identity into tool authorization; do not let a model-generated customer ID override it.

Choose the entry point for your callers

import requests
from google.auth.transport.requests import Request
from google.oauth2.id_token import fetch_id_token

service_url = "https://YOUR-SERVICE-URL.run.app"
id_token = fetch_id_token(Request(), service_url)
response = requests.post(
    service_url + "/v1/agent-runs",
    headers={"Authorization": "Bearer " + id_token,
             "Idempotency-Key": "support-case-104-attempt-1"},
    json={"task": "Check delivery status", "order_id": "O-104"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

What does a third-party request and response look like?

This is your application API, not the Claude Messages API. The bearer value below is a placeholder for an access token accepted by your gateway/application. It is not necessarily a Cloud Run ID token.

POST /v1/agent-runs HTTP/1.1
Host: agents.example.com
Authorization: Bearer CALLER_ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: partner-case-104-v1

{
  "task": "Check delivery status and explain the next step",
  "order_id": "O-104"
}

Your backend derives identity and tenant from verified authentication records. A body containing "tenant_id": "someone-else" or text saying “I am admin” must not override that identity. A valid token still needs authorization to access O-104.

For a long task, respond after durably accepting work:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/agent-runs/run_7d92

{
  "run_id": "run_7d92",
  "status": "queued",
  "status_url": "/v1/agent-runs/run_7d92"
}

The authenticated caller polls GET /v1/agent-runs/run_7d92. Check tenant/owner access on this endpoint too; knowing a run ID is not permission. A completed response might be:

{
  "run_id": "run_7d92",
  "status": "completed",
  "result": {
    "order_id": "O-104",
    "delivery_status": "delivered",
    "next_step": "Review the delivery photo with the customer."
  }
}

Other states can include running, waiting_for_approval, and failed. Keep status transitions in trusted application state. For short bounded tasks you can return a synchronous answer; for long loops or human approval, persist and queue work rather than keeping a browser request open for hours.

async def create_agent_run(http_request):
    principal = await trusted_authentication.verify(http_request)
    # Verify signature/issuer/audience/expiry or provider session/introspection.
    payload = validate_task_body(await http_request.json())
    authorization.require(principal, "agent.runs.create")
    authorization.require_order_access(principal, payload.order_id)
    quotas.require_available(principal.tenant_id)

    # Atomic run + outbox creation: avoid saved-but-never-enqueued jobs.
    # Idempotency is scoped to tenant + operation; reject changed payload reuse.
    run = await runs.create_with_outbox(
        principal=principal,
        task=payload,
        idempotency_key=http_request.headers["Idempotency-Key"],
    )
    return accepted(run.id)

# Queue delivery invokes a worker; it does not rely on an in-memory background task.
async def process_run(run_id):
    run = await runs.load_and_claim(run_id)
    await resume_agent_loop(run.checkpoint, trusted_identity=run.principal)
    # Authorize each tool action; save checkpoints; honor turn/time/cost limits.

from fastapi import Depends, FastAPI, Header, HTTPException, status
from pydantic import BaseModel, Field

from app.auth import Principal, verify_caller  # JWT signature, issuer, audience, expiry
from app.authz import require, require_order_access  # raise PermissionError when not allowed
from app.quotas import QuotaExceeded, require_available
from app.runs import runs  # durable store: run row + outbox in one transaction

app = FastAPI()


class RunRequest(BaseModel):
    task: str = Field(min_length=1, max_length=2000)
    order_id: str = Field(pattern=r"^O-\d+$")


@app.post("/v1/agent-runs", status_code=status.HTTP_202_ACCEPTED)
async def create_agent_run(
    body: RunRequest,
    idempotency_key: str = Header(alias="Idempotency-Key", max_length=100),
    caller: Principal = Depends(verify_caller),
):
    try:
        require(caller, "agent.runs.create")
        require_order_access(caller, body.order_id)
    except PermissionError:
        raise HTTPException(status.HTTP_403_FORBIDDEN, "Not allowed")
    try:
        require_available(caller.tenant_id)
    except QuotaExceeded:
        raise HTTPException(status.HTTP_429_TOO_MANY_REQUESTS, "Quota exhausted")
    run = await runs.create_with_outbox(
        principal=caller, task=body, idempotency_key=idempotency_key)
    return {"run_id": run.id, "status": "queued", "status_url": f"/v1/agent-runs/{run.id}"}

What gets deployed on GCP?

1. Build a container: HTTP entry point plus harness code and dependencies. Listen on the platform’s configured port. The model runs at its provider unless you separately choose self-hosted inference.
2. Deploy Cloud Run: assign a dedicated runtime service account and explicit invocation policy. Add a gateway/user-auth layer if serving partners or users.
3. Configure credentials: put production model credentials in Secret Manager with access only for the runtime identity; use workload identities for Google service access.
4. Persist and queue: store runs/checkpoints/results in a database or object storage; use a durable task/queue system for asynchronous work. Do not depend on container memory or local disk surviving.
5. Bound and observe: set concurrency/scaling and application budgets, apply per-tenant quotas, record traces without tokens/secrets, and handle duplicate delivery safely.

Interview wording: “I deploy the harness as a containerized API service. I authenticate callers with an identity provider or Cloud IAM, authorize tenant and action access, then create a durable agent run. A worker executes the loop with scoped tool permissions and server-held model credentials. Clients receive a run ID and access results through authenticated endpoints.”

Reference architecture — the support agent on GCP

The Domain-1 walkthrough's support agent, deployed for real on Google Cloud:

flowchart TD
  U[Customer email / chat] --> GW[API Gateway / webhook endpoint]
  GW --> PS[Pub/Sub topic: support-tickets]
  PS --> CR[Cloud Run: the harness container]
  SM[Secret Manager: ANTHROPIC_API_KEY] -.mounted at startup.-> CR
  CR -->|HTTPS: model calls| CAPI[Claude API — api.anthropic.com]
  CR -->|tool calls| SQL[(Cloud SQL: orders DB)]
  CR -->|tool calls| MCP[MCP server: internal customer-records CRM — Cloud Run service]
  CR --> LOG[Cloud Logging → BigQuery: traces, tokens, gate verdicts]
  SCH[Cloud Scheduler: nightly] --> EV[Eval job: golden set vs staging]
  EV --> LOG
  HITL[Approval queue: escalations UI] --- CR

The same shape on any cloud

The names change; the topology — queue in front, stateless harness container, secret store, single allowlisted egress, traces out — does not. (Amazon Bedrock (AWS) and Vertex AI (Google Cloud) — each cloud's own managed model service — add a variation: Claude is called through the cloud's endpoint instead of directly to api.anthropic.com — same harness, different base URL and cloud-IAM authentication (the cloud's own Identity and Access Management, instead of an Anthropic API key).)

Enterprise assembly checklist — what the architect signs off

1. Identity & secrets: API keys in the secret store, rotated; one service account per tool backend, least-privilege each.
2. Egress control: the harness can reach the Claude API and its tool backends — and nothing else. This single network rule is your strongest defense against exfiltration (smuggling data out): even a prompt-injected agent has nowhere to send it (Domain 3's layer 3, at the network layer).
3. Budgets as infrastructure: max-turns/cost ceilings in the harness AND platform quotas (Cloud Run concurrency, spend alerts) — two independent layers.
4. Observability first-class: per-run traces with correlation ids landing in a queryable store before launch, not after the first incident.
5. Evals in the deploy path: golden set green = deployable; a config/prompt/model change that can't turn the suite red proves nothing (Domain 5's negative controls).
6. HITL has a real surface: escalations land in a queue humans actually monitor, with an SLA — an unmonitored approval queue is a silent-failure machine.

🪤 Trap: "we need GPUs to deploy the agent" — no. Inference runs on Anthropic's side of the Claude API; your side is an ordinary container that makes HTTPS calls. The trap answer provisions infrastructure for a problem you don't have; the architect answer is the checklist above.