Agent

​

Parameters

Parameter	Type	Default	Description
model	Optional[Model]	None	Model to use for this Agent
name	Optional[str]	None	Agent name
id	Optional[str]	None	Agent ID (autogenerated UUID if not set)
user_id	Optional[str]	None	Default user_id to use for this agent
session_id	Optional[str]	None	Default session_id to use for this agent (autogenerated if not set)
session_state	Optional[Dict[str, Any]]	None	Default session state (stored in the database to persist across runs)
add_session_state_to_context	bool	False	Set to True to add the session_state to the context
enable_agentic_state	bool	False	Set to True to give the agent tools to update the session_state dynamically
cache_session	bool	False	If True, cache the current Agent session in memory for faster access
search_session_history	Optional[bool]	False	Set this to True to allow searching through previous sessions.
num_history_sessions	Optional[int]	None	Specify the number of past sessions to include in the search. It’s advisable to keep this number to 2 or 3 for now, as a larger number might fill up the context length of the model, potentially leading to performance issues.
dependencies	Optional[Dict[str, Any]]	None	Dependencies available for tools and prompt functions
add_dependencies_to_context	bool	False	If True, add the dependencies to the user prompt
db	Optional[BaseDb]	None	Database to use for this agent
memory_manager	Optional[MemoryManager]	None	Memory manager to use for this agent
enable_agentic_memory	bool	False	Enable the agent to manage memories of the user
enable_user_memories	bool	False	If True, the agent creates/updates user memories at the end of runs
add_memories_to_context	Optional[bool]	None	If True, the agent adds a reference to the user memories in the response
enable_session_summaries	bool	False	If True, the agent creates/updates session summaries at the end of runs
add_session_summary_to_context	Optional[bool]	None	If True, the agent adds session summaries to the context
session_summary_manager	Optional[SessionSummaryManager]	None	Session summary manager
add_history_to_context	bool	False	Add the chat history of the current session to the messages sent to the Model
num_history_runs	int	3	Number of historical runs to include in the messages.
knowledge	Optional[Knowledge]	None	Agent Knowledge
knowledge_filters	Optional[Dict[str, Any]]	None	Knowledge filters to apply to the knowledge base
enable_agentic_knowledge_filters	Optional[bool]	None	Let the agent choose the knowledge filters
add_knowledge_to_context	bool	False	Enable RAG by adding references from Knowledge to the user prompt
knowledge_retriever	Optional[Callable[..., Optional[List[Union[Dict, str]]]]]	None	Function to get references to add to the user_message
references_format	Literal["json", "yaml"]	"json"	Format of the references
metadata	Optional[Dict[str, Any]]	None	Metadata stored with this agent
tools	Optional[List[Union[Toolkit, Callable, Function, Dict]]]	None	A list of tools provided to the Model
tool_call_limit	Optional[int]	None	Maximum number of tool calls allowed for a single run
tool_choice	Optional[Union[str, Dict[str, Any]]]	None	Controls which (if any) tool is called by the model
tool_hooks	Optional[List[Callable]]	None	Functions that will run between tool calls
reasoning	bool	False	Enable reasoning by working through the problem step by step
reasoning_model	Optional[Model]	None	Model to use for reasoning
reasoning_agent	Optional[Agent]	None	Agent to use for reasoning
reasoning_min_steps	int	1	Minimum number of reasoning steps
reasoning_max_steps	int	10	Maximum number of reasoning steps
read_chat_history	bool	False	Add a tool that allows the Model to read the chat history
search_knowledge	bool	True	Add a tool that allows the Model to search the knowledge base
update_knowledge	bool	False	Add a tool that allows the Model to update the knowledge base
read_tool_call_history	bool	False	Add a tool that allows the Model to get the tool call history
send_media_to_model	bool	True	If False, media (images, videos, audio, files) is only available to tools and not sent to the LLM
store_media	bool	True	If True, store media in run output
system_message	Optional[Union[str, Callable, Message]]	None	Provide the system message as a string or function
system_message_role	str	"system"	Role for the system message
build_context	bool	True	Set to False to skip context building
description	Optional[str]	None	A description of the Agent that is added to the start of the system message
instructions	Optional[Union[str, List[str], Callable]]	None	List of instructions for the agent
expected_output	Optional[str]	None	Provide the expected output from the Agent
additional_context	Optional[str]	None	Additional context added to the end of the system message
markdown	bool	False	If markdown=true, add instructions to format the output using markdown
add_name_to_context	bool	False	If True, add the agent name to the instructions
add_datetime_to_context	bool	False	If True, add the current datetime to the instructions to give the agent a sense of time
add_location_to_context	bool	False	If True, add the current location to the instructions to give the agent a sense of place
timezone_identifier	Optional[str]	None	Allows for custom timezone for datetime instructions following the TZ Database format (e.g. “Etc/UTC”)
resolve_in_context	bool	True	If True, resolve session_state, dependencies, and metadata in the user and system messages
additional_input	Optional[List[Union[str, Dict, BaseModel, Message]]]	None	A list of extra messages added after the system message and before the user message
user_message_role	str	"user"	Role for the user message
build_user_context	bool	True	Set to False to skip building the user context
retries	int	0	Number of retries to attempt
delay_between_retries	int	1	Delay between retries (in seconds)
exponential_backoff	bool	False	If True, the delay between retries is doubled each time
input_schema	Optional[Type[BaseModel]]	None	Provide an input schema to validate the input
output_schema	Optional[Type[BaseModel]]	None	Provide a response model to get the response as a Pydantic model
parser_model	Optional[Model]	None	Provide a secondary model to parse the response from the primary model
parser_model_prompt	Optional[str]	None	Provide a prompt for the parser model
output_model	Optional[Model]	None	Provide an output model to structure the response from the main model
output_model_prompt	Optional[str]	None	Provide a prompt for the output model
parse_response	bool	True	If True, the response from the Model is converted into the output_schema
structured_outputs	Optional[bool]	None	Use model enforced structured_outputs if supported (e.g. OpenAIChat)
use_json_mode	bool	False	If output_schema is set, sets the response mode of the model, i.e. if the model should explicitly respond with a JSON object instead of a Pydantic model
save_response_to_file	Optional[str]	None	Save the response to a file
stream	Optional[bool]	None	Stream the response from the Agent
stream_intermediate_steps	bool	False	Stream the intermediate steps from the Agent
store_events	bool	False	Persist the events on the run response
events_to_skip	Optional[List[RunEvent]]	None	Specify which event types to skip when storing events on the RunOutput
role	Optional[str]	None	If this Agent is part of a team, this is the role of the agent in the team
debug_mode	bool	False	Enable debug logs
debug_level	Literal[1, 2]	1	Debug level for logging
telemetry	bool	True	Log minimal telemetry for analytics

​

Functions

​

run

Run the agent. Parameters:

• input (Union[str, List, Dict, Message, BaseModel, List[Message]]): The input to send to the agent
• stream (Optional[bool]): Whether to stream the response
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• 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[Sequence[Audio]]): Audio files to include
• images (Optional[Sequence[Image]]): Image files to include
• videos (Optional[Sequence[Video]]): Video files to include
• files (Optional[Sequence[File]]): Files to include
• retries (Optional[int]): Number of retries to attempt
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• add_history_to_context (Optional[bool]): Whether to add history to context
• add_dependencies_to_context (Optional[bool]): Whether to add dependencies to context
• add_session_state_to_context (Optional[bool]): Whether to add session state to context
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• metadata (Optional[Dict[str, Any]]): Metadata to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

​

arun

Run the agent asynchronously. Parameters:

• input (Union[str, List, Dict, Message, BaseModel, List[Message]]): The input to send to the agent
• stream (Optional[bool]): Whether to stream the response
• 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[Sequence[Audio]]): Audio files to include
• images (Optional[Sequence[Image]]): Image files to include
• videos (Optional[Sequence[Video]]): Video files to include
• files (Optional[Sequence[File]]): Files to include
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• retries (Optional[int]): Number of retries to attempt
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• add_history_to_context (Optional[bool]): Whether to add history to context
• add_dependencies_to_context (Optional[bool]): Whether to add dependencies to context
• add_session_state_to_context (Optional[bool]): Whether to add session state to context
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• metadata (Optional[Dict[str, Any]]): Metadata to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

Returns:

• Union[RunOutput, AsyncIterator[RunOutputEvent]]: Either a RunOutput or an iterator of RunOutputEvents, depending on the stream parameter

​

continue_run

Continue a run. Parameters:

• run_response (Optional[RunOutput]): The run response to continue
• run_id (Optional[str]): The run ID to continue
• updated_tools (Optional[List[ToolExecution]]): Updated tools to use, required if the run is resumed using run_id
• stream (Optional[bool]): Whether to stream the response
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• retries (Optional[int]): Number of retries to attempt
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

Returns:

• Union[RunOutput, Iterator[RunOutputEvent]]: Either a RunOutput or an iterator of RunOutputEvents, depending on the stream parameter

​

acontinue_run

Continue a run asynchronously. Parameters:

• run_response (Optional[RunOutput]): The run response to continue
• run_id (Optional[str]): The run ID to continue
• updated_tools (Optional[List[ToolExecution]]): Updated tools to use, required if the run is resumed using run_id
• stream (Optional[bool]): Whether to stream the response
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• user_id (Optional[str]): User ID to use
• session_id (Optional[str]): Session ID to use
• retries (Optional[int]): Number of retries to attempt
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

Returns:

• Union[RunOutput, AsyncIterator[Union[RunOutputEvent, RunOutput]]]: Either a RunOutput or an iterator of RunOutputEvents, depending on the stream parameter

​

print_response

Run the agent and print the response. Parameters:

• input (Union[List, Dict, str, Message, BaseModel, List[Message]]): The input to send to the agent
• session_id (Optional[str]): Session ID to use
• session_state (Optional[Dict[str, Any]]): Session state to use
• user_id (Optional[str]): User ID to use
• audio (Optional[Sequence[Audio]]): Audio files to include
• images (Optional[Sequence[Image]]): Image files to include
• videos (Optional[Sequence[Video]]): Video files to include
• files (Optional[Sequence[File]]): Files to include
• stream (Optional[bool]): Whether to stream the response
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• markdown (Optional[bool]): Whether to format output as markdown
• show_message (bool): Whether to show the message
• show_reasoning (bool): Whether to show reasoning
• show_full_reasoning (bool): Whether to show full reasoning
• console (Optional[Any]): Console to use for output
• tags_to_include_in_markdown (Optional[Set[str]]): Tags to include in markdown content
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• add_history_to_context (Optional[bool]): Whether to add history to context
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• metadata (Optional[Dict[str, Any]]): Metadata to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

​

aprint_response

Run the agent and print the response asynchronously. Parameters:

• input (Union[List, Dict, str, Message, BaseModel, List[Message]]): The input to send to the agent
• session_id (Optional[str]): Session ID to use
• session_state (Optional[Dict[str, Any]]): Session state to use
• user_id (Optional[str]): User ID to use
• audio (Optional[Sequence[Audio]]): Audio files to include
• images (Optional[Sequence[Image]]): Image files to include
• videos (Optional[Sequence[Video]]): Video files to include
• files (Optional[Sequence[File]]): Files to include
• stream (Optional[bool]): Whether to stream the response
• stream_intermediate_steps (Optional[bool]): Whether to stream intermediate steps
• markdown (Optional[bool]): Whether to format output as markdown
• show_message (bool): Whether to show the message
• show_reasoning (bool): Whether to show reasoning
• show_full_reasoning (bool): Whether to show full reasoning
• console (Optional[Any]): Console to use for output
• tags_to_include_in_markdown (Optional[Set[str]]): Tags to include in markdown content
• knowledge_filters (Optional[Dict[str, Any]]): Knowledge filters to apply
• add_history_to_context (Optional[bool]): Whether to add history to context
• dependencies (Optional[Dict[str, Any]]): Dependencies to use for this run
• metadata (Optional[Dict[str, Any]]): Metadata to use for this run
• debug_mode (Optional[bool]): Whether to enable debug mode

​

cli_app

Run an interactive command-line interface to interact with the agent. Parameters:

• input (Optional[str]): The input to send to the agent
• 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: “:sunglasses:”)
• stream (bool): Whether to stream the response (default: False)
• markdown (bool): Whether to format output as markdown (default: False)
• 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 agent asynchronously. Parameters:

• input (Optional[str]): The input to send to the agent
• 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: “:sunglasses:”)
• stream (bool): Whether to stream the response (default: False)
• markdown (bool): Whether to format output as markdown (default: False)
• exit_on (Optional[List[str]]): List of commands to exit the CLI
• **kwargs: Additional keyword arguments

​

cancel_run

Cancel a run by run ID. Parameters:

• run_id (str): The run ID to cancel

Returns:

• bool: True if the run was successfully cancelled

​

get_run_output

Get the run output for the given run ID. Parameters:

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

Returns:

• Optional[RunOutput]: The run output

​

get_last_run_output

Get the last run output for the session. Parameters:

• session_id (str): Session ID to use

Returns:

• Optional[RunOutput]: The last run output

​

get_session

Get the session for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• Optional[AgentSession]: The agent session

​

get_session_summary

Get the session summary for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• Session summary for the given session

​

get_user_memories

Get the user memories for the given user ID. Parameters:

• user_id (str): User ID to use

Returns:

• List[UserMemory]: The user memories

​

get_session_state

Get the session state for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• Dict[str, Any]: The session state

​

get_session_metrics

Get the session metrics for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• Optional[Metrics]: The session metrics

​

delete_session

Delete a session. Parameters:

• session_id (str): Session ID to delete

​

save_session

Save a session to the database. Parameters:

• session (AgentSession): The session to save

​

rename

Rename the agent and update the session. Parameters:

• name (str): The new name for the agent
• session_id (str): Session ID to use

​

get_session_name

Get the session name for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• str: The session name

​

set_session_name

Set the session name. Parameters:

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

Returns:

• AgentSession: The updated session

​

get_messages_for_session

Get the messages for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• List[Message]: The messages for the session

​

get_chat_history

Get the chat history for the given session ID. Parameters:

• session_id (str): Session ID to use

Returns:

• List[Message]: The chat history

​

add_tool

Add a tool to the agent. Parameters:

• tool (Union[Toolkit, Callable, Function, Dict]): The tool to add

​

set_tools

Replace the tools of the agent. Parameters:

• tools (List[Union[Toolkit, Callable, Function, Dict]]): The tools to set