Skip to main content

When Clarifications Happen

The agent asks for clarification when:
  1. Ambiguous request. Could be interpreted multiple ways
  2. Missing information. Required details not provided
  3. Multiple options. Several valid approaches exist
  4. Safety confirmation. High-impact operations need a thumbs-up first

Clarification Event

Common Scenarios

Responding to Clarifications

Always use the same session_id when responding:

Select an Option

Provide All Details Upfront

To avoid clarifications entirely, be specific in your initial request:

Non-Streaming Clarifications

When stream: false, check for clarification_needed: true:

Behavior Mode Impact

  • agent mode: The agent makes smart assumptions when possible, and only asks when things are truly ambiguous
  • ask mode: The agent always checks in with you before executing anything
  • plan mode: The agent shows the game plan and asks for your approval
Last modified on March 6, 2026