AgentSession

AgentSession Attributes

Parameter	Type	Default	Description
`session_id`	`str`	Required	Session identifier; any string is accepted (a UUID is customary)
`agent_id`	`Optional[str]`	`None`	ID of the agent that this session is associated with
`team_id`	`Optional[str]`	`None`	ID of the team that this session is associated with
`user_id`	`Optional[str]`	`None`	ID of the user interacting with this agent
`workflow_id`	`Optional[str]`	`None`	ID of the workflow that this session is associated with
`session_data`	`Optional[Dict[str, Any]]`	`None`	Session Data: session_name, session_state, images, videos, audio
`metadata`	`Optional[Dict[str, Any]]`	`None`	Metadata stored with this agent
`agent_data`	`Optional[Dict[str, Any]]`	`None`	Agent Data: agent_id, name and model
`runs`	`Optional[List[Union[RunOutput, TeamRunOutput]]]`	`None`	List of all runs in the session
`summary`	`Optional[SessionSummary]`	`None`	Summary of the session
`created_at`	`Optional[int]`	`None`	The unix timestamp when this session was created
`updated_at`	`Optional[int]`	`None`	The unix timestamp when this session was last updated

AgentSession Methods

`upsert_run(run: RunOutput)`

Adds a RunOutput to the runs list. If a run with the same run_id already exists, it updates the existing run.

`get_run(run_id: str) -> Optional[Union[RunOutput, TeamRunOutput]]`

Returns a deep copy of the run with this run_id, or None if absent. Mutating the returned object does not update the session or persist a database change.

`get_messages(...) -> List[Message]`

Returns messages from matching top-level runs; member runs with a parent_run_id are excluded. Status filtering happens before last_n_runs and the message limit.

Parameters:

agent_id (Optional[str]): The id of the agent to get the messages from
team_id (Optional[str]): The id of the team to get the messages from
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]]): Defaults to None, which skips PAUSED, CANCELLED, ERROR, and REGENERATED runs. Pass [] to include every status
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_tool_calls(num_calls: Optional[int] = None) -> List[Dict[str, Any]]`

Returns tool calls from the session's messages, newest runs first. num_calls caps the number returned.

`get_session_summary() -> Optional[SessionSummary]`

Get the session summary for the session

`get_chat_history(...) -> List[Message]`

Returns history with system and tool messages excluded and status filtering disabled (skip_statuses=[]). Other roles can remain; this is not a strict user/assistant allowlist. Top-level run and duplicate-history filtering still apply. Use get_messages() to control these filters.

Parameters:

last_n_runs (Optional[int]): Number of recent runs to include. If None, all runs will be considered

Returns:

List[Message]: The chat history for the session

On this page