Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Implement user input handling in Flows (#4490)
João Moura84d57c7a2461
diff --git a/lib/crewai/src/crewai/cli/reset_memories_command.py b/lib/crewai/src/crewai/cli/reset_memories_command.pyindex 5d3d73de9..85971f94f 100644--- a/lib/crewai/src/crewai/cli/reset_memories_command.py+++ b/lib/crewai/src/crewai/cli/reset_memories_command.py@@ -2,7 +2,30 @@ import subprocessimport click-from crewai.cli.utils import get_crews+from crewai.cli.utils import get_crews, get_flows+from crewai.flow import Flow+++def _reset_flow_memory(flow: Flow) -> None:+ """Reset memory for a single flow instance.++ Handles Memory, MemoryScope (both have .reset()), and MemorySlice+ (delegates to the underlying ._memory). Silently succeeds when the+ storage directory does not exist yet (nothing to reset).++ Args:+ flow: The flow instance whose memory should be reset.+ """+ mem = flow.memory+ if mem is None:+ return+ try:+ if hasattr(mem, "reset"):+ mem.reset()+ elif hasattr(mem, "_memory") and hasattr(mem._memory, "reset"):+ mem._memory.reset()+ except (FileNotFoundError, OSError):+ passdef reset_memories_command(@@ -12,7 +35,7 @@ def reset_memories_command(kickoff_outputs: bool,all: bool,) -> None:- """Reset the crew memories.+ """Reset the crew and flow memories.Args:memory: Whether to reset the unified memory.@@ -29,8 +52,11 @@ def reset_memories_command(returncrews = get_crews()- if not crews:- raise ValueError("No crew found.")+ flows = get_flows()++ if not crews and not flows:+ raise ValueError("No crew or flow found.")+for crew in crews:if all:crew.reset_memories(command_type="all")@@ -59,6 +85,20 @@ def reset_memories_command(f"[Crew ({crew.name if crew.name else crew.id})] Agents knowledge has been reset.")+ for flow in flows:+ flow_name = flow.name or flow.__class__.__name__+ if all:+ _reset_flow_memory(flow)+ click.echo(+ f"[Flow ({flow_name})] Reset memories command has been completed."+ )+ continue+ if memory:+ _reset_flow_memory(flow)+ click.echo(+ f"[Flow ({flow_name})] Memory has been reset."+ )+except subprocess.CalledProcessError as e:click.echo(f"An error occurred while resetting the memories: {e}", err=True)click.echo(e.output, err=True)diff --git a/lib/crewai/src/crewai/cli/utils.py b/lib/crewai/src/crewai/cli/utils.pyindex b73f9f76b..6ee181ea1 100644--- a/lib/crewai/src/crewai/cli/utils.py+++ b/lib/crewai/src/crewai/cli/utils.py@@ -386,6 +386,109 @@ def fetch_crews(module_attr: Any) -> list[Crew]:return crew_instances+def get_flow_instance(module_attr: Any) -> Flow | None:+ """Check if a module attribute is a user-defined Flow subclass and return an instance.++ Args:+ module_attr: An attribute from a loaded module.++ Returns:+ A Flow instance if the attribute is a valid user-defined Flow subclass,+ None otherwise.+ """+ if (+ isinstance(module_attr, type)+ and issubclass(module_attr, Flow)+ and module_attr is not Flow+ ):+ try:+ return module_attr()+ except Exception:+ return None+ return None+++_SKIP_DIRS = frozenset(+ {".venv", "venv", ".git", "__pycache__", "node_modules", ".tox", ".nox"}+)+++def get_flows(flow_path: str = "main.py") -> list[Flow]:+ """Get the flow instances from project files.++ Walks the project directory looking for files matching ``flow_path``+ (default ``main.py``), loads each module, and extracts Flow subclass+ instances. Directories that are clearly not user source code (virtual+ environments, ``.git``, etc.) are pruned to avoid noisy import errors.++ Args:+ flow_path: Filename to search for (default ``main.py``).++ Returns:+ A list of discovered Flow instances.+ """+ flow_instances: list[Flow] = []+ try:+ current_dir = os.getcwd()+ if current_dir not in sys.path:+ sys.path.insert(0, current_dir)++ src_dir = os.path.join(current_dir, "src")+ if os.path.isdir(src_dir) and src_dir not in sys.path:+ sys.path.insert(0, src_dir)++ search_paths = [".", "src"] if os.path.isdir("src") else ["."]++ for search_path in search_paths:+ for root, dirs, files in os.walk(search_path):+ dirs[:] = [+ d+ for d in dirs+ if d not in _SKIP_DIRS and not d.startswith(".")+ ]+ if flow_path in files and "cli/templates" not in root:+ file_os_path = os.path.join(root, flow_path)+ try:+ spec = importlib.util.spec_from_file_location(+ "flow_module", file_os_path+ )+ if not spec or not spec.loader:+ continue++ module = importlib.util.module_from_spec(spec)+ sys.modules[spec.name] = module++ try:+ spec.loader.exec_module(module)++ for attr_name in dir(module):+ module_attr = getattr(module, attr_name)+ try:+ if flow_instance := get_flow_instance(+ module_attr+ ):+ flow_instances.append(flow_instance)+ except Exception: # noqa: S112+ continue++ if flow_instances:+ break++ except Exception: # noqa: S112+ continue++ except (ImportError, AttributeError):+ continue++ if flow_instances:+ break++ except Exception: # noqa: S110+ pass++ return flow_instances++def is_valid_tool(obj: Any) -> bool:from crewai.tools.base_tool import Tooldiff --git a/lib/crewai/src/crewai/events/types/flow_events.py b/lib/crewai/src/crewai/events/types/flow_events.pyindex 826722762..3eea1bbdd 100644--- a/lib/crewai/src/crewai/events/types/flow_events.py+++ b/lib/crewai/src/crewai/events/types/flow_events.py@@ -120,6 +120,52 @@ class FlowPlotEvent(FlowEvent):type: str = "flow_plot"+class FlowInputRequestedEvent(FlowEvent):+ """Event emitted when a flow requests user input via ``Flow.ask()``.++ This event is emitted before the flow suspends waiting for user input,+ allowing UI frameworks and observability tools to know when a flow+ needs user interaction.++ Attributes:+ flow_name: Name of the flow requesting input.+ method_name: Name of the flow method that called ``ask()``.+ message: The question or prompt being shown to the user.+ metadata: Optional metadata sent with the question (e.g., user ID,+ channel, session context).+ """++ method_name: str+ message: str+ metadata: dict[str, Any] | None = None+ type: str = "flow_input_requested"+++class FlowInputReceivedEvent(FlowEvent):+ """Event emitted when user input is received after ``Flow.ask()``.++ This event is emitted after the user provides input (or the request+ times out), allowing UI frameworks and observability tools to track+ input collection.++ Attributes:+ flow_name: Name of the flow that received input.+ method_name: Name of the flow method that called ``ask()``.+ message: The original question or prompt.+ response: The user's response, or None if timed out / unavailable.+ metadata: Optional metadata sent with the question.+ response_metadata: Optional metadata from the provider about the+ response (e.g., who responded, thread ID, timestamps).+ """++ method_name: str+ message: str+ response: str | None = None+ metadata: dict[str, Any] | None = None+ response_metadata: dict[str, Any] | None = None+ type: str = "flow_input_received"++class HumanFeedbackRequestedEvent(FlowEvent):"""Event emitted when human feedback is requested.diff --git a/lib/crewai/src/crewai/flow/__init__.py b/lib/crewai/src/crewai/flow/__init__.pyindex 2e31d9220..ec4a3ac5e 100644--- a/lib/crewai/src/crewai/flow/__init__.py+++ b/lib/crewai/src/crewai/flow/__init__.py@@ -7,6 +7,7 @@ from crewai.flow.async_feedback import (from crewai.flow.flow import Flow, and_, listen, or_, router, startfrom crewai.flow.flow_config import flow_configfrom crewai.flow.human_feedback import HumanFeedbackResult, human_feedback+from crewai.flow.input_provider import InputProvider, InputResponsefrom crewai.flow.persistence import persistfrom crewai.flow.visualization import (FlowStructure,@@ -22,6 +23,8 @@ __all__ = ["HumanFeedbackPending","HumanFeedbackProvider","HumanFeedbackResult",+ "InputProvider",+ "InputResponse","PendingFeedbackContext","and_","build_flow_structure",diff --git a/lib/crewai/src/crewai/flow/async_feedback/providers.py b/lib/crewai/src/crewai/flow/async_feedback/providers.pyindex e86c0a747..65055d650 100644--- a/lib/crewai/src/crewai/flow/async_feedback/providers.py+++ b/lib/crewai/src/crewai/flow/async_feedback/providers.py@@ -1,7 +1,8 @@-"""Default provider implementations for human feedback.+"""Default provider implementations for human feedback and user input.This module provides the ConsoleProvider, which is the default synchronous-provider that collects feedback via console input.+provider that collects both feedback (for ``@human_feedback``) and user input+(for ``Flow.ask()``) via console."""from __future__ import annotations@@ -16,20 +17,23 @@ if TYPE_CHECKING:class ConsoleProvider:- """Default synchronous console-based feedback provider.+ """Default synchronous console-based provider for feedback and input.This provider blocks execution and waits for console input from the user.- It displays the method output with formatting and prompts for feedback.+ It serves two purposes:++ - **Feedback** (``request_feedback``): Used by ``@human_feedback`` to+ display method output and collect review feedback.+ - **Input** (``request_input``): Used by ``Flow.ask()`` to prompt the+ user with a question and collect a response.This is the default provider used when no custom provider is specified- in the @human_feedback decorator.+ in the ``@human_feedback`` decorator or on the Flow's ``input_provider``.- Example:+ Example (feedback):```pythonfrom crewai.flow.async_feedback import ConsoleProvider-- # Explicitly use console provider@human_feedback(message="Review this:",provider=ConsoleProvider(),@@ -37,9 +41,20 @@ class ConsoleProvider:def my_method(self):return "Content to review"```++ Example (input):+ ```python+ from crewai.flow import Flow, start++ class MyFlow(Flow):+ @start()+ def gather_info(self):+ topic = self.ask("What topic should we research?")+ return topic+ ```"""- def __init__(self, verbose: bool = True):+ def __init__(self, verbose: bool = True) -> None:"""Initialize the console provider.Args:@@ -124,3 +139,55 @@ class ConsoleProvider:finally:# Resume live updatesformatter.resume_live_updates()++ def request_input(+ self,+ message: str,+ flow: Flow[Any],+ metadata: dict[str, Any] | None = None,+ ) -> str | None:+ """Request user input via console (blocking).++ Displays the prompt message with formatting and waits for the user+ to type their response. Used by ``Flow.ask()``.++ Unlike ``request_feedback``, this method does not display an+ "OUTPUT FOR REVIEW" panel or emit feedback-specific events (those+ are handled by ``ask()`` itself).++ Args:+ message: The question or prompt to display to the user.+ flow: The Flow instance requesting input.+ metadata: Optional metadata from the caller. Ignored by the+ console provider (console has no concept of user routing).++ Returns:+ The user's input as a stripped string. Returns empty string+ if user presses Enter without input. Never returns None+ (console input is always available).+ """+ from crewai.events.event_listener import event_listener++ # Pause live updates during human input+ formatter = event_listener.formatter+ formatter.pause_live_updates()++ try:+ console = formatter.console++ if self.verbose:+ console.print()+ console.print(message, style="yellow")+ console.print()++ response = input(">>> \n").strip()+ else:+ response = input(f"{message} ").strip()++ # Add line break after input so formatter output starts clean+ console.print()++ return response+ finally:+ # Resume live updates+ formatter.resume_live_updates()diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex c3ac1ad72..d8e74fc08 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -77,7 +77,7 @@ from crewai.flow.flow_wrappers import (StartMethod,)from crewai.flow.persistence.base import FlowPersistence-from crewai.flow.types import FlowExecutionData, FlowMethodName, PendingListenerKey+from crewai.flow.types import FlowExecutionData, FlowMethodName, InputHistoryEntry, PendingListenerKeyfrom crewai.flow.utils import (_extract_all_methods,_extract_all_methods_recursive,@@ -738,6 +738,7 @@ class Flow(Generic[T], metaclass=FlowMeta):tracing: bool | None = Nonestream: bool = Falsememory: Any = None # Memory | MemoryScope | MemorySlice | None; auto-created if not set+ input_provider: Any = None # InputProvider | None; per-flow override for self.ask()def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]:class _FlowGeneric(cls): # type: ignore@@ -784,6 +785,9 @@ class Flow(Generic[T], metaclass=FlowMeta):self._pending_feedback_context: PendingFeedbackContext | None = Noneself.suppress_flow_events: bool = suppress_flow_events+ # User input history (for self.ask())+ self._input_history: list[InputHistoryEntry] = []+# Initialize state with initial valuesself._state = self._create_initial_state()self.tracing = tracing@@ -2119,15 +2123,24 @@ class Flow(Generic[T], metaclass=FlowMeta):if future:self._event_futures.append(future)- if asyncio.iscoroutinefunction(method):- result = await method(*args, **kwargs)- else:- # Run sync methods in thread pool for isolation- # This allows Agent.kickoff() to work synchronously inside Flow methods- import contextvars+ # Set method name in context so ask() can read it without+ # stack inspection. Must happen before copy_context() so the+ # value propagates into the thread pool for sync methods.+ from crewai.flow.flow_context import current_flow_method_name++ method_name_token = current_flow_method_name.set(method_name)+ try:+ if asyncio.iscoroutinefunction(method):+ result = await method(*args, **kwargs)+ else:+ # Run sync methods in thread pool for isolation+ # This allows Agent.kickoff() to work synchronously inside Flow methods+ import contextvars- ctx = contextvars.copy_context()- result = await asyncio.to_thread(ctx.run, method, *args, **kwargs)+ ctx = contextvars.copy_context()+ result = await asyncio.to_thread(ctx.run, method, *args, **kwargs)+ finally:+ current_flow_method_name.reset(method_name_token)# Auto-await coroutines returned from sync methods (enables AgentExecutor pattern)if asyncio.iscoroutine(result):@@ -2582,6 +2595,201 @@ class Flow(Generic[T], metaclass=FlowMeta):logger.error(f"Error executing listener {listener_name}: {e}")raise+ # ── User Input (self.ask) ────────────────────────────────────────++ def _resolve_input_provider(self) -> Any:+ """Resolve the input provider using the priority chain.++ Resolution order:+ 1. ``self.input_provider`` (per-flow override)+ 2. ``flow_config.input_provider`` (global default)+ 3. ``ConsoleInputProvider()`` (built-in fallback)++ Returns:+ An object implementing the ``InputProvider`` protocol.+ """+ from crewai.flow.async_feedback.providers import ConsoleProvider+ from crewai.flow.flow_config import flow_config++ if self.input_provider is not None:+ return self.input_provider+ if flow_config.input_provider is not None:+ return flow_config.input_provider+ return ConsoleProvider()++ def _checkpoint_state_for_ask(self) -> None:+ """Auto-checkpoint flow state before waiting for user input.++ If persistence is configured, saves the current state so that+ ``self.state`` is recoverable even if the process crashes while+ waiting for input.++ This is best-effort: if persistence is not configured, this is a no-op.+ """+ if self._persistence is None:+ return+ try:+ state_data = (+ self._state+ if isinstance(self._state, dict)+ else self._state.model_dump()+ )+ self._persistence.save_state(+ flow_uuid=self.flow_id,+ method_name="_ask_checkpoint",+ state_data=state_data,+ )+ except Exception:+ logger.debug("Failed to checkpoint state before ask()", exc_info=True)++ def ask(+ self,+ message: str,+ timeout: float | None = None,+ metadata: dict[str, Any] | None = None,+ ) -> str | None:+ """Request input from the user during flow execution.++ Blocks the current thread until the user provides input or the+ timeout expires. Works in both sync and async flow methods (the+ flow framework runs sync methods in a thread pool via+ ``asyncio.to_thread``, so the event loop stays free).++ Timeout ensures flows always terminate. When timeout expires,+ ``None`` is returned, enabling the pattern::++ while (msg := self.ask("You: ", timeout=300)) is not None:+ process(msg)++ Before waiting for input, the current ``self.state`` is automatically+ checkpointed to persistence (if configured) for durability.++ Args:+ message: The question or prompt to display to the user.+ timeout: Maximum seconds to wait for input. ``None`` means+ wait indefinitely. When timeout expires, returns ``None``.+ Note: timeout is best-effort for the provider call --+ ``ask()`` returns ``None`` promptly, but the underlying+ ``request_input()`` may continue running in a background+ thread until it completes naturally. Network providers+ should implement their own internal timeouts.+ metadata: Optional metadata to send to the input provider,+ such as user ID, channel, session context. The provider+ can use this to route the question to the right recipient.++ Returns:+ The user's input as a string, or ``None`` on timeout, disconnect,+ or provider error. Empty string ``""`` means the user pressed+ Enter without typing (intentional empty input).++ Example:+ ```python+ class MyFlow(Flow):+ @start()+ def gather_info(self):+ topic = self.ask(+ "What topic should we research?",+ metadata={"user_id": "u123", "channel": "#research"},+ )+ if topic is None:+ return "No input received"+ return topic+ ```+ """+ from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError+ from datetime import datetime++ from crewai.events.types.flow_events import (+ FlowInputReceivedEvent,+ FlowInputRequestedEvent,+ )+ from crewai.flow.flow_context import current_flow_method_name+ from crewai.flow.input_provider import InputResponse++ method_name = current_flow_method_name.get("unknown")++ # Emit input requested event+ crewai_event_bus.emit(+ self,+ FlowInputRequestedEvent(+ type="flow_input_requested",+ flow_name=self.name or self.__class__.__name__,+ method_name=method_name,+ message=message,+ metadata=metadata,+ ),+ )++ # Auto-checkpoint state before waiting+ self._checkpoint_state_for_ask()++ provider = self._resolve_input_provider()+ raw: str | InputResponse | None = None++ try:+ if timeout is not None:+ # Manual executor management to avoid shutdown(wait=True)+ # deadlock when the provider call outlives the timeout.+ executor = ThreadPoolExecutor(max_workers=1)+ future = executor.submit(+ provider.request_input, message, self, metadata+ )+ try:+ raw = future.result(timeout=timeout)+ except FuturesTimeoutError:+ future.cancel()+ raw = None+ finally:+ # wait=False so we don't block if the provider is still+ # running (e.g. input() stuck waiting for user).+ # cancel_futures=True cleans up any queued-but-not-started tasks.+ executor.shutdown(wait=False, cancel_futures=True)+ else:+ raw = provider.request_input(message, self, metadata=metadata)+ except KeyboardInterrupt:+ raise+ except Exception:+ logger.debug("Input provider error in ask()", exc_info=True)+ raw = None++ # Normalize provider response: str, InputResponse, or None+ response: str | None = None+ response_metadata: dict[str, Any] | None = None++ if isinstance(raw, InputResponse):+ response = raw.text+ response_metadata = raw.metadata+ elif isinstance(raw, str):+ response = raw+ else:+ response = None++ # Record in history+ self._input_history.append({+ "message": message,+ "response": response,+ "method_name": method_name,+ "timestamp": datetime.now(),+ "metadata": metadata,+ "response_metadata": response_metadata,+ })++ # Emit input received event+ crewai_event_bus.emit(+ self,+ FlowInputReceivedEvent(+ type="flow_input_received",+ flow_name=self.name or self.__class__.__name__,+ method_name=method_name,+ message=message,+ response=response,+ metadata=metadata,+ response_metadata=response_metadata,+ ),+ )++ return response+def _request_human_feedback(self,message: str,diff --git a/lib/crewai/src/crewai/flow/flow_config.py b/lib/crewai/src/crewai/flow/flow_config.pyindex 8684cc3cf..a4a6bfbe4 100644--- a/lib/crewai/src/crewai/flow/flow_config.py+++ b/lib/crewai/src/crewai/flow/flow_config.py@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, Anyif TYPE_CHECKING:from crewai.flow.async_feedback.types import HumanFeedbackProvider+ from crewai.flow.input_provider import InputProviderclass FlowConfig:@@ -20,10 +21,15 @@ class FlowConfig:hitl_provider: The human-in-the-loop feedback provider.Defaults to None (uses console input).Can be overridden by deployments at startup.+ input_provider: The input provider used by ``Flow.ask()``.+ Defaults to None (uses ``ConsoleProvider``).+ Can be overridden by+ deployments at startup."""def __init__(self) -> None:self._hitl_provider: HumanFeedbackProvider | None = None+ self._input_provider: InputProvider | None = None@propertydef hitl_provider(self) -> Any:@@ -35,6 +41,32 @@ class FlowConfig:"""Set the HITL provider."""self._hitl_provider = provider+ @property+ def input_provider(self) -> Any:+ """Get the configured input provider for ``Flow.ask()``.++ Returns:+ The configured InputProvider instance, or None if not set+ (in which case ``ConsoleInputProvider`` is used as default).+ """+ return self._input_provider++ @input_provider.setter+ def input_provider(self, provider: Any) -> None:+ """Set the input provider for ``Flow.ask()``.++ Args:+ provider: An object implementing the ``InputProvider`` protocol.++ Example:+ ```python+ from crewai.flow import flow_config++ flow_config.input_provider = WebSocketInputProvider(...)+ ```+ """+ self._input_provider = provider+# Singleton instanceflow_config = FlowConfig()diff --git a/lib/crewai/src/crewai/flow/flow_context.py b/lib/crewai/src/crewai/flow/flow_context.pyindex ae9bd69f9..0ff6cf973 100644--- a/lib/crewai/src/crewai/flow/flow_context.py+++ b/lib/crewai/src/crewai/flow/flow_context.py@@ -14,3 +14,7 @@ current_flow_request_id: contextvars.ContextVar[str | None] = contextvars.Contexcurrent_flow_id: contextvars.ContextVar[str | None] = contextvars.ContextVar("flow_id", default=None)++current_flow_method_name: contextvars.ContextVar[str] = contextvars.ContextVar(+ "flow_method_name", default="unknown"+)diff --git a/lib/crewai/src/crewai/flow/input_provider.py b/lib/crewai/src/crewai/flow/input_provider.pynew file mode 100644index 000000000..20799abbe--- /dev/null+++ b/lib/crewai/src/crewai/flow/input_provider.py@@ -0,0 +1,151 @@+"""Input provider protocol for Flow.ask().++This module provides the InputProvider protocol and InputResponse dataclass+used by Flow.ask() to request input from users during flow execution.++The default implementation is ``ConsoleProvider`` (from+``crewai.flow.async_feedback.providers``), which serves both feedback+and input collection via console.++Example (default console input):+ ```python+ from crewai.flow import Flow, start+++ class MyFlow(Flow):+ @start()+ def gather_info(self):+ topic = self.ask("What topic should we research?")+ return topic+ ```++Example (custom provider with metadata):+ ```python+ from crewai.flow import Flow, start+ from crewai.flow.input_provider import InputProvider, InputResponse+++ class SlackProvider:+ def request_input(self, message, flow, metadata=None):+ channel = metadata.get("channel", "#general") if metadata else "#general"+ thread = self.post_question(channel, message)+ reply = self.wait_for_reply(thread)+ return InputResponse(+ text=reply.text,+ metadata={"responded_by": reply.user_id, "thread_id": thread.id},+ )+++ class MyFlow(Flow):+ input_provider = SlackProvider()++ @start()+ def gather_info(self):+ topic = self.ask("What topic?", metadata={"channel": "#research"})+ return topic+ ```+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable+++if TYPE_CHECKING:+ from crewai.flow.flow import Flow+++@dataclass+class InputResponse:+ """Response from an InputProvider, optionally carrying metadata.++ Simple providers can just return a string from ``request_input()``.+ Providers that need to send metadata back (e.g., who responded,+ thread ID, external timestamps) return an ``InputResponse`` instead.++ ``ask()`` normalizes both cases -- callers always get ``str | None``.+ The response metadata is stored in ``_input_history`` and emitted+ in ``FlowInputReceivedEvent``.++ Attributes:+ text: The user's input text, or None if unavailable.+ metadata: Optional metadata from the provider about the response+ (e.g., who responded, thread ID, timestamps).++ Example:+ ```python+ class MyProvider:+ def request_input(self, message, flow, metadata=None):+ response = get_response_from_external_system(message)+ return InputResponse(+ text=response.text,+ metadata={"responded_by": response.user_id},+ )+ ```+ """++ text: str | None+ metadata: dict[str, Any] | None = field(default=None)+++@runtime_checkable+class InputProvider(Protocol):+ """Protocol for user input collection strategies.++ Implement this protocol to create custom input providers that integrate+ with external systems like websockets, web UIs, Slack, or custom APIs.++ The default provider is ``ConsoleProvider``, which blocks waiting for+ console input via Python's built-in ``input()`` function.++ Providers are always synchronous. The flow framework runs sync methods+ in a thread pool (via ``asyncio.to_thread``), so ``ask()`` never blocks+ the event loop even inside async flow methods.++ Providers can return either:+ - ``str | None`` for simple cases (no response metadata)+ - ``InputResponse`` when they need to send metadata back with the answer++ Example (simple):+ ```python+ class SimpleProvider:+ def request_input(self, message: str, flow: Flow) -> str | None:+ return input(message)+ ```++ Example (with metadata):+ ```python+ class SlackProvider:+ def request_input(self, message, flow, metadata=None):+ channel = metadata.get("channel") if metadata else "#general"+ reply = self.post_and_wait(channel, message)+ return InputResponse(+ text=reply.text,+ metadata={"responded_by": reply.user_id},+ )+ ```+ """++ def request_input(+ self,+ message: str,+ flow: Flow[Any],+ metadata: dict[str, Any] | None = None,+ ) -> str | InputResponse | None:+ """Request input from the user.++ Args:+ message: The question or prompt to display to the user.+ flow: The Flow instance requesting input. Can be used to+ access flow state, name, or other context.+ metadata: Optional metadata from the caller, such as user ID,+ channel, session context, etc. Providers can use this to+ route the question to the right recipient.++ Returns:+ The user's input as a string, an ``InputResponse`` with text+ and optional response metadata, or None if input is unavailable+ (e.g., user cancelled, connection dropped).+ """+ ...diff --git a/lib/crewai/src/crewai/flow/types.py b/lib/crewai/src/crewai/flow/types.pyindex 024de41df..65ed3a995 100644--- a/lib/crewai/src/crewai/flow/types.py+++ b/lib/crewai/src/crewai/flow/types.py@@ -4,6 +4,7 @@ This module contains TypedDict definitions and type aliases used throughoutthe Flow system."""+from datetime import datetimefrom typing import (Annotated,Any,@@ -101,6 +102,30 @@ class FlowData(TypedDict):flow_methods_attributes: list[FlowMethodData]+class InputHistoryEntry(TypedDict):+ """A single entry in the flow's input history from ``self.ask()``.++ Each call to ``Flow.ask()`` appends one entry recording the question,+ the user's response, which method asked, and any metadata exchanged+ between the caller and the input provider.++ Attributes:+ message: The question or prompt that was displayed to the user.+ response: The user's response, or None on timeout/error.+ method_name: The flow method that called ``ask()``.+ timestamp: When the input was received.+ metadata: Metadata sent with the question (caller to provider).+ response_metadata: Metadata received with the answer (provider to caller).+ """++ message: str+ response: str | None+ method_name: str+ timestamp: datetime+ metadata: dict[str, Any] | None+ response_metadata: dict[str, Any] | None++class FlowExecutionData(TypedDict):"""Flow execution data.diff --git a/lib/crewai/tests/cli/test_cli.py b/lib/crewai/tests/cli/test_cli.pyindex 529f5ded7..ed74a6036 100644--- a/lib/crewai/tests/cli/test_cli.py+++ b/lib/crewai/tests/cli/test_cli.py@@ -66,7 +66,9 @@ def mock_crew():def mock_get_crews(mock_crew):with mock.patch("crewai.cli.reset_memories_command.get_crews", return_value=[mock_crew]- ) as mock_get_crew:+ ) as mock_get_crew, mock.patch(+ "crewai.cli.reset_memories_command.get_flows", return_value=[]+ ):yield mock_get_crew@@ -193,6 +195,79 @@ def test_reset_memory_from_many_crews(mock_get_crews, runner):assert call_count == 2, "reset_memories should have been called twice"+def mock_flow():+ _mock = mock.Mock()+ _mock.name = "TestFlow"+ _mock.memory = mock.Mock()+ _mock.memory.reset = mock.Mock()+ return _mock+++def mock_get_flows(mock_flow):+ with mock.patch(+ "crewai.cli.reset_memories_command.get_flows", return_value=[mock_flow]+ ) as mock_get_flow, mock.patch(+ "crewai.cli.reset_memories_command.get_crews", return_value=[]+ ):+ yield mock_get_flow+++def test_reset_flow_memory(mock_get_flows, mock_flow, runner):+ result = runner.invoke(reset_memories, ["-m"])+ mock_flow.memory.reset.assert_called_once()+ assert "[Flow (TestFlow)] Memory has been reset." in result.output+++def test_reset_flow_all_memories(mock_get_flows, mock_flow, runner):+ result = runner.invoke(reset_memories, ["-a"])+ mock_flow.memory.reset.assert_called_once()+ assert "[Flow (TestFlow)] Reset memories command has been completed." in result.output+++def test_reset_flow_knowledge_no_effect(mock_get_flows, mock_flow, runner):+ result = runner.invoke(reset_memories, ["--knowledge"])+ mock_flow.memory.reset.assert_not_called()+ assert "[Flow (TestFlow)]" not in result.output+++def test_reset_no_crew_or_flow_found(runner):+ with mock.patch(+ "crewai.cli.reset_memories_command.get_crews", return_value=[]+ ), mock.patch(+ "crewai.cli.reset_memories_command.get_flows", return_value=[]+ ):+ result = runner.invoke(reset_memories, ["-m"])+ assert "No crew or flow found." in result.output+++def test_reset_crew_and_flow_memory(mock_crew, mock_flow, runner):+ with mock.patch(+ "crewai.cli.reset_memories_command.get_crews", return_value=[mock_crew]+ ), mock.patch(+ "crewai.cli.reset_memories_command.get_flows", return_value=[mock_flow]+ ):+ result = runner.invoke(reset_memories, ["-m"])+ mock_crew.reset_memories.assert_called_once_with(command_type="memory")+ mock_flow.memory.reset.assert_called_once()+ assert f"[Crew ({mock_crew.name})] Memory has been reset." in result.output+ assert "[Flow (TestFlow)] Memory has been reset." in result.output+++def test_reset_flow_memory_none(runner):+ mock_flow = mock.Mock()+ mock_flow.name = "NoMemFlow"+ mock_flow.memory = None+ with mock.patch(+ "crewai.cli.reset_memories_command.get_crews", return_value=[]+ ), mock.patch(+ "crewai.cli.reset_memories_command.get_flows", return_value=[mock_flow]+ ):+ result = runner.invoke(reset_memories, ["-m"])+ assert "[Flow (NoMemFlow)] Memory has been reset." in result.output++def test_reset_no_memory_flags(runner):result = runner.invoke(reset_memories,diff --git a/lib/crewai/tests/test_flow_ask.py b/lib/crewai/tests/test_flow_ask.pynew file mode 100644index 000000000..d198e261c--- /dev/null+++ b/lib/crewai/tests/test_flow_ask.py@@ -0,0 +1,1152 @@+"""Tests for Flow.ask() user input method.++This module tests the ask() method on Flow, including basic usage,+timeout behavior, provider resolution, event emission, auto-checkpoint+durability, input history tracking, and integration with flow machinery.+"""++from __future__ import annotations++import time+from datetime import datetime+from typing import Any+from unittest.mock import MagicMock, patch++from crewai.flow import Flow, flow_config, listen, start+from crewai.flow.async_feedback.providers import ConsoleProvider+from crewai.flow.flow import FlowState+from crewai.flow.input_provider import InputProvider, InputResponse+++# ── Test helpers ─────────────────────────────────────────────────+++class MockInputProvider:+ """Mock input provider that returns pre-configured responses."""++ def __init__(self, responses: list[str | None]) -> None:+ self.responses = responses+ self._call_count = 0+ self.messages: list[str] = []+ self.received_metadata: list[dict[str, Any] | None] = []++ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> str | None:+ self.messages.append(message)+ self.received_metadata.append(metadata)+ if self._call_count >= len(self.responses):+ return None+ response = self.responses[self._call_count]+ self._call_count += 1+ return response+++class SlowMockProvider:+ """Mock provider that delays before returning, for timeout tests."""++ def __init__(self, delay: float, response: str = "delayed") -> None:+ self.delay = delay+ self.response = response++ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> str | None:+ time.sleep(self.delay)+ return self.response+++# ── Basic Functionality ──────────────────────────────────────────+++class TestAskBasic:+ """Tests for basic ask() functionality."""++ def test_ask_returns_user_input(self) -> None:+ """ask() returns the string from the input provider."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["hello"])++ @start()+ def my_method(self):+ return self.ask("Say something:")++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "hello"++ def test_ask_in_async_method(self) -> None:+ """ask() works inside an async flow method."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["async hello"])++ @start()+ async def my_method(self):+ return self.ask("Say something:")++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "async hello"++ def test_ask_in_start_method(self) -> None:+ """ask() works inside a @start() method, flow completes normally."""+ execution_log: list[str] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI"])++ @start()+ def gather(self):+ topic = self.ask("Topic?")+ execution_log.append(f"got:{topic}")+ return topic++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "AI"+ assert execution_log == ["got:AI"]++ def test_ask_in_listen_method(self) -> None:+ """ask() works inside a @listen() method."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["detailed"])++ @start()+ def step1(self):+ return "topic"++ @listen("step1")+ def step2(self):+ depth = self.ask("How deep?")+ return f"researching at {depth} level"++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "researching at detailed level"++ def test_ask_multiple_calls(self) -> None:+ """Multiple ask() calls in one method return correct values in order."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI", "detailed", "english"])++ @start()+ def gather(self):+ topic = self.ask("Topic?")+ depth = self.ask("Depth?")+ lang = self.ask("Language?")+ return {"topic": topic, "depth": depth, "lang": lang}++ flow = TestFlow()+ result = flow.kickoff()+ assert result == {"topic": "AI", "depth": "detailed", "lang": "english"}++ def test_ask_conditional(self) -> None:+ """ask() called conditionally based on previous answer."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI", "LLMs"])++ @start()+ def gather(self):+ topic = self.ask("Topic?")+ if topic == "AI":+ focus = self.ask("Specific area?")+ else:+ focus = "general"+ return {"topic": topic, "focus": focus}++ flow = TestFlow()+ result = flow.kickoff()+ assert result == {"topic": "AI", "focus": "LLMs"}++ def test_ask_returns_empty_string_on_enter(self) -> None:+ """Empty string means user pressed Enter (intentional empty input)."""++ class TestFlow(Flow):+ input_provider = MockInputProvider([""])++ @start()+ def my_method(self):+ result = self.ask("Optional input:")+ return result++ flow = TestFlow()+ result = flow.kickoff()+ assert result == ""+ assert result is not None # Explicitly not None+++# ── Timeout ──────────────────────────────────────────────────────+++class TestAskTimeout:+ """Tests for timeout behavior."""++ def test_ask_timeout_returns_none(self) -> None:+ """ask() returns None when timeout expires."""++ class TestFlow(Flow):+ input_provider = SlowMockProvider(delay=5.0)++ @start()+ def my_method(self):+ return self.ask("Question?", timeout=0.1)++ flow = TestFlow()+ result = flow.kickoff()+ assert result is None++ def test_ask_timeout_in_async_method(self) -> None:+ """ask() timeout works inside an async flow method."""++ class TestFlow(Flow):+ input_provider = SlowMockProvider(delay=5.0)++ @start()+ async def my_method(self):+ return self.ask("Question?", timeout=0.1)++ flow = TestFlow()+ result = flow.kickoff()+ assert result is None++ def test_ask_loop_with_timeout_termination(self) -> None:+ """while (msg := ask(...)) is not None pattern terminates on timeout."""+ messages_received: list[str] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["hello", "world", None])++ @start()+ def chat(self):+ while (msg := self.ask("You:")) is not None:+ messages_received.append(msg)+ return len(messages_received)++ flow = TestFlow()+ result = flow.kickoff()+ assert result == 2+ assert messages_received == ["hello", "world"]++ def test_ask_no_timeout_waits_indefinitely(self) -> None:+ """ask() with no timeout blocks until provider returns."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("Question?") # no timeout++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "answer"+++# ── Provider Resolution ──────────────────────────────────────────+++class TestProviderResolution:+ """Tests for provider resolution priority chain."""++ def test_ask_uses_flow_level_provider(self) -> None:+ """Per-flow input_provider is used when set."""+ provider = MockInputProvider(["from flow"])++ class TestFlow(Flow):+ input_provider = provider++ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ flow.kickoff()+ assert provider.messages == ["Q?"]++ def test_ask_uses_global_config_provider(self) -> None:+ """flow_config.input_provider is used as fallback."""+ provider = MockInputProvider(["from config"])++ original = flow_config.input_provider+ try:+ flow_config.input_provider = provider++ class TestFlow(Flow):+ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "from config"+ assert provider.messages == ["Q?"]+ finally:+ flow_config.input_provider = original++ def test_ask_defaults_to_console_provider(self) -> None:+ """When no provider configured, ConsoleProvider is used."""+ original = flow_config.input_provider+ try:+ flow_config.input_provider = None++ class TestFlow(Flow):+ # No input_provider set+ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ resolved = flow._resolve_input_provider()+ assert isinstance(resolved, ConsoleProvider)+ finally:+ flow_config.input_provider = original++ def test_flow_provider_overrides_global(self) -> None:+ """Per-flow provider takes precedence over global config."""+ flow_provider = MockInputProvider(["from flow"])+ global_provider = MockInputProvider(["from global"])++ original = flow_config.input_provider+ try:+ flow_config.input_provider = global_provider++ class TestFlow(Flow):+ input_provider = flow_provider++ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ result = flow.kickoff()+ assert result == "from flow"+ assert flow_provider.messages == ["Q?"]+ assert global_provider.messages == [] # not called+ finally:+ flow_config.input_provider = original+++# ── Events ───────────────────────────────────────────────────────+++class TestAskEvents:+ """Tests for event emission during ask()."""++ def test_ask_emits_input_requested_event(self) -> None:+ """FlowInputRequestedEvent is emitted when ask() is called."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import FlowInputRequestedEvent++ events_captured: list[FlowInputRequestedEvent] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("What topic?")++ flow = TestFlow()++ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowInputRequestedEvent):+ events_captured.append(event)+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert len(events_captured) == 1+ assert events_captured[0].message == "What topic?"+ assert events_captured[0].type == "flow_input_requested"++ def test_ask_emits_input_received_event(self) -> None:+ """FlowInputReceivedEvent is emitted after input is received."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import FlowInputReceivedEvent++ events_captured: list[FlowInputReceivedEvent] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["my answer"])++ @start()+ def my_method(self):+ return self.ask("Question?")++ flow = TestFlow()++ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowInputReceivedEvent):+ events_captured.append(event)+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert len(events_captured) == 1+ assert events_captured[0].message == "Question?"+ assert events_captured[0].response == "my answer"+ assert events_captured[0].type == "flow_input_received"++ def test_ask_timeout_emits_received_with_none(self) -> None:+ """FlowInputReceivedEvent has response=None on timeout."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import FlowInputReceivedEvent++ events_captured: list[FlowInputReceivedEvent] = []++ class TestFlow(Flow):+ input_provider = SlowMockProvider(delay=5.0)++ @start()+ def my_method(self):+ return self.ask("Question?", timeout=0.1)++ flow = TestFlow()++ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowInputReceivedEvent):+ events_captured.append(event)+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert len(events_captured) == 1+ assert events_captured[0].response is None+++# ── Auto-checkpoint (Durability) ─────────────────────────────────+++class TestAskCheckpoint:+ """Tests for auto-checkpoint durability before ask() waits."""++ def test_ask_checkpoints_state_before_waiting(self) -> None:+ """State is saved to persistence before waiting for input."""+ mock_persistence = MagicMock()+ mock_persistence.load_state.return_value = None++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ self.state["important"] = "data"+ return self.ask("Question?")++ flow = TestFlow(persistence=mock_persistence)+ flow.kickoff()++ # Find the _ask_checkpoint call among save_state calls+ checkpoint_calls = [+ c for c in mock_persistence.save_state.call_args_list+ if c.kwargs.get("method_name") == "_ask_checkpoint"+ or (len(c.args) >= 2 and c.args[1] == "_ask_checkpoint")+ ]+ assert len(checkpoint_calls) >= 1++ def test_ask_no_checkpoint_without_persistence(self) -> None:+ """No error when persistence is not configured."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("Question?")++ flow = TestFlow() # No persistence+ result = flow.kickoff()+ assert result == "answer" # Works fine without persistence++ def test_state_recoverable_after_checkpoint(self) -> None:+ """State set before ask() is checkpointed and recoverable.++ The auto-checkpoint happens *before* the provider is called, so+ state values set prior to ask() are persisted. This means if the+ server crashes while waiting for input, previously gathered data+ is safe.+ """+ mock_persistence = MagicMock()+ mock_persistence.load_state.return_value = None++ class GatherFlow(Flow):+ input_provider = MockInputProvider(["AI", "detailed"])++ @start()+ def gather(self):+ # First ask: nothing in state yet+ topic = self.ask("Topic?")+ self.state["topic"] = topic+ # Second ask: state now has topic, checkpoint saves it+ depth = self.ask("Depth?")+ self.state["depth"] = depth+ return {"topic": topic, "depth": depth}++ flow = GatherFlow(persistence=mock_persistence)+ result = flow.kickoff()+ assert result == {"topic": "AI", "depth": "detailed"}++ # Find the checkpoint calls+ checkpoint_calls = [+ c for c in mock_persistence.save_state.call_args_list+ if c.kwargs.get("method_name") == "_ask_checkpoint"+ or (len(c.args) >= 2 and c.args[1] == "_ask_checkpoint")+ ]+ assert len(checkpoint_calls) == 2++ # The second checkpoint (before asking "Depth?") should have topic+ second_checkpoint = checkpoint_calls[1]+ # state_data is the third positional arg or keyword arg+ if second_checkpoint.kwargs.get("state_data"):+ state_data = second_checkpoint.kwargs["state_data"]+ else:+ state_data = second_checkpoint.args[2]+ assert state_data.get("topic") == "AI"+++# ── Input History ────────────────────────────────────────────────+++class TestInputHistory:+ """Tests for _input_history tracking."""++ def test_input_history_accumulated(self) -> None:+ """_input_history tracks all ask/response pairs."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI", "detailed"])++ @start()+ def gather(self):+ self.ask("Topic?")+ self.ask("Depth?")+ return "done"++ flow = TestFlow()+ flow.kickoff()++ assert len(flow._input_history) == 2+ assert flow._input_history[0]["message"] == "Topic?"+ assert flow._input_history[0]["response"] == "AI"+ assert flow._input_history[1]["message"] == "Depth?"+ assert flow._input_history[1]["response"] == "detailed"++ def test_input_history_includes_method_name(self) -> None:+ """Input history records which method called ask()."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI"])++ @start()+ def gather_info(self):+ self.ask("Topic?")+ return "done"++ flow = TestFlow()+ flow.kickoff()++ assert len(flow._input_history) == 1+ assert flow._input_history[0]["method_name"] == "gather_info"++ def test_input_history_includes_timestamp(self) -> None:+ """Input history records timestamps."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI"])++ @start()+ def my_method(self):+ self.ask("Topic?")+ return "done"++ flow = TestFlow()+ before = datetime.now()+ flow.kickoff()+ after = datetime.now()++ assert len(flow._input_history) == 1+ ts = flow._input_history[0]["timestamp"]+ assert isinstance(ts, datetime)+ assert before <= ts <= after++ def test_input_history_records_none_on_timeout(self) -> None:+ """Input history records None response on timeout."""++ class TestFlow(Flow):+ input_provider = SlowMockProvider(delay=5.0)++ @start()+ def my_method(self):+ self.ask("Question?", timeout=0.1)+ return "done"++ flow = TestFlow()+ flow.kickoff()++ assert len(flow._input_history) == 1+ assert flow._input_history[0]["response"] is None+++# ── Integration ──────────────────────────────────────────────────+++class TestAskIntegration:+ """Integration tests for ask() with other flow features."""++ def test_ask_works_with_listen_chain(self) -> None:+ """ask() in a start method, result flows to listener."""+ execution_log: list[str] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI agents"])++ @start()+ def gather(self):+ topic = self.ask("Topic?")+ execution_log.append(f"gathered:{topic}")+ return topic++ @listen("gather")+ def process(self):+ execution_log.append("processing")+ return "processed"++ flow = TestFlow()+ flow.kickoff()+ assert "gathered:AI agents" in execution_log+ assert "processing" in execution_log++ def test_ask_with_structured_state(self) -> None:+ """ask() works with Pydantic-based flow state."""++ class ResearchState(FlowState):+ topic: str = ""+ depth: str = ""++ class TestFlow(Flow[ResearchState]):+ initial_state = ResearchState+ input_provider = MockInputProvider(["AI", "detailed"])++ @start()+ def gather(self):+ self.state.topic = self.ask("Topic?")+ self.state.depth = self.ask("Depth?")+ return {"topic": self.state.topic, "depth": self.state.depth}++ flow = TestFlow()+ result = flow.kickoff()+ assert result == {"topic": "AI", "depth": "detailed"}+ assert flow.state.topic == "AI"+ assert flow.state.depth == "detailed"++ def test_ask_in_async_method_with_listen_chain(self) -> None:+ """ask() in an async start method, result flows to listener."""+ execution_log: list[str] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["async topic"])++ @start()+ async def gather(self):+ topic = self.ask("Topic?")+ execution_log.append(f"gathered:{topic}")+ return topic++ @listen("gather")+ def process(self):+ execution_log.append("processing")+ return "processed"++ flow = TestFlow()+ flow.kickoff()+ assert "gathered:async topic" in execution_log+ assert "processing" in execution_log++ def test_ask_with_state_persistence_recovery(self) -> None:+ """Ask checkpoints state so previously gathered values survive."""+ mock_persistence = MagicMock()+ mock_persistence.load_state.return_value = None++ class RecoverableFlow(Flow):+ input_provider = MockInputProvider(["AI", "detailed"])++ @start()+ def gather(self):+ if not self.state.get("topic"):+ self.state["topic"] = self.ask("Topic?")+ if not self.state.get("depth"):+ self.state["depth"] = self.ask("Depth?")+ return {+ "topic": self.state["topic"],+ "depth": self.state["depth"],+ }++ flow = RecoverableFlow(persistence=mock_persistence)+ result = flow.kickoff()+ assert result["topic"] == "AI"+ assert result["depth"] == "detailed"++ # Verify checkpoints were made+ checkpoint_calls = [+ c for c in mock_persistence.save_state.call_args_list+ if c.kwargs.get("method_name") == "_ask_checkpoint"+ or (len(c.args) >= 2 and c.args[1] == "_ask_checkpoint")+ ]+ # Two ask() calls = two checkpoints+ assert len(checkpoint_calls) == 2++ def test_ask_and_human_feedback_coexist(self) -> None:+ """ask() and @human_feedback can be used in the same flow."""+ from crewai.flow import human_feedback++ class TestFlow(Flow):+ input_provider = MockInputProvider(["AI"])++ @start()+ def gather(self):+ topic = self.ask("Topic?")+ return topic++ @listen("gather")+ @human_feedback(message="Review this topic:")+ def review(self):+ return f"Researching: {self.state.get('_last_topic', 'unknown')}"++ flow = TestFlow()++ with patch.object(flow, "_request_human_feedback", return_value="looks good"):+ flow.kickoff()++ # Flow completed with both ask and human_feedback+ assert flow.last_human_feedback is not None++ def test_ask_preserves_flow_lifecycle(self) -> None:+ """Flow events (started, finished) still fire normally with ask()."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import (+ FlowFinishedEvent,+ FlowStartedEvent,+ )++ events_seen: list[str] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()++ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowStartedEvent):+ events_seen.append("started")+ elif isinstance(event, FlowFinishedEvent):+ events_seen.append("finished")+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert "started" in events_seen+ assert "finished" in events_seen+++# ── Console Provider ─────────────────────────────────────────────+++class TestConsoleProviderInput:+ """Tests for ConsoleProvider.request_input() (used by Flow.ask())."""++ def test_console_provider_pauses_live_updates(self) -> None:+ """ConsoleProvider pauses and resumes formatter live updates."""+ from crewai.events.event_listener import event_listener++ mock_formatter = MagicMock()+ mock_formatter.console = MagicMock()++ provider = ConsoleProvider(verbose=True)++ with (+ patch.object(event_listener, "formatter", mock_formatter),+ patch("builtins.input", return_value="test input"),+ ):+ result = provider.request_input("Question?", MagicMock())++ mock_formatter.pause_live_updates.assert_called_once()+ mock_formatter.resume_live_updates.assert_called_once()+ assert result == "test input"++ def test_console_provider_displays_message(self) -> None:+ """ConsoleProvider displays the message with Rich console."""+ from crewai.events.event_listener import event_listener++ mock_formatter = MagicMock()+ mock_console = MagicMock()+ mock_formatter.console = mock_console++ provider = ConsoleProvider(verbose=True)++ with (+ patch.object(event_listener, "formatter", mock_formatter),+ patch("builtins.input", return_value="answer"),+ ):+ provider.request_input("What topic?", MagicMock())++ # Verify the message was printed+ print_calls = [str(c) for c in mock_console.print.call_args_list]+ assert any("What topic?" in c for c in print_calls)++ def test_console_provider_non_verbose(self) -> None:+ """ConsoleProvider in non-verbose mode uses plain input."""+ from crewai.events.event_listener import event_listener++ mock_formatter = MagicMock()+ mock_formatter.console = MagicMock()++ provider = ConsoleProvider(verbose=False)++ with (+ patch.object(event_listener, "formatter", mock_formatter),+ patch("builtins.input", return_value="plain answer") as mock_input,+ ):+ result = provider.request_input("Q?", MagicMock())++ assert result == "plain answer"+ mock_input.assert_called_once_with("Q? ")++ def test_console_provider_strips_response(self) -> None:+ """ConsoleProvider strips whitespace from response."""+ from crewai.events.event_listener import event_listener++ mock_formatter = MagicMock()+ mock_formatter.console = MagicMock()++ provider = ConsoleProvider(verbose=False)++ with (+ patch.object(event_listener, "formatter", mock_formatter),+ patch("builtins.input", return_value=" spaced answer "),+ ):+ result = provider.request_input("Q?", MagicMock())++ assert result == "spaced answer"++ def test_console_provider_implements_protocol(self) -> None:+ """ConsoleProvider satisfies the InputProvider protocol."""+ provider = ConsoleProvider()+ assert isinstance(provider, InputProvider)+++# ── InputProvider Protocol ───────────────────────────────────────+++class TestInputProviderProtocol:+ """Tests for the InputProvider protocol."""++ def test_custom_provider_satisfies_protocol(self) -> None:+ """A class with request_input satisfies the InputProvider protocol."""++ class MyProvider:+ def request_input(self, message: str, flow: Flow[Any]) -> str | None:+ return "custom"++ provider = MyProvider()+ assert isinstance(provider, InputProvider)++ def test_mock_provider_satisfies_protocol(self) -> None:+ """MockInputProvider satisfies the InputProvider protocol."""+ provider = MockInputProvider(["test"])+ assert isinstance(provider, InputProvider)+++# ── Error Handling ───────────────────────────────────────────────+++class TestAskErrorHandling:+ """Tests for error handling in ask()."""++ def test_ask_returns_none_on_provider_error(self) -> None:+ """ask() returns None if provider raises an exception."""++ class FailingProvider:+ def request_input(self, message: str, flow: Flow[Any]) -> str | None:+ raise RuntimeError("Provider failed")++ class TestFlow(Flow):+ input_provider = FailingProvider()++ @start()+ def my_method(self):+ return self.ask("Question?")++ flow = TestFlow()+ result = flow.kickoff()+ assert result is None++ def test_ask_in_async_method_returns_none_on_provider_error(self) -> None:+ """ask() returns None if provider raises in an async method."""++ class FailingProvider:+ def request_input(self, message: str, flow: Flow[Any]) -> str | None:+ raise RuntimeError("Provider failed")++ class TestFlow(Flow):+ input_provider = FailingProvider()++ @start()+ async def my_method(self):+ return self.ask("Question?")++ flow = TestFlow()+ result = flow.kickoff()+ assert result is None+++# ── Metadata ─────────────────────────────────────────────────────+++class TestAskMetadata:+ """Tests for bidirectional metadata support in ask()."""++ def test_ask_passes_metadata_to_provider(self) -> None:+ """Provider receives the metadata dict from ask()."""+ provider = MockInputProvider(["answer"])++ class TestFlow(Flow):+ input_provider = provider++ @start()+ def my_method(self):+ return self.ask("Q?", metadata={"user_id": "u123"})++ flow = TestFlow()+ flow.kickoff()+ assert provider.received_metadata == [{"user_id": "u123"}]++ def test_ask_metadata_none_by_default(self) -> None:+ """Provider receives None metadata when not provided."""+ provider = MockInputProvider(["answer"])++ class TestFlow(Flow):+ input_provider = provider++ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ flow.kickoff()+ assert provider.received_metadata == [None]++ def test_ask_provider_returns_input_response(self) -> None:+ """Provider returns InputResponse with response metadata."""++ class MetadataProvider:+ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> InputResponse:+ return InputResponse(+ text="the answer",+ metadata={"responded_by": "u456", "thread_id": "t789"},+ )++ class TestFlow(Flow):+ input_provider = MetadataProvider()++ @start()+ def my_method(self):+ return self.ask("Q?", metadata={"user_id": "u123"})++ flow = TestFlow()+ result = flow.kickoff()++ # ask() still returns plain string+ assert result == "the answer"++ # History has both metadata dicts+ assert len(flow._input_history) == 1+ entry = flow._input_history[0]+ assert entry["metadata"] == {"user_id": "u123"}+ assert entry["response_metadata"] == {"responded_by": "u456", "thread_id": "t789"}++ def test_ask_provider_returns_string_with_metadata_sent(self) -> None:+ """Provider returns plain string; history has metadata but no response_metadata."""++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("Q?", metadata={"channel": "#research"})++ flow = TestFlow()+ flow.kickoff()++ entry = flow._input_history[0]+ assert entry["metadata"] == {"channel": "#research"}+ assert entry["response_metadata"] is None++ def test_ask_metadata_in_requested_event(self) -> None:+ """FlowInputRequestedEvent carries metadata."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import FlowInputRequestedEvent++ events_captured: list[FlowInputRequestedEvent] = []++ class TestFlow(Flow):+ input_provider = MockInputProvider(["answer"])++ @start()+ def my_method(self):+ return self.ask("Q?", metadata={"user_id": "u123"})++ flow = TestFlow()+ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowInputRequestedEvent):+ events_captured.append(event)+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert len(events_captured) == 1+ assert events_captured[0].metadata == {"user_id": "u123"}++ def test_ask_metadata_in_received_event(self) -> None:+ """FlowInputReceivedEvent carries both metadata and response_metadata."""+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.flow_events import FlowInputReceivedEvent++ events_captured: list[FlowInputReceivedEvent] = []++ class MetadataProvider:+ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> InputResponse:+ return InputResponse(text="answer", metadata={"responded_by": "u456"})++ class TestFlow(Flow):+ input_provider = MetadataProvider()++ @start()+ def my_method(self):+ return self.ask("Q?", metadata={"user_id": "u123"})++ flow = TestFlow()+ original_emit = crewai_event_bus.emit++ def capture_emit(source: Any, event: Any) -> Any:+ if isinstance(event, FlowInputReceivedEvent):+ events_captured.append(event)+ return original_emit(source, event)++ with patch.object(crewai_event_bus, "emit", side_effect=capture_emit):+ flow.kickoff()++ assert len(events_captured) == 1+ assert events_captured[0].metadata == {"user_id": "u123"}+ assert events_captured[0].response_metadata == {"responded_by": "u456"}+ assert events_captured[0].response == "answer"++ def test_ask_input_response_with_none_text(self) -> None:+ """Provider returns InputResponse with text=None."""++ class NoneTextProvider:+ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> InputResponse:+ return InputResponse(text=None, metadata={"reason": "user_declined"})++ class TestFlow(Flow):+ input_provider = NoneTextProvider()++ @start()+ def my_method(self):+ return self.ask("Q?")++ flow = TestFlow()+ result = flow.kickoff()+ assert result is None++ entry = flow._input_history[0]+ assert entry["response"] is None+ assert entry["response_metadata"] == {"reason": "user_declined"}++ def test_ask_metadata_thread_safe(self) -> None:+ """Concurrent ask() calls with different metadata don't cross-contaminate."""+ import threading++ call_log: list[dict[str, Any]] = []+ log_lock = threading.Lock()++ class TrackingProvider:+ def request_input(+ self, message: str, flow: Flow[Any], metadata: dict[str, Any] | None = None+ ) -> InputResponse:+ # Small delay to increase chance of interleaving+ time.sleep(0.05)+ with log_lock:+ call_log.append({"message": message, "metadata": metadata})+ user = metadata.get("user", "unknown") if metadata else "unknown"+ return InputResponse(+ text=f"answer from {user}",+ metadata={"responded_by": user},+ )++ class TestFlow(Flow):+ input_provider = TrackingProvider()++ @start()+ def trigger(self):+ return "go"++ @listen("trigger")+ def listener_a(self):+ return self.ask("Question A?", metadata={"user": "alice"})++ @listen("trigger")+ def listener_b(self):+ return self.ask("Question B?", metadata={"user": "bob"})++ flow = TestFlow()+ flow.kickoff()++ # Both calls should have recorded their own metadata+ assert len(flow._input_history) == 2++ alice_entry = next(+ (e for e in flow._input_history if e["metadata"] and e["metadata"].get("user") == "alice"),+ None,+ )+ bob_entry = next(+ (e for e in flow._input_history if e["metadata"] and e["metadata"].get("user") == "bob"),+ None,+ )++ assert alice_entry is not None+ assert alice_entry["response"] == "answer from alice"+ assert alice_entry["response_metadata"] == {"responded_by": "alice"}++ assert bob_entry is not None+ assert bob_entry["response"] == "answer from bob"+ assert bob_entry["response_metadata"] == {"responded_by": "bob"}