Skip to main content

Approval

The Approval class lets you review and respond to tool execution approval requests — listing pending items, approving or denying individually, and processing in bulk.

Listing pending approvals

import agentflow as af

# All pending approvals
pending = await af.Approval.list_pending()

for approval in pending:
    print(f"{approval.tool_name}{approval.status} — args: {approval.arguments}")

Retrieving an approval

approval = await af.Approval.get("appr_abc123")

print(approval.tool_name)       # "send_email"
print(approval.agent_id)        # "agent_456"
print(approval.arguments)       # {"to": "[email protected]", "subject": "..."}
print(approval.conversation_id) # "conv_789"

Responding to approvals

# Approve with a reason
await approval.approve(reason="Looks good, send it")

# Deny with a reason
await approval.deny(reason="Wrong recipient — should be [email protected]")

# Cancel (withdraw the request)
await approval.cancel()

Bulk responses

# Approve or deny multiple approvals at once
await af.Approval.bulk_respond([
    {"id": "appr_001", "action": "approve", "reason": "Approved"},
    {"id": "appr_002", "action": "deny", "reason": "Incorrect parameters"},
    {"id": "appr_003", "action": "approve"},
])

Stats and summaries

# Per-tool approval stats
stats = await af.Approval.get_stats(tool_id="tool_abc123")
print(f"Approved: {stats['approved']}, Denied: {stats['denied']}")

# Dashboard summary across all tools
summary = await af.Approval.get_summary()
print(f"Pending: {summary['pending']}, Total: {summary['total']}")

Properties

PropertyTypeDescription
idstrApproval UUID
tool_namestrName of the tool requesting approval
tool_idstrTool UUID
agent_idstrAgent that triggered the tool call
statusstr"pending", "approved", "denied", or "cancelled"
argumentsdictArguments the tool was called with
conversation_idstrConversation where the tool call originated
created_atdatetimeWhen the approval request was created
expires_at`datetimeNone`When the approval expires (if timeout is set)