Chat History

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.

Prerequisites

For the SQLite/OpenAI examples:

uv pip install -U "agno[openai,sqlite]"
export OPENAI_API_KEY="your_openai_api_key"

Enable Chat History

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

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"

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

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.

Start with num_history_runs=3. Increase only if your agent needs more context. For long conversations, combine limited history with session summaries.

On-Demand History Access

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

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:

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.

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:

# 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:

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 receive selected previous team turns. num_team_history_runs bounds this member context (default 3) independently of the leader's num_history_runs.

Workflow History

Workflows use add_workflow_history_to_steps to pass previous run results to steps:

from agno.workflow import Workflow

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

Workflow history passes previous workflow outputs to steps, not conversation messages. See Workflow Sessions 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
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 - What gets stored and how to retrieve it.
AgentSession reference
TeamSession reference

On this page