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

# Chat History

> Include previous messages in context for multi-turn conversations.

Chat history gives each run messages from earlier runs in the same session. Configure a database and set `add_history_to_context=True` to add those messages to the model context.

## Enable Chat History

Set `add_history_to_context=True` to include previous messages in every run:

```python Agent theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb

agent = Agent(
    db=SqliteDb(db_file="agent.db"),
    add_history_to_context=True,
    num_history_runs=3,  # Include the last 3 runs
)

agent.print_response("My name is Sarah", session_id="chat_123")
agent.print_response("What's my name?", session_id="chat_123")  # Agent knows: "Sarah"
```

```python Team theme={null}
from agno.team import Team
from agno.db.sqlite import SqliteDb

team = Team(
    members=[...],
    db=SqliteDb(db_file="team.db"),
    add_history_to_context=True,
    num_history_runs=3,  # Include the last 3 runs
)

team.print_response("My name is Sarah", session_id="chat_123")
team.print_response("What's my name?", session_id="chat_123")  # Team knows: "Sarah"
```

> [!NOTE]
>
> Chat history requires a database that stores the session runs.

## Control History Size

More history means more tokens. Use these parameters to control what gets included:

| Parameter | Description |
| - | - |
| `num_history_runs` | Number of previous runs to include (default: 3) |
| `num_history_messages` | Maximum messages to include across all runs |
| `max_tool_calls_from_history` | Limit tool call messages in history |

```python theme={null}
agent = Agent(
    db=SqliteDb(db_file="agent.db"),
    add_history_to_context=True,
    num_history_messages=20,  # Cap at 20 messages total
)
```

Set `num_history_runs` or `num_history_messages`, not both. If both are set, `num_history_runs` is used.

> [!TIP]
>
> Start with `num_history_runs=3`. Increase only if your agent needs more context. For long conversations, combine limited history with [session summaries](https://agno-v2.mintlify.site/sessions/session-summaries.md).

## On-Demand History Access

Instead of always including history, let the agent decide when to look it up:

```python theme={null}
agent = Agent(
    db=SqliteDb(db_file="agent.db"),
    read_chat_history=True,  # Agent gets a get_chat_history() tool
)
```

The agent can call `get_chat_history()` when it needs context, rather than having history in every request. Useful for analytics, auditing, or when most queries don't need prior context.

## Cross-Session History

Search across multiple sessions for context that spans conversations:

```python theme={null}
agent = Agent(
    db=SqliteDb(db_file="agent.db"),
    search_past_sessions=True,
    num_past_sessions_to_search=2,  # Search last 2 sessions
)
```

The agent gets `search_past_sessions` and `read_past_session` tools to look up previous conversations.

> [!WARNING]
>
> Keep `num_past_sessions_to_search` low (2-3). Cross-session history can quickly fill your context window.

## Programmatic Access

Retrieve history directly in your code:

```python theme={null}
# Get user and assistant messages
chat_history = agent.get_chat_history(session_id="chat_123")

# Get all messages from the session
messages = agent.get_session_messages(session_id="chat_123")

# Get the last run output with metrics
last_run = agent.get_last_run_output()
```

Use this for building custom UIs, debugging, or exporting transcripts.

## Team History

Teams support additional history sharing between members:

```python theme={null}
team = Team(
    members=[...],
    db=SqliteDb(db_file="team.db"),
    add_history_to_context=True,
    num_history_runs=3,
    add_team_history_to_members=True,  # Share history across team members
)
```

With `add_team_history_to_members=True`, member agents see the full team conversation rather than only their own interactions.

## Workflow History

Workflows use `add_workflow_history_to_steps` to pass previous run results to steps:

```python theme={null}
from agno.workflow import Workflow

workflow = Workflow(
    db=SqliteDb(db_file="workflow.db"),
    add_workflow_history_to_steps=True,
    num_history_runs=5,
    steps=[...],
)
```

> [!NOTE]
>
> Workflow history passes previous workflow outputs to steps, not conversation messages. See [Workflow Sessions](https://agno-v2.mintlify.site/sessions/workflow-sessions.md) for details.

## Choosing a Pattern

| Scenario | Configuration |
| - | - |
| Chat-style products | `add_history_to_context=True`, `num_history_runs=3` |
| Long conversations | Limited history + [session summaries](https://agno-v2.mintlify.site/sessions/session-summaries.md) |
| Tool-heavy agents | Add `max_tool_calls_from_history` to reduce noise |
| Cross-session recall | `search_past_sessions=True`, `num_past_sessions_to_search=2` |
| Selective lookup | `read_chat_history=True` (agent decides when to look up) |
| Custom UIs | Use `get_chat_history()` programmatically |

## Developer Resources

* [Session Storage](https://agno-v2.mintlify.site/database/session-storage.md) - What gets stored and how to retrieve it.
* [AgentSession reference](https://agno-v2.mintlify.site/reference/agents/session.md)
* [TeamSession reference](https://agno-v2.mintlify.site/reference/teams/session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.