Chat History in Agents

Before running the examples, create and activate a virtual environment:

uv pip install agno openai sqlalchemy
export OPENAI_API_KEY="your-api-key"

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

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.

The fragments below reuse this setup:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb

History Reference

agent = Agent(
    db=SqliteDb(db_file="tmp/agent.db"),
    add_history_to_context=True,
    num_history_runs=5,
)

agent = Agent(
    db=SqliteDb(db_file="tmp/agent.db"),
    read_chat_history=True,  # Agent decides when to look up
)

agent = Agent(
    db=SqliteDb(db_file="tmp/agent.db"),
    search_past_sessions=True,
    num_past_sessions_to_search=10,
)

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.

Developer Resources