History Management

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.

Common Patterns

Automatic History (Most Common)

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

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

1team = Team(
2    model=OpenAIResponses(id="gpt-5.2"),
3    db=SqliteDb(db_file="tmp/data.db"),
4    add_history_to_context=True,
5    num_history_runs=3,  # Last 3 conversation turns
6)

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:

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

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

Programmatic Access

Retrieve history directly in your code:

1# All messages excluding those marked as from_history
2chat_history = agent.get_chat_history()
3
4# User-assistant message pairs from each run
5messages = agent.get_session_messages()
6
7# Last run output with metrics and tool calls
8last_run = agent.get_last_run_output()

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_session_history=True with num_history_sessions=2 (keep low to avoid context limits)
• Programmatic workflows: Call get_session_messages() / get_chat_history() directly in your code

Learn More

For comprehensive guides, detailed examples, and advanced patterns: