AI Agent Error Messages: Name the Step, the Record and the Next Owner
Write AI agent error messages that name the failed step, the affected record and the owner who acts next. Includes a checklist and example.

An AI agent error message is useful when it tells the responsible person three things: which step failed, which record the agent was working on, and who should act next. A message that reads only 'tool call failed' sends someone into the logs to rebuild the run, and that delay is where duplicate refunds, repeated emails and stalled orders begin. Writing these messages is a design task you finish before the agent touches live work, not a clean-up task after the first incident.
Key takeaways
- Name the failed step in plain business language, not in the internal function name the engineer used.
- Attach the affected record by a stable identifier that a person can search for, and state what condition it is in now.
- Name one owner role for the next action and the single decision that role needs to make.
- Separate failed, blocked and unknown outcomes, because an unknown write is the one most likely to be repeated by mistake.
- Test every message with the person who will read it under pressure, not only with the team that built the tool.
Why most agent errors are hard to act on
An agent usually works as a chain. It reads a request, looks up a customer, checks a policy, drafts an action and writes to a system. When one link breaks, the default output is often a status code or a stack trace written for the developer who built the tool. The operations lead who receives the alert then has to answer questions the message should have answered: was anything sent, did the record change, and is it safe to try again?
Unclear errors carry three costs that matter to a business. Work stops longer than it needs to, people repeat actions the agent may already have completed, and staff stop trusting the agent, so they quietly do the work by hand. Each of these is avoidable with clearer wording and better routing. None of them requires a different model.
The three parts every error message needs
Every message should carry the same parts in plain language. The step names the business action, so 'Looking up the order in the billing system' is more useful than 'get_invoice returned 504'. The record identifies the object with a stable reference such as an order number, ticket number or contract reference. The owner names the role that decides the next move, such as the billing approver or the support lead.
Use this checklist when you write or review a message:
- Step: the business action, described in the words your staff use.
- Record: the stable identifier someone can search for in the source system.
- State: completed, failed cleanly, or unknown, with no guessing.
- Owner: one role that decides the next action, not a shared inbox.
- Decision: the single question that owner must answer.
- Safe next move: what to do now, including what not to do, such as retrying.
Illustrative scenario: an agent drafts a partial refund for order 4471. It reads the order, calculates the amount and sends the request to the payment provider, which does not answer within the allowed wait. A weak message says 'Refund error, timeout.' A usable message says: refund for order 4471 stopped at the payment step, the provider did not confirm, so the refund may or may not exist; do not retry until the billing approver checks the provider record. The second version lets the approver act in one minute instead of an hour.
Separate failed, blocked and unknown outcomes
Three outcomes look alike in a log but need different responses. A failed step received a clear rejection, so the agent can record the reason and stop. A blocked step never ran because a precondition was missing, such as an approval, a required customer field or a closed period. An unknown step started but returned no reliable answer, usually after a timeout, and the external system may have completed the work.
Treat unknown as its own category. Do not label it failed, because a retry could duplicate the action. Where the external system supports it, the agent should send a stable request key so a repeated call can be recognized rather than executed twice. For the timeout pattern in more detail, read Tool Timeouts in AI Agents: Report Unknown, Not Failed.
Route each error to the person who can act
An accurate message sent to the wrong person still wastes time. Decide routing before the first failure, and write it down with the message templates. A practical decision guide looks like this:
- If the agent lacks a permission or credential, route to the system administrator who manages that access, and name the missing permission.
- If the record data conflicts with itself, route to the process owner for that record, and show the conflicting fields side by side.
- If an outside service is unavailable, hold the affected step, let the agent continue unrelated work, and notify operations with the list of waiting records.
- If a write ends in an unknown state, route to the person who can check the external system, and block retries until that person confirms the outcome.
- If the agent repeats the same failure, pause that task and escalate to the operations lead with the run history attached.
Send the decision, not the raw log. The owner should see the question, two or three options and the record, with the full trace one click away. The fallback behavior for each route should be designed in advance, and Fallback paths for an AI agent when a tool fails shows how to define what the agent does while a person decides. The handoff format itself is covered in Human escalation for AI agents: send the decision, not the mess.
How to rewrite your current messages and test them
You do not need a new system to improve messages. You need a short, disciplined pass over the failures you already have.
- Collect a sample of recent failed runs from your logs, including any runs that someone had to fix by hand.
- Group the messages by the underlying problem, so you rewrite the pattern once rather than each instance.
- Rewrite each message with the six checklist fields, using the names your staff already use for customers, orders and teams.
- Ask one person from the owning team to read each message and say, without help, what they would do next. If they hesitate or ask a colleague, the message is not finished.
- Check that no message suggests a retry for an unknown outcome, and that every write-related message names the external system to check.
- Run the revised messages in shadow mode before the agent holds write permissions, so you see real failures without real consequences. The method is described in Run an AI agent in shadow mode before giving it authority.
Keep the revised templates in the same document as the routing guide, so the next engineer who changes a tool updates the message as well.
How Be Human handles this in managed operations
In a managed engagement, Be Human defines the failure categories and the routing rules with your team when the first role is scoped, and writes message templates for each tool the agent uses. Approval boundaries determine which owner receives each class of error, and the logs keep the step name and record identifier so every message can be traced later. Monthly reviews of permissions and incidents check whether the routing still matches who actually holds each decision, and any change to a template is recorded in the operating notes. The goal is that the first person who reads an alert can act on it without reconstructing the run.
Choosing where to start
Start with the workflow where an unclear error currently costs the most time or creates the most duplicate work, because that is where better routing pays back first. Write the six fields for its three most common failures, test them with the people who own the work, and only then widen the scope. If you are unsure which task to hand to an agent first, the free Be Human AI diagnostic is designed to help you find the first task worth handing to an agent.
Frequently asked questions
Should an agent show raw error output to business users? No. The raw output belongs in the trace that engineers use, while the business message should translate it into the step, the record, the state and the owner. Keep the full detail one click away so nothing is hidden during an investigation.
Who should receive agent error alerts? Send each alert to the role that can take the next action, not to a shared inbox that everyone assumes someone else is watching. Some errors belong to a system administrator, others to a process owner or an approver. Set this routing during scoping, and review it whenever permissions or team responsibilities change.
Is it safe to let an agent retry after an error? It depends on the state of the outcome. A clean failure with no side effects can usually be retried within a set limit. An unknown outcome after a write should not be retried until a person confirms the external state, unless the action was designed to be safe to repeat.
How do I know whether an error message is good enough? Ask a person who owns the process to read it without any added context and say what they would do next. If they need to open another tool, ask a colleague or guess whether the action happened, the message needs more of the step, record, state or owner. Repeat this check each time you add a new tool.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


