What is ask()?
Flow.ask(question, timeout=300) is the lightweight escape hatch when a running flow needs a short string from a human before it can choose the next branch. It emits FlowInputRequestedEvent so whatever input provider you registered — terminal prompt, web modal, queue worker — can satisfy the request without you hand-rolling suspend or resume plumbing. The call blocks the current flow method until a string arrives or the timeout fires, so treat it like a synchronous RPC with a hard deadline.
Contrast this with human_feedback checkpoints: ask is best for one-line clarifications such as region codes, SKUs, or confirmation tokens while human_feedback carries richer payloads, audit metadata, and AMP-style long-lived approvals. Because ask shares the flow execution thread, never nest it under heavy approval flows that can wait hours — those belong behind HumanFeedbackProvider and persisted state.
Pin your provider implementation to the same crewai version you test because event field names and timeout semantics evolve. Log correlation ids when timeouts occur so operators can see which question stalled. Pair ask with explicit defaults in flow state when operators might abandon the prompt so downstream routers still behave deterministically.
Testing ask paths requires a fake provider that immediately returns canned answers so pytest never blocks. In staging, replay recorded FlowInputRequestedEvent payloads to reproduce race conditions between ask timeouts and router transitions. Document expected answer formats so models downstream do not misparse free text into invalid enum transitions. Instrument ask boundaries with metrics around wait time percentiles and cancellation counts so SRE dashboards catch stuck providers before customer traffic degrades.
Use Cases
- • Clarifying questions
- • On-demand input
Key Features
- ✓ Sync API
- ✓ Timeout
- ✓ Provider-agnostic
When NOT to Use
Heavy approval workflows — use @human_feedback for that.
Notes
Blocking vs async hosts
ask blocks the flow method body. In async servers, run the flow under kickoff_async and ensure your input provider awaits external IO without starving the loop — otherwise every concurrent request stalls.
Provider must be registered before kickoff
If nothing listens for FlowInputRequestedEvent, the question never resolves and you burn the full timeout. Smoke-test new providers in CI with a fake responder.
Do not use ask for secrets on shared consoles
The question string and answer path through observability hooks. Prefer dedicated secret channels or masked UI components when collecting credentials.
Retry storms
If upstream logic retries the whole method after a timeout, you may spam operators with duplicate questions. Debounce or persist partial answers in flow state.
Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| question | str | No | What to ask the user. |
| timeout | int | No | Seconds to wait before raising. |
Code Examples
Clarify
answer = self.ask('Which region?', timeout=60)Branch on operator choice
choice = self.ask('Export CSV or JSON?', timeout=120).strip().lower()
if choice.startswith('j'):
self.state.fmt = 'json'
else:
self.state.fmt = 'csv'Short timeout for ops prompts
ans = self.ask('Continue? (y/n)', timeout=30)
if not ans.strip().lower().startswith('y'):
return 'skipped'When to Use
Mid-flow human input.
Common Mistakes
❌ Calling ask() in a tight loop without a timeout
✅ Always set timeout to bound waits.
❌ Using ask() for multi-day legal approvals
✅ Switch to @human_feedback with HumanFeedbackProvider and @persist for durable waits.
Related: @tool decorator reference, Agent class reference, and the first Crew tutorial.
ask() FAQ
What is ask() in CrewAI?
Synchronously prompts the user for input mid-flow with an optional timeout. Flow.ask(question, timeout=300) is the lightweight escape hatch when a running flow needs a short string from a human before it can choose the next branch. It emits FlowInputRequestedEvent so whatever input provider you registered — terminal prompt, web modal, queue worker — can satisfy the request without you hand-rolling suspend or resume plumbing. The call blocks the current flow method until a string arrives or the timeout fires, so treat it like a synchronous RPC with a …
Which CrewAI types expose the method ask()?
DevShelfHub documents ask() on Flow. The reference maps it to Python module crewai.flow.flow.Flow — pin your installed crewai version and match imports to the snippet on this page.
When should I use ask()?
Mid-flow human input.
When should I avoid ask()?
Heavy approval workflows — use @human_feedback for that.
How do I call ask() from Python?
ans = self.ask('Need clarification: ...')
Where can I explore more CrewAI API reference pages?
Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.