History Management

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

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

Agents and Teams with a database configured automatically track message and run history. You have multiple ways to access and use this history to give your agents and teams "memory" of past conversations.

The fragments below reuse this setup:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.team import Team

Common Patterns

Automatic History (Most Common)

Enable add_history_to_context=True to automatically include recent messages in every run:

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/data.db"),
    add_history_to_context=True,
    num_history_runs=3,  # Last 3 conversation turns
)

When to use: Chat-style products, quick prototypes, any scenario where responses need context from previous turns.

On-Demand History Access

Enable read_chat_history=True to let the model decide when to look up history:

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/data.db"),
    read_chat_history=True,  # Model can call get_chat_history() tool
)

When to use: Analytics, auditing, or when you want the model to selectively access history rather than always including it.

Programmatic Access

After running the Agent from the previous fragment, retrieve history directly in your code:

agent.run("Hello, my name is Alice", session_id="history-example")

# User and assistant messages for the session
chat_history = agent.get_chat_history(session_id="history-example")

# All session messages, excluding those tagged as history in previous runs
messages = agent.get_session_messages(session_id="history-example")

# Last run output with metrics and tool calls
last_run = agent.get_last_run_output(session_id="history-example")

When to use: Building your own UI, analytics, debugging, or when you need raw transcripts.

Choosing a Pattern

Short chats: Leave defaults (history off) or enable add_history_to_context with num_history_runs=3
Long-lived threads: Combine limited history (num_history_runs=2) with session summaries to keep tokens manageable
Tool-heavy agents: Use max_tool_calls_from_history to limit tool call noise in context
Audit/debug flows: Enable read_chat_history=True so the model looks things up only when needed
Cross-session recall: Use search_past_sessions=True with num_past_sessions_to_search=2 (keep low to avoid context limits)
Programmatic workflows: Call get_session_messages() / get_chat_history() directly in your code