AI Agent Runbook: The Operating Notes Worth Keeping

An AI agent runbook is a short set of operating notes that lets a qualified person who did not build the agent understand what it does, diagnose a problem, pause it and restore it. It covers the agent's purpose, owner, access, normal behavior, known failure patterns, and the exact steps to stop and resume work. If a capable colleague cannot act on it under pressure, it is not finished.

Key takeaways

• A runbook is written for the person on call, not the person who built the agent. It should work without a phone call to the builder.
• Document the pause procedure before anything else. Stopping an agent safely matters more than explaining it elegantly.
• Record what normal looks like, so deviations are visible. A diagnosis guide maps each symptom to a first check.
• Restoring is a separate procedure from fixing. Define what must be true before the agent works unsupervised again.
• A runbook that is not reviewed on a schedule becomes fiction. Tie updates to every change in tools, permissions, instructions or model.

What is an AI agent runbook, and who is it for?

A runbook is the operating manual for a running system. For an AI agent, it answers the questions people ask when something looks wrong: What is this agent supposed to do? What can it touch? How do I tell whether it is behaving normally? How do I stop it? How do I bring it back?

The reader is a qualified person, meaning someone with the right access and general operations skill, but not necessarily the engineer who configured the agent. Think of an operations lead covering a colleague's absence, or an on-call contact at a partner firm. They should be able to act with the runbook open and nothing else.

This is different from the agent's instructions. Instructions tell the agent how to behave. A runbook tells humans how to operate the agent. Keeping the two separate also helps with maintenance, a point covered in how to keep AI agent instructions maintainable. The runbook should describe the instructions (where they live, who may change them), not copy them.

What belongs on the first page?

The first page is a record card. Someone who opens the runbook during an incident should find the essentials without scrolling. Include these items:

• Purpose: one or two sentences on the role the agent performs and the work it explicitly does not perform.
• Owner and backup owner: named people, with how to reach them, and who has authority to pause the agent.
• Channels: where the agent receives requests and where it sends output, such as a shared inbox or a chat workspace.
• Systems and tools: every system the agent reads from or writes to, and which actions are read only, which are proposals and which are direct writes.
• Identity and permissions: the account the agent uses, the scope of its access, and where credentials are managed. Credential storage details belong in your secrets system, not in the runbook, but the runbook says where to look.
• Approval boundaries: the actions that always require a human decision, and who approves them.
• Schedule: any recurring or triggered runs, with their normal timing.
• Dependencies: the model provider, integrations and data sources the agent relies on, with the contact or status page for each.
• Success criterion: the observable sign that the agent is doing its job, as agreed when the role was defined.

The permissions line deserves care. Authorization guidance such as the [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) stresses least privilege and deny by default. A runbook that lists real permissions makes it obvious when an agent has more access than its role needs.

How do you write a pause procedure that anyone can follow?

Pausing is the most important section, because the first goal in an incident is to stop harm, not to understand it. Write it as numbered steps in plain language, and define more than one level of pause, since a full shutdown is not always necessary.

A workable structure has three levels:

• Level one, stop new work: the agent finishes nothing new. Scheduled runs are disabled and incoming requests are held in a queue or routed to a person.
• Level two, stop outward actions: the agent may still read and draft, but sending messages and writing to systems is disabled. Output goes to a review list.
• Level three, cut access: the agent's credentials are suspended or its tool connections are disconnected, so it cannot act even if something else misbehaves.

Then give the steps. Here is a plan you can adapt:

• Step one: confirm you have authority to pause, and note the time and the reason in the incident log.
• Step two: disable scheduled runs and triggers. Name the exact place where each one is controlled.
• Step three: apply the pause level that matches the risk. If the agent may be sending wrong information externally, go straight to level two or three.
• Step four: capture the current state. Save the agent's recent activity, its queue and any half-finished tasks before anything is changed.
• Step five: tell the people affected. Name who must be informed, such as the process owner and anyone waiting on the agent's output, and give a short message template.
• Step six: route the paused work to a human. Say where the pending items go and who handles them in the meantime.

The last step is the one teams forget. Pausing an agent that carries real workload without a manual path just moves the failure somewhere less visible. For how to hand work to a person cleanly, see the principle behind sending the decision, not the mess, in Be Human's thinking on human escalation.

How do you diagnose a misbehaving agent?

Diagnosis needs two things in the runbook: a description of normal, and a map from symptoms to first checks. Normal means the typical volume of tasks, the usual range of completion time, the common outcomes and the usual proportion handled without human help. Write these as descriptions in your own terms, reviewed against real activity, not as guesses. Without a baseline, every odd day looks like an emergency or nothing at all.

The map from symptoms to checks can be a simple list. Each line gives the symptom and the first place to look:

• The agent produces no output: check whether it is paused, whether the schedule or trigger fired, and whether its credentials are still valid.
• The agent produces output but it is wrong or invented: check which source it retrieved from, whether that source changed, and whether instructions or the model were updated recently.
• The agent repeats the same action: check whether a retry loop is running and whether a downstream system is rejecting the action. Your retry policy should say how many attempts are acceptable.
• The agent acts outside its role: check recent changes to permissions or tools, and read the inputs it received for embedded instructions. Documents from outside the company can carry text that tries to steer an agent.
• The agent is slow: check the dependencies' status pages first, then the size of the inputs and the queue.
• The agent asks for human help far more often than usual: check whether a tool failed, a document format changed or a rule became ambiguous.

Diagnosis is only as good as the evidence available. The runbook should state where logs and traces live, how to search them, and what each record contains. Guidance from OpenTelemetry on [observability concepts](https://opentelemetry.io/docs/concepts/observability-primer/) explains why traces, metrics and logs together give a fuller picture than any one alone. Which events to record for an agent is covered in AI agent observability: what should you actually log?.

How do you restore an agent after a pause?

Restoring is not the reverse of pausing. A pause is a fast action. Restoration is a deliberate decision with conditions. Write those conditions down in advance, so nobody resumes the agent just because the pressure to do so is high.

A restoration checklist might read:

• The cause is identified, or the risky capability is disabled so the cause cannot recur.
• Any change made during the incident is recorded, with who made it and why.
• Affected outputs are reviewed, and corrections or notices are sent where needed.
• Half-finished tasks are resolved. Decide for each one whether to resume, redo or cancel. The idea of saved progress is described in AI agent checkpoints: how to resume unfinished work.
• A small set of known test cases is run and the results match expectations.
• The agent restarts at a reduced level first, such as level two with human review of outputs, before full authority returns.
• The named owner approves the return to normal and records it.

If the cause was a model or instruction change, the decision may be to adjust or roll back instead of simply resuming. The runbook should say where previous versions of instructions and settings are stored and who can revert them. The reasoning behind that choice is laid out in AI model update regression testing: adopt, adjust or roll back.

What does this look like in practice?

Here is an illustrative scenario, not a real case. A services firm has an agent that drafts replies to customer scheduling requests and proposes calendar changes for a coordinator to approve. On a Monday, a coordinator notices that several drafts offer times that are already taken.

The coordinator, who did not set up the agent, opens the runbook. The first page confirms the agent has proposal-only access to the calendar, so no wrong bookings can have been written. The coordinator applies level two: drafts are held for review and nothing is sent. The pause steps take a few moments because each control is named.

The diagnosis guide points to wrong or invented output, so the coordinator checks the retrieval source listed on the first page. A shared availability sheet had been reorganized the previous week, and a column the agent relied on had moved. The coordinator records this, asks the owner to fix the source mapping and, in the meantime, routes requests to the manual queue.

For restoration, the owner repairs the mapping, runs the known test cases and brings the agent back with review on every draft for a few days. The log shows who decided what. Nothing in this sequence needed the original builder to be reachable.

How do you keep the runbook accurate, and how does Be Human handle it?

A runbook decays quietly. Tools are added, permissions change, instructions get edited, and the document keeps describing last quarter's agent. Prevent that by making updates part of the work, not a separate chore:

• Update the runbook in the same change that alters a tool, permission, schedule or instruction. No change is complete until the document matches.
• Review it on a recurring schedule, alongside routine maintenance such as the one in a weekly maintenance checklist for managed AI agents.
• After every incident, add the new symptom, the check that found the cause and any step that was unclear.
• Test the pause procedure occasionally with someone who has not used it before, and fix whatever confuses them.
• Keep one current version in one place, with a visible review date and owner.

The NIST [AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) treats ongoing monitoring and clear accountability as part of managing AI systems, and a maintained runbook is a practical form of both.

Be Human designs a runbook as part of each agent's setup, alongside its identity, memory, tools, permissions and approval boundaries. Under managed operations, it is kept current as integrations, permissions or models change, and it is used during monitoring, recurring evaluations, permission reviews and incident response. The company's own named people keep the authority to pause or approve, and the runbook is written so they can use it directly.

Frequently asked questions

How long should an AI agent runbook be? Long enough that the on-call person can pause, diagnose and restore without asking anyone, and no longer. For most single-role agents that means a few pages: a record card, a pause procedure, a diagnosis guide and a restoration checklist. Put detail in linked documents and keep the runbook itself scannable.

Who should own the runbook? The person accountable for the agent's role in the business should own it, with a named backup. Technical contributors write and verify the technical sections, but ownership stays with someone who can decide to pause or resume. Without a named owner, updates stop and the document goes stale.

Does every agent need its own runbook? Yes, though they can share common sections. Two agents may use the same model provider and the same escalation contacts, but they usually differ in permissions, tools and failure patterns. A shared base document with a short agent-specific page for each is a sensible structure.

What is the first thing to write if we have nothing today? Write the pause procedure, then the record card. Those two pieces let someone stop the agent and know what they are stopping. Add the diagnosis guide from your first real incidents, since actual failures teach you more than predictions do.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.