Human-in-the-Loop

By default, API runs are fully autonomous — the agent completes the task without pausing for input. Enable human_in_the_loop=True for workflows where you want the agent to pause and ask for human decisions.

Quick Start

How It Works

human_in_the_loop is the master switch for all interactive features. permission_mode selects the specific behavior:

When the agent needs human input, the run status changes to awaiting_approval. After you respond, it returns to running.

Clarifying Questions

The simplest interactive pattern — the agent asks multiple-choice questions during execution.

Enable

Answer Questions

Poll the run status and respond when the agent asks:

The answers dict maps the question text to the selected option label. For custom answers not in the multiple-choice list, pass your free-text response as the value.

Tool Approval

The agent pauses before sensitive tool calls for human review.

Enable

Approve or Deny Tools

Remember Decisions

Pass remember=True to auto-approve the same tool in future runs:

Pre-Approve Tools

Skip the approval step for known-safe tools:

Now when runs for cust_123 use approval mode, Slack and Linear calls are auto-approved. See Permissions for full details.

Plan Mode

The agent creates an execution plan, then waits for approval before acting.

Enable

Approve or Revise

Approve the plan using the answer endpoint:

To reject or revise, pass feedback text instead of "Approve" — the agent will create a new plan based on your feedback.

Task Runs

All the same options work with task execution:

Production Integration

Webhook-Driven Approval

Use webhook events to build an approval UI instead of polling:

1. Register for run.awaiting_input webhook events
2. When the webhook fires, check the run for pending permissions or questions
3. Show the request details to your user
4. Call the appropriate endpoint (approve for tools, answer for questions/plans)

Timeout Behavior

If no human responds within 75 seconds, the run status changes to awaiting_approval and pauses. It resumes automatically when you submit a response — no time limit on the pause.

What's Next

• Permissions — pre-approve tools and manage policies
• Runs & Follow-ups — run execution and follow-up messages
• Streaming & Events — real-time event streaming
• Webhook Events — get notified when runs need input