Agent API Rollout Runbook

Use this runbook for the first Agent API schema rollout, runtime binding, and smoke. The goal is to keep Agent API readiness explicit without turning routine dev or prod deploys into environment-specific recovery workflows.

Before Merge

• Pick an owner and rollout window for the first schema rollout.
• Confirm Dockerfile.prod is still used for Cloud Run deploys and its /app/entrypoint.sh runs python manage.py migrate --fake-initial --noinput before exec "$@" starts Gunicorn.
• Dev deploy runs the workflow definition from main and deploys the branch named in deploy_branch. Prod deploy uses the selected workflow ref or push to main.
• Deploy workflows smoke /system_health/readiness; Agent API smoke is a separate rollout/diagnostic check.
• Do not create runner or smoke ApiClient credentials before API_CLIENT_TOKEN_HASH_KEY is bound in the target runtime.

First Rollout

1. Deploy the branch so Agent API migrations through 0014_unique_execution_lease_idempotency apply.
2. Run scripts/check_agent_api_runtime_config.sh <dev|prod>; it should fail only until the token hash secret binding is applied.
3. Run the Configure Agent API Runtime Config workflow for the target environment and bind API_CLIENT_TOKEN_HASH_KEY to the Cloud Run service and required jobs.
4. Create a read-scope smoke ApiClient in the target database and store its raw token as GitHub environment secret LTI_AGENT_API_SMOKE_TOKEN.
5. Run AGENT_API_SMOKE_TOKEN=<read-scope-token> scripts/smoke_agent_api_runtime.sh <cloud-run-url>.

Runner Smoke

After the schema, runtime secret, and smoke token are in place, prove the runner-write path separately from deploy health smoke:

1. Create or select a pending manual-AI Agentic QA run in LTI.
2. Configure a runner ApiClient with lti:runner:write and start the local console dependency.
3. Run python agent_runtime/runner_bridge.py --once --require-execution.
4. Confirm LTI shows a leased/completed execution, redacted events, and evidence artifacts for that run.

Rollout Checks

• If a token was created before the hash key binding was proven, revoke it and create a replacement only after runtime config passes.
• Re-run /system_health, Agent API smoke, and the runner smoke before ending the rollout window.

Token Rotation

• Create a replacement ApiClient with the same scopes.
• Update the matching GitHub secret or local runner environment with the new raw token.
• Verify smoke or runner lease with the new token.
• Revoke the old ApiClient after the new token is proven.