When Clarifications Happen
The agent asks for clarification when:
- Ambiguous request. Could be interpreted multiple ways
- Missing information. Required details not provided
- Multiple options. Several valid approaches exist
- Safety confirmation. High-impact operations need a thumbs-up first
Clarification Event
{
"type": "clarification_needed",
"question": "What style would you like for your portrait?",
"options": [
"Photorealistic - Natural appearance",
"Artistic - Painterly look",
"Anime - Japanese animation style",
"Cinematic - Movie poster aesthetic"
],
"context": "Each style produces very different results.",
"requires_response": true
}
Common Scenarios
| Scenario | Example Question |
|---|
| Style selection | ”What visual style do you prefer?” |
| Aspect ratio | ”What aspect ratio should the image be?” |
| Video duration | ”How long should the video be?” |
| Edit type | ”What type of edit would you like?” |
| Model selection | ”Which model would you prefer?” |
Responding to Clarifications
Always use the same session_id when responding:
Natural Language (Recommended)
{
"messages": [{"role": "user", "content": "Make it anime style with vibrant colors"}],
"session_id": "my-session"
}
Select an Option
{
"messages": [{"role": "user", "content": "Option 3: Anime"}],
"session_id": "my-session"
}
Provide All Details Upfront
To avoid clarifications entirely, be specific in your initial request:
{
"messages": [{
"role": "user",
"content": "Generate an anime-style portrait, 1:1 aspect ratio, cyberpunk background, neon lighting"
}]
}
Non-Streaming Clarifications
When stream: false, check for clarification_needed: true:
{
"success": true,
"clarification_needed": true,
"question": "What style would you prefer?",
"options": ["Photorealistic", "Artistic", "Anime"],
"session_id": "session_abc123"
}
Behavior Mode Impact
agent mode: The agent makes smart assumptions when possible, and only asks when things are truly ambiguousask mode: The agent always checks in with you before executing anythingplan mode: The agent shows the game plan and asks for your approval
Last modified on March 6, 2026
