Skip to main content
Agents with storage enabled automatically have access to the run history of the session (also called the “conversation history” or “chat history”).
For all forms of session history, you need to have a database assigned to the agent. See Storage for more details.
We can give the Agent access to the chat history in the following ways:

​
Agent-Level History

  • You can set add_history_to_context=True and num_history_runs=5 to add the inputs and responses from the last 5 runs automatically to every request sent to the agent.
  • You can be more granular about how many messages to add to include in the list sent to the model, by setting num_history_messages.
  • You can set read_chat_history=True to provide a get_chat_history() tool to your agent allowing it to read any message in the entire chat history.
  • You can set read_tool_call_history=True to provide a get_tool_call_history() tool to your agent allowing it to read tool calls in reverse chronological order.
  • You can enable search_past_sessions to allow searching through previous sessions.
Working with agent history can be tricky. Experiment with the above settings to find the best fit for your use case. See the History Reference for help on how to use the different history features.

​
History Reference

Start with Agent History in Context for basic conversation continuity:
Database Requirement: All history features require a database configured on the agent. See Storage for setup.
Performance Tip: More history = larger context = slower and costlier requests. Start with num_history_runs=3 and increase only if needed.

​
Add history to the agent context

To add the history of the conversation to the context, you can set add_history_to_context=True. This will add the inputs and responses from the last 3 runs (that is the default) to the context of the agent. You can change the number of runs by setting num_history_runs=n where n is the number of runs to include. You can either set add_history_to_context=True on the Agent or on the run() method directly. See the Persistent Session with History example for a complete implementation. Learn more in the Context Engineering documentation.

​
Read the chat history

To read the chat history, you can set read_chat_history=True. This will provide a get_chat_history() tool to your agent allowing it to read any message in the entire chat history. See the Chat History Management page for a complete implementation.

​
Search the session history

In some scenarios, you might want to fetch messages from across multiple sessions to provide context or continuity in conversations. Set search_past_sessions=True to give the agent two tools: search_past_sessions() returns previews of recent sessions, and read_past_session(session_id) returns the full conversation for a specific session.
  • num_past_sessions_to_search: Maximum number of past sessions to search. Defaults to 20.
  • num_past_session_runs_in_search: Number of runs per session shown in the preview. Defaults to 3.
Keep num_past_sessions_to_search low to avoid filling up the context length of the model, which can lead to performance issues.

​
Developer Resources

Chat History Example

Retrieve stored messages from agent conversations with get_chat_history().

Persistent Session with History

Control how much conversation history is included using num_history_runs.