Agents are useful because they can act autonomously. But autonomy without oversight can be a risky business. Agent approval lets you decide where to draw the line between actions an agent can take on its own and those where a human should be part of the decision.
This post covers how to think about approval in your agent design and how to choose between the different patterns Mastra provides.
The trust spectrum
Not every tool call is risky. A search is harmless. A delete is not. When designing an agent, it helps to think about where each action falls on a trust spectrum:
The further right you go, the more you want a human-in-the-loop. Agent approval exists for cases where you want a human involved before anything happens.
Approval vs suspension
Mastra provides two ways to pause an agent: approval and suspension. They sound similar but they solve different problems.
Approval is gatekeeping. The agent wants to call a tool, and you're asking, can this happen? The answer is yes or no. Use approval when the action is risky and you want confirmation from the user before proceeding.
Suspension is clarification. The tool has enough context to start, but not enough to finish. It pauses execution, returns relevant options to the user, and waits for human input before continuing. Use suspension when the action itself is generally safe, but human input is required to clarify.
You can, however, use both in the same agent. A booking agent might suspend to ask which flight, then require approval before completing a booking and charging the card.
Tool-level vs agent-level
Mastra lets you configure approval at two scopes. On individual tools, or on all agent requests.
Tool-level approval (requireApproval: true on the tool). You mark specific high-risk tools, and only those tools pause for approval. The agent can still call its other tools freely. This works well when you have a mix of safe and unsafe actions.
Agent-level approval (requireToolApproval: true on the request) applies approval to every tool call in that request. Each tool call pauses for approval before executing. This makes sense when the entire operation is risky.
If you’re not sure, start with tool-level approval. It keeps things simple for users, and you can always tighten things up later.
When automatic resumption makes sense
When suspending tool calls you have a choice, manually resume the tool with code, or let the agent resume automatically based on the user's response.
Manual resumption gives you granular control. Your application calls resumeStream() when it's ready, maybe after a button click, or some backend validation. This works well for programmatic flows, dashboards, or anywhere the "resume" action isn't a chat message.
Automatic resumption is conversational. The agent tracks suspended tool calls in memory, and when the user replies, it can work out what to do next and resume automatically. This creates natural a back-and-forth interaction, for example:
1User: "Book me a flight to Tokyo"
2Agent: "Found 3 options. Book the cheapest one?"
3User: "Yes"
4Agent: "Done. Your flight is booked."With automatic resumption there’s no extra code to wire up, it just flows. This works best for low-risk, conversational actions, but it only works if you have memory configured and the user stays on the same message thread.
Designing for approval
If it’s likely your agent will need approval, think about the user experience (UX) early.
Make the ask clear. When approval is required, the user should immediately understand what they're approving. "Delete user john@example.com?", is better than "Tool execution requires approval."
Match the interaction flow. In a chat interface, the approval should feel like a message from the agent. In a dashboard, it might be a modal or an approval queue. If approvals can stack up, you need a way to list and manage them. The pattern should fit how users already interact with your application.
Handle decline gracefully. If the user says no, what happens? The agent should acknowledge the decision and either move on or ask what to do instead.
Approval isn’t just a technical feature, it’s a UX decision. Mastra gives you multiple ways to apply the right level of approval for your situation. With agent approval, there’s no right answer, and as with most things in software development… it depends.
Getting started
For more info about how to configure tools with requireApproval, handle approval chunks in streams, or set up automatic resumption, see our Agent Approval docs.
