AI Runbooks Explained: How to Give AI Agents Procedures to Follow

Hello, I'm Rijul. I'm building git-lrc, a micro AI code reviewer that runs on every commit. It's free and source-available on GitHub. Star git-lrc to help more developers discover the project. Do give it a try and share your feedback

If you have read about AI agents, you may have come across the term AI runbook.

You may also have seen people confidently talk about agents handling routine tasks, running commands, investigating issues, and performing actions much like a human engineer would.

But there is an important distinction here:

Just because an agent can use tools does not mean it knows what to do or what procedure to follow.

Think about the difference between an experienced engineer and a new employee joining a team.

An experienced engineer may already know the team's standard procedures.

A new employee might have the technical ability to do the work, but still needs to learn:

• What to check first
• Which tools to use
• What actions to avoid
• How the team normally handles a particular situation

AI agents are similar.

Suppose you tell an agent:

The API is broken. Fix it.

The agent might start investigating broadly.

It could check different files, inspect various configurations, run multiple commands, and try several approaches before figuring out what is actually wrong.

This can lead to:

• Wasted time
• Wasted tokens
• Unnecessary tool calls
• More iterations than necessary

But what if we already had a standard procedure for handling this particular problem?

The agent could follow that procedure and focus its investigation.

That is where AI runbooks come in.

What Is an AI Runbook?

A runbook is simply a documented procedure for handling a specific situation.

For example, suppose an API starts returning HTTP 500 errors.

A runbook might say:

The API is returning 500 errors.

1. Check if the API is running.
2. Inspect the logs.
3. Check the database configuration.
4. Verify that the database is accessible.
5. Make the smallest necessary fix.
6. Verify that the API is working again.

This gives the agent a procedure to follow.

The agent still has to perform the investigation and use its tools.

The runbook simply provides a structure for that investigation.

A Small AI Runbook Demo

To demonstrate this, I created a small task management API using FastAPI and SQLite.

You can also try the demo yourself through my repository

The project contains a runbook for handling API failures:

runbooks/
└── api-500-error.md

Now let's look at the scenario.

First, I start the server.

The API is working correctly.

Next, I intentionally break the application by changing the database path from:

./data/app.db

to:

./data1/app.db

Now, when I call the health endpoint, the API returns an error.

At this point, I ask my AI agent to investigate the issue.

The API is returning HTTP 500 errors.

Please check whether there is a relevant runbook in the runbooks/ directory and follow it.

Diagnose the root cause, make the smallest safe fix, and verify that the API is working again.

Instead of immediately changing application code, the agent can follow the procedure defined in the runbook:

1. Find the relevant runbook.
2. Check the API.
3. Inspect the logs.
4. Check the database configuration.
5. Identify the incorrect database path.
6. Fix the configuration.
7. Verify that the API is healthy again.

The agent still performs the investigation.

The runbook simply gives that investigation a structure.

In this case, the agent finds the root cause and applies the fix.

Prompt vs Runbook

Compare these two instructions.

A simple prompt might say:

Fix the API.

A runbook provides something more specific:

When the API returns a 500 error, check these things in this order.

Avoid making unnecessary changes.

After applying a fix, verify that the API is working again.

The difference is important.

With a simple prompt, the agent has to figure out the entire process by itself.

With a runbook, the agent gets procedural knowledge.

It knows:

• What to check
• In what order to check it
• What actions to take
• What actions to avoid
• How to verify the result

This makes the agent's behavior more predictable.

The Big Idea

AI agents already have the ability to use tools.

They can:

• Read files
• Run commands
• Inspect logs
• Modify code
• Call APIs

But tools only provide capabilities.

A runbook provides a procedure.

That is the key idea behind AI runbooks.

You are not just telling the agent:

Here are some tools. Figure it out.

You are giving it:

Here is how this team normally handles this situation. Follow these steps, use your judgment where necessary, and verify the result when you are done.

That is how you give an AI agent procedural knowledge.

And in many cases, that can lead to a much more predictable outcome than simply giving an agent a vague instruction and hoping it figures out the best approach.

That's it for this introduction to AI runbooks.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

Give it a ⭐ star on Github