How to prepare an IT runbook for an AI agent

Preparing IT runbooks for AI agents starts with making operational instructions explicit: define the goal, required inputs, permitted actions, and success criteria. Give the agent clear boundaries for execution and specific conditions for requesting human help.

An experienced administrator may understand what “check the service and restart if necessary” means. An AI agent needs more context. Which service should it inspect? What indicates failure? Who must approve a restart? Preparing the runbook means answering these questions before execution begins.

Define the task and its boundaries

Choose a narrow, repeatable procedure for your first runbook. AWS recommends starting with a short process whose failures have limited impact.

State the intended outcome, the trigger, and the systems within scope. For example, a runbook might investigate an unavailable internal application on a designated test server.

Clarify exclusions too. If the procedure covers diagnosis only, explicitly prohibit configuration changes. Name the owner who can resolve questions or authorize further work.

Specify inputs, tools, and prerequisites

List the information the agent needs before starting, such as a device identifier, application name, error message, or request number.

Identify the approved tools and explain their purpose, required parameters, and expected results. Clear tool documentation helps agents interact with systems more reliably.

Require the agent to stop when essential information is missing. Avoid instructions that encourage it to guess a target device or substitute another account.

Keep passwords and access tokens outside the runbook. Reference the approved credential mechanism instead.

Turn instructions into explicit decisions

Write each step around an action, an observable result, and the next decision. Replace vague phrases such as “resolve the issue” with specific checks.

For a hypothetical service investigation, the instructions could follow this sequence:

1. Confirm the target server and service name.
2. Retrieve the current service status.
3. If the service runs, collect diagnostic information.
4. If it has stopped, request approval before restarting.
5. Check application availability after the approved restart.

Define what the agent should do when results conflict or a tool returns an error. Include retry limits to prevent repeated actions without progress.

Build approval and escalation into IT runbooks for AI agents

Specify which actions require human approval and who can provide it. Enforce these requirements through the execution platform’s permissions and approval controls, alongside the written instructions.

Tell the agent when to pause, what evidence to collect, and where to escalate. Agent workflows benefit from human checkpoints and clear stopping conditions.

Test outcomes and maintain the runbook

Test the procedure in a controlled environment before production use. Include successful execution, missing inputs, denied approvals, and tool failures.

Verify the operational outcome rather than treating a successful command as proof of resolution. Record actions, results, and unresolved issues.

Assign an owner, track revisions, and review instructions whenever tools or processes change. Ask another administrator to validate the steps.

Hexnode Synapse brings a similar orchestration approach to IT and security operations — agents ground their actions in connected knowledge sources, and per-tool permissions can require human approval before a step like a restart runs, which is exactly the kind of boundary a well-written runbook defines.