Skip to main content
Before registry tools, MCP tools, or sub-agent delegation execute, the SDK can pause and wait for human approval. One agent-level policy governs all three paths.

​
Policies

Set with WithToolApprovalPolicy:
PolicyBehavior
RequireAllToolApprovalPolicy{} (default)Every tool call, MCP call, and sub-agent delegation requires approval
AutoToolApprovalPolicy()Nothing requires approval — use only when you fully trust the agent
AllowlistToolApprovalPolicy(config)Listed tools/skills/sub-agents skip approval; everything else still requires it
When you omit WithToolApprovalPolicy, the default is require-all. If your agent has tools registered, every run will pause for approval unless you set a policy. For automated or trusted agents, use AutoToolApprovalPolicy().
approvalPol, err := agent.AllowlistToolApprovalPolicy(agent.AllowlistToolApprovalConfig{
    ToolNames:     []string{"calculator"},
    SubAgentNames: []string{"MathSpecialist"},
    MCPTools:      map[string][]string{"remote": {"search"}}, // optional
})
if err != nil {
    log.Fatal(err)
}

a, err := agent.NewAgent(
    agent.WithToolApprovalPolicy(approvalPol),
    agent.WithApprovalHandler(approvalHandler),
    agent.WithLLMClient(llmClient),
)
Custom tools may implement ToolApproval — the configured agent policy overrides tool-level hints when set. Implement AgentToolApprovalPolicy for fully custom policy logic.

​
Run and RunAsync

Set WithApprovalHandler whenever approvals can occur: 
a, err := agent.NewAgent(
    agent.WithApprovalHandler(func(ctx context.Context, req *agent.ApprovalRequest) {
        // Prompt the user, then:
        _ = req.Respond(agent.ApprovalStatusApproved) // or ApprovalStatusRejected
    }),
    agent.WithToolApprovalPolicy(agent.RequireAllToolApprovalPolicy{}),
    agent.WithLLMClient(llmClient),
)

result, err := a.Run(ctx, prompt, nil)
For RunAsync, use the same handler — resultCh delivers the final result after all approvals complete: 
resultCh, err := a.RunAsync(ctx, prompt, nil)
res := <-resultCh
if res.Error != nil { /* handle */ }
fmt.Println(res.Result.Content)

​
Approval request types

ApprovalRequest.NameParse withFields
Tool approvalParseToolApproval(req)ToolName, AgentName
Sub-agent delegationParseDelegationApproval(req)SubAgentName, AgentName

​
Stream

Approval and delegation requests arrive as AgentEventTypeCustom events on the stream — not via WithApprovalHandler. Parse and respond with OnApproval: 
for ev := range eventCh {
    if ev == nil || ev.Type() != agent.AgentEventTypeCustom {
        continue
    }
    ce, ok := ev.(*agent.AgentCustomEvent)
    if !ok {
        continue
    }
    if v, err := agent.ParseCustomEventApproval(ce); err == nil {
        _ = a.OnApproval(ctx, v.ApprovalToken, agent.ApprovalStatusApproved)
    } else if d, err := agent.ParseCustomEventDelegation(ce); err == nil {
        _ = a.OnApproval(ctx, d.ApprovalToken, agent.ApprovalStatusApproved)
    }
}
For Run and RunAsync, use req.Respond() inside WithApprovalHandler. For Stream, use OnApproval with ApprovalToken from the parsed event — these are two separate paths and cannot be mixed.

​
Sub-agent approval

Parent and specialist agents have independent policies: 
Main agent:  RequireAll  → delegate to MathSpecialist → user approval on main stream
Math agent:  Auto        → calculator inside specialist → no approval
Math agent:  RequireAll  → calculator inside specialist → approval (fan-in on main stream)
The main agent’s policy governs whether delegation itself requires approval. The specialist’s policy governs tool calls inside the specialist. Set each independently.

​
Approval timeout

WithApprovalTimeout (default: agent timeout − 30s) limits how long the user has to respond. If they do not respond in time:
MethodOn timeout
RunReturns error
StreamEmits AgentEventTypeRunError on the channel
RunAsyncresultCh receives AgentRunAsyncResult with Error set
Approval timeout must be less than the agent timeout. See Timeouts & Modes.

​
Example

Tools

approval and authorizer sub-examples

RunAsync

Non-blocking run with approval handler

Tools

ToolAuthorizer for programmatic gates before approval

Sub-agents

Delegation approval flow

Streaming

CUSTOM events and OnApproval

Timeouts

WithTimeout and WithApprovalTimeout