Human-in-the-Loop
How to integrate human-in-the-loop workflows for tool approval
Human-in-the-loop (HITL) workflows allow you to maintain control over critical agent actions by requiring human approval before executing certain tools. This is essential for operations that could have significant consequences, such as database modifications, financial transactions, or external API calls with cost implications.
Overview
When a tool is marked as requiring approval, the agent will pause execution and wait for human approval or denial before proceeding. This creates a checkpoint in the agent’s workflow where human judgment can be applied. The approval workflow is designed to be non-blocking and supports both synchronous and streaming message interfaces, making it suitable for interactive applications as well as batch processing systems.
Key Benefits
- Risk Mitigation: Prevent unintended actions in production environments
- Cost Control: Review expensive operations before execution
- Compliance: Ensure human oversight for regulated operations
- Quality Assurance: Validate agent decisions before critical actions
How It Works
The approval workflow follows a clear sequence of steps that ensures human oversight at critical decision points:
- Tool Configuration: Mark specific tools as requiring approval either globally (default for all agents) or per-agent
- Execution Pause: When the agent attempts to call a protected tool, it immediately pauses and returns an approval request message
- Human Review: The approval request includes the tool name, arguments, and context, allowing you to make an informed decision
- Approval/Denial: Send an approval response to either execute the tool or provide feedback for the agent to adjust its approach
- Continuation: The agent receives the tool result (on approval) or an error message (on denial) and continues processing
Best Practices
Following these best practices will help you implement effective human-in-the-loop workflows while maintaining a good user experience and system performance.
1. Selective Tool Marking
Not every tool needs human approval. Be strategic about which tools require oversight to avoid workflow bottlenecks while maintaining necessary controls:
Tools that typically require approval:
- Database write operations (INSERT, UPDATE, DELETE)
- External API calls with financial implications
- File system modifications or deletions
- Communication tools (email, SMS, notifications)
- System configuration changes
- Third-party service integrations with rate limits
2. Clear Denial Reasons
When denying a request, your feedback directly influences how the agent adjusts its approach. Provide specific, actionable guidance rather than vague rejections:
The agent will use your denial reason to reformulate its approach, so the more specific you are, the better the agent can adapt.
Setting Up Approval Requirements
There are two methods for configuring tool approval requirements, each suited for different use cases. Choose the approach that best fits your security model and operational needs.
Method 1: Default Tool Approval
Set approval requirements at the tool level when creating or updating a tool. This approach ensures consistent security policies across all agents that use the tool. The default_requires_approval
flag will be applied to all future agent-tool attachments:
Method 2: Per-Agent Tool Approval
Configure approval requirements for specific agent-tool combinations, allowing fine-grained control over individual agent behaviors. This method is particularly useful for:
- Trusted agents: Remove approval requirements for well-tested, reliable agents
- Progressive autonomy: Gradually reduce approval requirements as agents prove reliable
- Override defaults: Change the approval setting for tools already attached to an agent
Use the following endpoints to modify approval settings for existing agent-tool relationships:
Handling Approval Requests
Step 1: Agent Requests Approval
When the agent attempts to call a tool that requires approval, execution immediately pauses. The agent returns a special approval request message containing:
- Tool name: The specific tool being called
- Arguments: The exact parameters the agent intends to pass
- Tool call ID: A unique identifier for tracking this specific call
- Message ID: The approval request ID needed for your response
- Stop reason: Set to
"requires_approval"
to indicate the pause state
This format matches the ToolCallMessage format intentionally, so that we can handle approval requests the same way we handle tool calls. Here’s what an approval request looks like in practice:
Step 2: Review and Respond
Once you receive an approval request, you have two options: approve the tool execution or deny it with guidance. The agent will remain paused until it receives your response.
Approving the Request
To approve a tool call, send an approval message with approve: true
and the approval request ID. The agent will immediately execute the tool and continue processing:
Denying with Guidance
When denying a tool call, you can provide a reason that helps the agent understand how to adjust its approach. The agent will receive an error response and can use your feedback to reformulate its strategy. This is particularly useful for guiding the agent toward safer or more appropriate actions: