workflow.mdx

title	Workflow
sidebarTitle	Workflow
mode	wide

Parameters

Parameter	Type	Default	Description
name	Optional[str]	None	Workflow name
id	Optional[str]	None	Workflow ID (autogenerated if not set)
description	Optional[str]	None	Workflow description
steps	Optional[WorkflowSteps]	None	Workflow steps - can be a callable function, Steps object, or list of steps
db	Optional[BaseDb]	None	Database to use for this workflow
session_id	Optional[str]	None	Default session_id to use for this workflow (autogenerated if not set)
user_id	Optional[str]	None	Default user_id to use for this workflow
session_state	Optional[Dict[str, Any]]	None	Default session state (stored in the database to persist across runs)
debug_mode	Optional[bool]	False	If True, the workflow runs in debug mode
stream	Optional[bool]	None	Stream the response from the Workflow
stream_events	bool	False	Stream the intermediate steps from the Workflow
stream_executor_events	bool	True	Stream the events emitted by the Step executor (the agent/team events) together with the Workflow events
store_events	bool	False	Persist the events on the run response
events_to_skip	Optional[List[Union[WorkflowRunEvent, RunEvent, TeamRunEvent]]]	None	Events to skip when persisting the events on the run response
store_executor_outputs	bool	True	Control whether to store executor responses (agent/team responses) in flattened runs
websocket_handler	Optional[WebSocketHandler]	None	WebSocket handler for real-time communication
input_schema	Optional[Type[BaseModel]]	None	Input schema to validate the input to the workflow
metadata	Optional[Dict[str, Any]]	None	Metadata stored with this workflow
add_workflow_history_to_steps	bool	False	If True, add the workflow history to the steps
num_history_runs	int	None	Number of runs to include in the workflow history, if not provided, all history runs are included
cache_session	bool	False	If True, cache the current workflow session in memory for faster access
telemetry	bool	True	Log minimal telemetry for analytics

Functions

run

Execute the workflow synchronously with optional streaming.

Parameters:

• input (Optional[Union[str, Dict[str, Any], List[Any], BaseModel]]): The input to send to the workflow
• additional_data (Optional[Dict[str, Any]]): Additional data to include with the input
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• session_state (Optional[Dict[str, Any]]): Session state to use
• audio (Optional[List[Audio]]): Audio files to include
• images (Optional[List[Image]]): Image files to include
• videos (Optional[List[Video]]): Video files to include
• files (Optional[List[File]]): Files to include
• stream (bool): Whether to stream the response
• stream_events (Optional[bool]): Whether to stream intermediate steps

Returns:

• Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]: Either a WorkflowRunOutput or an iterator of WorkflowRunOutputEvents, depending on the stream parameter

arun

Execute the workflow asynchronously with optional streaming.

Parameters:

• input (Optional[Union[str, Dict[str, Any], List[Any], BaseModel, List[Message]]]): The input to send to the workflow
• additional_data (Optional[Dict[str, Any]]): Additional data to include with the input
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• session_state (Optional[Dict[str, Any]]): Session state to use
• audio (Optional[List[Audio]]): Audio files to include
• images (Optional[List[Image]]): Image files to include
• videos (Optional[List[Video]]): Video files to include
• files (Optional[List[File]]): Files to include
• stream (bool): Whether to stream the response
• stream_events (Optional[bool]): Whether to stream intermediate steps
• background (Optional[bool]): Whether to run in background
• websocket (Optional[WebSocket]): WebSocket for real-time communication

Returns:

• Union[WorkflowRunOutput, AsyncIterator[WorkflowRunOutputEvent]]: Either a WorkflowRunOutput or an iterator of WorkflowRunOutputEvents, depending on the stream parameter

continue_run

Resume a paused workflow run after HITL requirements have been resolved. Used for both step-level and executor-level pauses. See HITL overview.

Parameters:

• run_response (Optional[WorkflowRunOutput]): The paused WorkflowRunOutput to continue. If not provided, run_id and session_id must be supplied to load it from the database.
• run_id (Optional[str]): The run_id of the paused run. Required if run_response is not provided.
• session_id (Optional[str]): The session_id of the paused run. Required if run_response is not provided.
• step_requirements (Optional[List[StepRequirement]]): Updated step requirements with confirmation status. Defaults to the requirements from run_response.
• stream (bool): Whether to stream the response. Defaults to the workflow's stream setting.
• stream_events (Optional[bool]): Whether to stream events. Defaults to the workflow's stream_events setting.

Returns:

• Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]: A WorkflowRunOutput if stream=False, otherwise an iterator of events.

Raises:

• ValueError: If neither run_response nor (run_id + session_id) are provided, the run is not paused, or step requirements have not been resolved.

acontinue_run

Asynchronous variant of continue_run. Required when the workflow's database is async. Same parameters and return shape as continue_run.

print_response

Print workflow execution with rich formatting and optional streaming.

Parameters:

• input (Union[str, Dict[str, Any], List[Any], BaseModel, List[Message]]): The input to send to the workflow
• additional_data (Optional[Dict[str, Any]]): Additional data to include with the input
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• audio (Optional[List[Audio]]): Audio files to include
• images (Optional[List[Image]]): Image files to include
• videos (Optional[List[Video]]): Video files to include
• files (Optional[List[File]]): Files to include
• stream (Optional[bool]): Whether to stream the response content
• markdown (bool): Whether to render content as markdown
• show_time (bool): Whether to show execution time
• show_step_details (bool): Whether to show individual step outputs
• console (Optional[Any]): Rich console instance (optional)

aprint_response

Print workflow execution with rich formatting and optional streaming asynchronously.

Parameters:

• input (Union[str, Dict[str, Any], List[Any], BaseModel, List[Message]]): The input to send to the workflow
• additional_data (Optional[Dict[str, Any]]): Additional data to include with the input
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• audio (Optional[List[Audio]]): Audio files to include
• images (Optional[List[Image]]): Image files to include
• videos (Optional[List[Video]]): Video files to include
• files (Optional[List[File]]): Files to include
• stream (Optional[bool]): Whether to stream the response content
• markdown (bool): Whether to render content as markdown
• show_time (bool): Whether to show execution time
• show_step_details (bool): Whether to show individual step outputs
• console (Optional[Any]): Rich console instance (optional)

cli_app

Run an interactive command-line interface to interact with the workflow.

Parameters:

• input (Optional[str]): The input to send to the workflow
• session_id (Optional[str]): Session ID to use
• user_id (Optional[str]): User ID to use
• user (str): Name for the user (default: "User")
• emoji (str): Emoji for the user (default: ":technologist:")
• stream (Optional[bool]): Whether to stream the response content
• markdown (bool): Whether to render content as markdown (default: True)
• show_time (bool): Whether to show execution time (default: True)
• show_step_details (bool): Whether to show individual step outputs (default: True)
• exit_on (Optional[List[str]]): List of commands to exit the CLI
• **kwargs: Additional keyword arguments

acli_app

Run an interactive command-line interface to interact with the workflow asynchronously.

Parameters:

• input (Optional[str]): The input to send to the workflow
• session_id (Optional[str]): Session ID to use
• user_id (Optional[str]): User ID to use
• user (str): Name for the user (default: "User")
• emoji (str): Emoji for the user (default: ":technologist:")
• stream (Optional[bool]): Whether to stream the response content
• markdown (bool): Whether to render content as markdown (default: True)
• show_time (bool): Whether to show execution time (default: True)
• show_step_details (bool): Whether to show individual step outputs (default: True)
• exit_on (Optional[List[str]]): List of commands to exit the CLI
• **kwargs: Additional keyword arguments

cancel_run

Cancel a running workflow execution.

Parameters:

• run_id (str): The run_id to cancel

Returns:

• bool: True if the run was found and marked for cancellation, False otherwise

get_run

Get the status and details of a background workflow run.

Parameters:

• run_id (str): The run ID to get

Returns:

• Optional[WorkflowRunOutput]: The workflow run output if found

get_run_output

Get a WorkflowRunOutput from the database.

Parameters:

• run_id (str): The run ID
• session_id (Optional[str]): Session ID to use

Returns:

• Optional[WorkflowRunOutput]: The run output

get_last_run_output

Get the last run response from the database for the given session ID.

Parameters:

• session_id (Optional[str]): Session ID to use

Returns:

• Optional[WorkflowRunOutput]: The last run output

get_chat_history

Return a list of dictionaries containing the input and output for each run in the session.

Parameters:

• session_id (Optional[str]): The session ID to get the chat history for. If not provided, the current cached session ID is used
• last_n_runs (Optional[int]): Number of recent runs to include. If None, all runs will be considered

Returns:

• List[WorkflowChatInteraction]: A list of dictionaries containing the input and output for each run

get_session

Get the session for the given session ID.

Parameters:

• session_id (Optional[str]): Session ID to use

Returns:

• Optional[WorkflowSession]: The workflow session

get_session_state

Get the session state for the given session ID.

Parameters:

• session_id (Optional[str]): Session ID to use

Returns:

• Dict[str, Any]: The session state

get_session_name

Get the session name for the given session ID.

Parameters:

• session_id (Optional[str]): Session ID to use

Returns:

• str: The session name

set_session_name

Set the session name and save to storage.

Parameters:

• session_id (Optional[str]): Session ID to use
• autogenerate (bool): Whether to autogenerate the name
• session_name (Optional[str]): The name to set

Returns:

• WorkflowSession: The updated session

get_session_metrics

Get the session metrics for the given session ID.

Parameters:

• session_id (Optional[str]): Session ID to use

Returns:

• Optional[SessionMetrics]: The session metrics

delete_session

Delete a session.

Parameters:

• session_id (str): Session ID to delete

save_session

Save the WorkflowSession to storage.

Parameters:

• session (WorkflowSession): The session to save

to_dict

Convert workflow to dictionary representation.

Returns:

• Dict[str, Any]: Dictionary representation of the workflow