# RUNBOOK.md

> Give operators a tested path from alert to diagnosis, containment, rollback, recovery, communication, and follow-up using the signals and failure modes of the complete agent workflow.

**Decision rule:** Write a runbook for failures that require timely coordinated action or specialized diagnosis. Keep routine automatic recovery in the system and record its limits here.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Service ownership and dependencies

> Make the operating boundary and escalation path available before an incident.

- **Owners:** <List primary, secondary, security, data, product, and vendor contacts>
- **Dependencies:** <List models, tools, queues, databases, auth, providers, and critical limits>
- **Environments:** <List production, staging, regions, release identifiers, and access procedure>

## Signals and diagnosis

> Connect every alert to a workflow stage, user impact, and known failure mode.

- **Service indicators:** <Define completion, correctness, safety, latency, cost, and availability signals>
- **Dashboards and traces:** <Link workflow, model, tool, queue, authorization, and business views>
- **Diagnostic sequence:** <List the fastest read-only checks and evidence to preserve>

## Containment and recovery

> Provide exact reversible actions with authority and stop conditions.

- **Contain:** <Define feature disablement, permission revocation, queue pause, isolation, and traffic controls>
- **Rollback:** <Define code, configuration, prompt, model, schema, and data rollback>
- **Recover:** <Define validation, replay, reconciliation, re-enable order, and customer remediation>

## Communication and learning

> Keep stakeholders informed and convert failures into maintained controls.

- **Updates:** <Define internal, user, vendor, legal, and regulatory communication owners and cadence>
- **Closure evidence:** <State the signals and reviewers required to close the incident>
- **Follow-up:** <Add eval cases, tasks, architecture decisions, documentation, and owner deadlines>

## Related AgentAtlas field guides

- [Deployment and operations](https://agentatlas.dev/topics/deployment-operations)
- [Observability](https://agentatlas.dev/topics/observability)
- [Human approval](https://agentatlas.dev/topics/human-approval)

## Primary references

- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls.
- [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) — Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry.
- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.