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_session_history 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

  • Simple History
  • Long Conversations
  • Multi-Session Memory
Start with Agent History in Context for basic conversation continuity:
agent = Agent(
    db=SqliteDb(db_file="tmp/agent.db"),
    add_history_to_context=True,
    num_history_runs=5,
)
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. To enable fetching messages from the last N sessions, you need to use the following flags:
  • search_session_history: Set this to True to allow searching through previous sessions.
  • num_history_sessions: Specify the number of past sessions to include in the search. In the example below, it is set to 2 to include only the last 2 sessions.
  • num_history_sessions: Specify the number of past sessions to include in the search.
Keep num_history_sessions low (2 or 3) to avoid filling up the context length of the model, which can lead to performance issues.

​
Developer Resources

Chat History Example

Learn how to manage and retrieve chat history in agent conversations.

Persistent Session with History

Control how much conversation history is included using num_history_runs.