Skip to main content

capabilities.tool_approval

Capability-native async tool approval flow.

When an AgentSpec marks tools as requiring human approval, this module provides:

  1. ToolApprovalConfig — configuration for the approval flow.
  2. ToolApprovalManager — HTTP client that creates approval records in the ai-agents service and polls until resolved.
  3. ToolApprovalCapability — a pydantic-ai AbstractCapability that intercepts tool calls needing approval via before_tool_execute.

ToolApprovalConfig Objects​

@dataclass
class ToolApprovalConfig()

Configuration for the tool-approval flow.

from_spec​

@classmethod
def from_spec(cls, spec_config: dict) -> ToolApprovalConfig

Build from AgentSpec configuration.

Expected structure::

tool_approval:
  tools:
    - "deploy.*"
    - "send_email"
    - "write_file"
  timeout: 300
  poll_interval: 2

ToolApprovalTimeoutError Objects​

class ToolApprovalTimeoutError(GuardrailBlockedError)

Raised when the approval request times out.

ToolApprovalRejectedError Objects​

class ToolApprovalRejectedError(GuardrailBlockedError)

Raised when the tool call is rejected by the human.

ToolApprovalManager Objects​

class ToolApprovalManager()

Manages tool approval requests against the ai-agents service.

requires_approval​

def requires_approval(tool_name: str) -> bool

Check whether a tool requires human approval.

request_and_wait​

async def request_and_wait(tool_name: str,
                           tool_args: dict[str, Any],
                           tool_call_id: str | None = None) -> dict[str, Any]

Create an approval request and poll until resolved.

close​

async def close() -> None

Shutdown the HTTP client.

ToolApprovalCapability Objects​

@dataclass
class ToolApprovalCapability(AbstractCapability[Any])

Capability that gates tool execution behind async human approval.

Uses the ai-agents HTTP service to create approval records and polls until a human approves or rejects the call.

Notes:

For the Vercel-AI transport with DeferredToolRequests enabled, agent creation intentionally filters this capability out to avoid duplicate approval gating. In that flow, approval is handled by deferred tool continuations instead of before_tool_execute polling.