Agent

Parameters

Parameter	Type	Default	Description
model	Optional[Union[Model, str]]	None	Model to use for this Agent. Can be a Model object or a model string (provider:model_id)
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
overwrite_db_session_state	bool	False	Set to True to overwrite the session state in the database with the session state provided in the run
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
update_memory_on_run	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
compress_tool_results	bool	False	If True, compress tool call results to save context space
compression_manager	Optional[CompressionManager]	None	Custom compression manager for compressing tool call results
add_history_to_context	bool	False	Add the chat history of the current session to the messages sent to the Model
num_history_runs	Optional[int]	None	Number of historical runs to include in the messages.
num_history_messages	Optional[int]	None	Number of historical messages to include messages list sent to the Model.
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
max_tool_calls_from_history	Optional[int]	None	Maximum number of tool calls from history to keep in context. If None, all tool calls from history are included. If set to N, only the last N tool calls from history are added to the context for memory management
tool_hooks	Optional[List[Callable]]	None	Functions that will run between tool calls
pre_hooks	Optional[List[Union[Callable[..., Any], BaseGuardrail, BaseEval]]]	None	Functions called right after agent-session is loaded, before processing starts
post_hooks	Optional[List[Union[Callable[..., Any], BaseGuardrail, BaseEval]]]	None	Functions called after output is generated but before the response is returned
reasoning	bool	False	Enable reasoning by working through the problem step by step
reasoning_model	Optional[Union[Model, str]]	None	Model to use for reasoning. Can be a Model object or a model string (provider:model_id)
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 the database
store_tool_messages	bool	True	If True, store tool results in the database
store_history_messages	bool	False	If True, store history messages in the database
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
introduction	str	None	Introduction messaage for the Agent
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
add_instruction_tags	bool	True	If True, wrap the instructions in <instructions> tags in the system message. Set to False to pass instructions as-is without XML tags
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 when running the Agent
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[Union[Type[BaseModel], Dict[str, Any]]]	None	Provide a response model to get the response as a Pydantic model or a JSON schema
parser_model	Optional[Union[Model, str]]	None	Provide a secondary model to parse the response from the primary model. Can be a Model object or a model string (provider:model_id)
parser_model_prompt	Optional[str]	None	Provide a prompt for the parser model
output_model	Optional[Union[Model, str]]	None	Provide an output model to structure the response from the main model. Can be a Model object or a model string (provider:model_id)
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_events	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_events (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. By default, merged with the session state in the db.
• 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
• output_schema (Optional[Union[Type[BaseModel], Dict[str, Any]]]): Output schema to use for this run. Can be a Pydantic model or a JSON schema.
• 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. By default, merged with the session state in the db.
• 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_events (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
• output_schema (Optional[Union[Type[BaseModel], Dict[str, Any]]]): Output schema to use for this run. Can be a Pydantic model or a JSON schema.
• 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_events (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_events (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. By default, merged with the session state in the db.
• 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
• markdown (Optional[bool]): Whether to format output as markdown
• show_message (bool): Whether to show the input message
• show_reasoning (bool): Whether to show reasoning steps
• show_full_reasoning (bool): Whether to show full reasoning information
• 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
• 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
• 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. By default, merged with the session state in the db.
• 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
• 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
• 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

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:

• Optional[List[UserMemory]]: The user memories

aget_user_memories

Get the user memories for the given user ID asynchronously.

Parameters:

• user_id (str): User ID to use

Returns:

• Optional[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

update_session_state

Update the session state for the given session ID.

Parameters:

• session_id (str): Session ID to use
• session_state_updates (Dict[str, Any]): The session state keys and values to update. Overwrites the existing session state.

Returns:

• Dict[str, Any]: The updated session state

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 a session to the database.

Parameters:

• session (AgentSession): The session to save

asave_session

Save a session to the database asynchronously.

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_session_messages

Get the messages for the given session ID.

Parameters:

• session_id (Optional[str]): The session ID to get the messages for. If not provided, the latest used session ID is used.
• last_n_runs (Optional[int]): The number of runs to return messages from, counting from the latest. Defaults to all runs.
• limit (Optional[int]): The number of messages to return, counting from the latest. Defaults to all messages.
• skip_roles (Optional[List[str]]): Skip messages with these roles.
• skip_statuses (Optional[List[RunStatus]]): Skip messages with these statuses.
• skip_history_messages (bool): Skip messages that were tagged as history in previous runs. Defaults to True.

Returns:

• List[Message]: The messages for the session

get_chat_history

Get the chat history for the given session ID.

Parameters:

• session_id (Optional[str]): The session ID to get the chat history for. If not provided, the latest used session ID is used.
• last_n_runs (Optional[int]): The number of runs to return messages from, counting from the latest. Defaults to all runs.

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