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)
fallback_models	Optional[List[Union[Model, str]]]	None	Models tried in order when the primary model fails. Ignored if fallback_config is set
fallback_config	Optional[FallbackConfig]	None	Fallback configuration for model failures, with support for error-specific routing. Takes precedence over fallback_models
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_past_sessions	Optional[bool]	False	Add tools that let the agent search past sessions and read their full conversations
num_past_sessions_to_search	Optional[int]	None	Maximum number of past sessions returned by the search_past_sessions tool. Defaults to 20 when unset
num_past_session_runs_in_search	Optional[int]	None	Number of runs included in each session preview returned by the search_past_sessions tool. Defaults to 3 when unset
search_session_history	Optional[bool]	None	(deprecated, use search_past_sessions)
num_history_sessions	Optional[int]	None	(deprecated, use num_past_sessions_to_search)
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
checkpoint	Optional[Literal["runs", "tool-batch", "tools"]]	None	When to persist run state to the database. "runs" writes only at terminal states; "tool-batch" also writes after each model turn. None falls back to the AgentOS-level setting, else "runs". "tools" is reserved for 3.0
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
enable_user_memories	Optional[bool]	None	(deprecated, use update_memory_on_run)
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[Union[KnowledgeProtocol, Callable[..., KnowledgeProtocol]]]	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
skills	Optional[Skills]	None	Skills for this agent. Loads structured instructions, reference docs, and scripts, and gives the agent tools to access them
metadata	Optional[Dict[str, Any]]	None	Metadata stored with this agent
tools	Optional[Union[List[Union[Toolkit, Callable, Function, Dict]], Callable[..., List]]]	None	A list of tools provided to the Model, or a callable factory that returns the list
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
add_search_knowledge_instructions	bool	True	If True, add instructions for using the search_knowledge tool to the system message
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
use_instruction_tags	bool	False	If True, wrap the instructions in <instructions> tags in the system message
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
datetime_format	Optional[str]	None	Custom format string for the datetime added to context (e.g. "%Y-%m-%d %H:%M:%S"). If None, the default datetime string representation is used
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
learning	Optional[Union[bool, LearningMachine]]	None	Enable learning for this agent. True creates a default LearningMachine with user profile and user memory stores; pass a LearningMachine for full control. Requires db
add_learnings_to_context	bool	True	If True, add learnings to the system message when learning is enabled
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
followups	bool	False	If True, generate followup prompt suggestions after the main response and set them on RunOutput.followups
num_followups	int	3	Number of followup prompts to generate
followup_model	Optional[Union[Model, str]]	None	Model used to generate followups. Defaults to the agent’s model
stream	Optional[bool]	None	Stream the response from the Agent
stream_events	Optional[bool]	None	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
culture_manager	Optional[CultureManager]	None	Culture manager for shared cultural knowledge (experimental)
enable_agentic_culture	bool	False	Give the agent tools to manage cultural knowledge (experimental)
update_cultural_knowledge	bool	False	If True, update cultural knowledge after every run (experimental)
add_culture_to_context	Optional[bool]	None	If True, add cultural knowledge to the context (experimental)
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
cache_callables	bool	True	Cache the results of callable tools and knowledge factories between runs
callable_tools_cache_key	Optional[Callable[..., Optional[str]]]	None	Function that returns the cache key for the callable tools factory. Defaults to user_id or session_id from the run context
callable_knowledge_cache_key	Optional[Callable[..., Optional[str]]]	None	Function that returns the cache key for the callable knowledge factory. Defaults to user_id or session_id from the run context

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