While SuperAGI excels at orchestrating autonomous agent workflows, a common requirement in production scenarios is the need for a human to review and approve certain actions before they proceed. This is particularly critical for operations with side effects, such as deploying code, sending customer communications, or modifying database records. The framework provides a mechanism for this, though implementing a clean, practical approval step requires careful consideration of the tool execution flow.
The core concept involves an agent using a specific tool that pauses its execution and creates an "approval" task. A human (or another agent acting as an overseer) must then manually resolve this task via the SuperAGI UI or API to allow the workflow to continue. The implementation hinges on two primary components: a custom tool that raises an `ToolCallStatus.APPROVAL_WAIT` status, and the configuration of the agent to handle this state.
Here is a minimal example of a custom approval tool. The key is to return the appropriate status and ensure the `approval_message` is clear and contains all necessary context for the human reviewer.
```python
from superagi.tools.base_tool import BaseTool
from superagi.models.tool_config import ToolConfig
from superagi.lib.logger import logger
from superagi.tools.tool_response import ToolResponseStatus as ToolCallStatus
class HumanApprovalTool(BaseTool):
def __init__(self):
super().__init__()
self.name = "Human Approval Tool"
self.description = "Requests human approval before proceeding. Provides context and awaits resolution."
self.args_schema = [
ToolConfig(name="action_context", description="Detailed description of the action requiring approval.")
]
def _execute(self, action_context: str = None):
"""
Executes the approval request.
"""
# Log the context for the audit trail
logger.info(f"[HumanApprovalTool] Approval requested for: {action_context}")
# This return structure is crucial. It signals the framework to pause.
return {
"status": ToolCallStatus.APPROVAL_WAIT.value,
"approval_message": f"Approval required for: {action_context}",
"result": None
}
```
To integrate this into an agent workflow, you must configure the agent to use this tool and properly interpret its response. The primary considerations are:
* **Agent Configuration:** The agent's `resource_summary` or initial prompt should clearly state that certain steps require approval. The tool should be listed in its allowed tools.
* **Workflow Design:** The approval step should be placed strategically in the execution sequence. All data needed for the human's decision must be captured in the `action_context` argument.
* **Approval Resolution:** Once the tool pauses execution, a task appears in the "Approvals" section of the SuperAGI UI. The human reviewer can:
* Approve: The agent resumes, and the tool's execution returns a success status.
* Reject: The agent's execution for that goal is typically terminated.
* Provide feedback: Often, rejection can include feedback sent back to the agent.
A significant trade-off to acknowledge is the introduction of latency and state management complexity. The agent's internal state is persisted while waiting, which is robust but requires consideration for long-running workflows. Furthermore, designing what constitutes an "approvable" unit of work is a system design challenge—too granular, and you create reviewer fatigue; too coarse, and you lose risk mitigation.
For more complex scenarios, such as conditional approvals or multi-stage review chains, you can extend this pattern by having the tool parse the human's feedback upon resumption and branch its logic accordingly. This pattern moves SuperAGI from a fully autonomous executor to a collaborative system where humans retain oversight over critical junctures.
brianh