> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-studio-tools-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat History in Agents

> Configure and access agent conversation history.

Agents with storage enabled automatically have access to the run history of the session (also called the "conversation history" or "chat history").

<Note>
  For all forms of session history, you need to have a database assigned to the agent. See [Storage](/database/overview) for more details.
</Note>

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.

<Tip>
  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](#history-reference) for help on how to use the different history features.
</Tip>

## History Reference

<Tabs>
  <Tab title="Simple History">
    Start with **Agent History in Context** for basic conversation continuity:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        add_history_to_context=True,
        num_history_runs=5,
    )
    ```
  </Tab>

  <Tab title="Long Conversations">
    Add **Chat History Tool** when agents need to search history:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        read_chat_history=True,  # Agent decides when to look up
    )
    ```
  </Tab>

  <Tab title="Multi-Session Memory">
    Enable **Multi-Session Search** for cross-session continuity:

    ```python theme={null}
    agent = Agent(
        db=SqliteDb(db_file="tmp/agent.db"),
        search_session_history=True,
        num_history_sessions=2,  # Keep low
    )
    ```
  </Tab>
</Tabs>

<Note>
  **Database Requirement**: All history features require a database configured on the agent. See [Storage](/database/overview) for setup.
</Note>

<Tip>
  **Performance Tip**: More history = larger context = slower and costlier requests. Start with `num_history_runs=3` and increase only if needed.
</Tip>

### 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](/history/agent/persistent-session-history) example for a complete implementation.

Learn more in the [Context Engineering](/context/overview) 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](/history/agent/chat-history) 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.

<Tip>
  Keep `num_history_sessions` low (2 or 3) to avoid filling up the context length of the model, which can lead to performance issues.
</Tip>

## Developer Resources

<CardGroup cols={2}>
  <Card title="Chat History Example" icon="message" iconType="duotone" href="/history/agent/chat-history">
    Learn how to manage and retrieve chat history in agent conversations.
  </Card>

  <Card title="Persistent Session with History" icon="database" iconType="duotone" href="/history/agent/persistent-session-history">
    Control how much conversation history is included using num\_history\_runs.
  </Card>
</CardGroup>