Conversation History

Learn about Team session history and managing conversation history.

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

For all forms of session history, you need to have a database assigned to the team. See Storage for more details.

We can give the Team access to the chat history in the following ways:

• Team-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 team leader.
  • 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 team 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 team allowing it to read tool calls in reverse chronological order.
  • You can enable search_session_history to allow searching through previous sessions.
  • You can set add_team_history_to_members=True and num_team_history_runs=5 to add the inputs and responses from the last 5 runs (that is the team-level inputs and responses) automatically to every message sent to the team members.
• Member-Level History:
  • You can also enable add_history_to_context for individual team members. This will only add the inputs and outputs for that member to all requests sent to that member, giving it access to its own history.

Working with team history can be tricky. Experiment with the above settings to find the best fit for your use case. See the History Reference for help on how to use the different history features.

History Reference

Simple History

Start with Team History in Context for basic conversation continuity:

team = Team(
    members=[...],
    db=SqliteDb(db_file="tmp/team.db"),
    add_history_to_context=True,
    num_history_runs=5,
)

Member Coordination

Use Team History to Members for shared context:

team = Team(
    members=[german_agent, spanish_agent],
    db=SqliteDb(db_file="tmp/team.db"),
    add_team_history_to_members=True,
    num_team_history_runs=3,
)

Share Interaction Information

Share Member Interactions during a run:

team = Team(
    members=[profile_agent, billing_agent],
    db=SqliteDb(db_file="tmp/team.db"),
    share_member_interactions=True,
)

Long Conversations

Add Chat History Tool when agents need to search history:

team = Team(
    members=[...],
    db=SqliteDb(db_file="tmp/team.db"),
    read_chat_history=True,  # Agent decides when to look up
)

Multi-Session Memory

Enable Multi-Session Search for cross-session continuity:

team = Team(
    members=[...],
    db=SqliteDb(db_file="tmp/team.db"),
    search_session_history=True,
    num_history_sessions=2,  # Keep low
)

Database Requirement: All history features require a database configured on the team. See Storage for setup.

Performance Tip: More history = larger context = slower and costlier requests. Start with num_history_runs=3 and increase only if needed.

Add history to the team 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 team leader. You can change the number of runs by setting num_history_runs=n where n is the number of runs to include.

Take a look at this example:

from agno.team import Team
from agno.models.google.gemini import Gemini
from agno.db.sqlite import SqliteDb

team = Team(
    model=Gemini(id="gemini-2.0-flash-001"),
    members=[],
    db=SqliteDb(db_file="tmp/data.db"),
    add_history_to_context=True,
    num_history_runs=3,
    description="You are a helpful assistant that always responds in a polite, upbeat and positive manner.",
)

team.print_response("Share a 2 sentence horror story", stream=True)

team.print_response("What was my first message?", stream=True)

See the full example in the Add history to the team context documentation.

Send team history to members

To send the team history to the members, you can set add_team_history_to_members=True. This will send the inputs and responses from the last 3 team-level runs (that is the default) to the members when tasks are delegated to them. You can change the number of runs by setting num_team_history_runs=n where n is the number of runs to include.

Take a look at this example:

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

german_agent = Agent(
    name="German Agent",
    role="You answer German questions.",
    model=OpenAIChat(id="o3-mini"),
)

spanish_agent = Agent(
    name="Spanish Agent",
    role="You answer Spanish questions.",
    model=OpenAIChat(id="o3-mini"),
)


multi_lingual_q_and_a_team = Team(
    name="Multi Lingual Q and A Team",
    model=OpenAIChat("o3-mini"),
    members=[german_agent, spanish_agent],
    instructions=[
        "You are a multi lingual Q and A team that can answer questions in English and Spanish. You MUST delegate the task to the appropriate member based on the language of the question.",
        "If the question is in German, delegate to the German agent. If the question is in Spanish, delegate to the Spanish agent.",
        "Always translate the response from the appropriate language to English and show both the original and translated responses.",
    ],
    db=SqliteDb(
        db_file="tmp/multi_lingual_q_and_a_team.db"
    ),  # Add a database to store the conversation history. This is a requirement for history to work correctly.
    determine_input_for_members=False,  # Send the input directly to the member agents without the team leader synthesizing its own input.
    respond_directly=True,  # The team leader will not process responses from the members and instead will return them directly.
    add_team_history_to_members=True,  # Send all interactions between the user and the team to the member agents.
)

# First give information to the team
## Ask question in German
multi_lingual_q_and_a_team.print_response(
    "Hallo, wie heißt du? Meine Name ist John.", stream=True, session_id="session_1"
)

# Then watch them recall the information (the question below states: "Tell me a 2-sentence story using my name")
## Follow up in Spanish
multi_lingual_q_and_a_team.print_response(
    "Cuéntame una historia de 2 oraciones usando mi nombre real.",
    stream=True,
    session_id="session_1",
)

In the above example the team history is sent to members who would not otherwise have access to it. That allows the Spanish agent to recall the information that was originally sent to the German agent.

add_team_history_to_members=True appends team history to the task sent to a team member, for example:

<team_history_context>
input: Hallo, wie heißt du? Meine Name ist John.
response: Ich heiße ChatGPT.
</team_history_context>

See the full example in the Team History for Members documentation.

Share member interactions with other members

All interactions with team members are automatically recorded. This includes the member name, the task that was given to the member, and the response from the member.

This is only available during a single run.

If you want members to have access to all interactions that has happened during the current run, you can set share_member_interactions=True.

See the example below and how information is shared between members during the run.

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


def get_user_profile() -> dict:
    """Get the user profile."""
    return {
        "name": "John Doe",
        "email": "[e-mail]",
        "phone": "1234567890",
        "billing_address": "123 Main St, Anytown, USA",
        "login_type": "email",
        "mfa_enabled": True,
    }


user_profile_agent = Agent(
    name="User Profile Agent",
    role="You are a user profile agent that can retrieve information about the user and the user's account.",
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[get_user_profile],
)

technical_support_agent = Agent(
    name="Technical Support Agent",
    role="You are a technical support agent that can answer questions about the technical support.",
    model=OpenAIChat(id="gpt-5-mini"),
)

billing_agent = Agent(
    name="Billing Agent",
    role="You are a billing agent that can answer questions about the billing.",
    model=OpenAIChat(id="gpt-5-mini"),
)


support_team = Team(
    name="Technical Support Team",
    model=OpenAIChat("o3-mini"),
    members=[user_profile_agent, technical_support_agent, billing_agent],
    instructions=[
        "You are a technical support team for a Facebook account that can answer questions about the technical support and billing for Facebook.",
        "Get the user's profile information first if the question is about the user's profile or account.",
    ],
    db=SqliteDb(
        db_file="tmp/technical_support_team.db"
    ),  # Add a database to store the conversation history. This is a requirement for history to work correctly.
    share_member_interactions=True,  # Send member interactions DURING the current run to the other members.
    show_members_responses=True,
)

## Ask question about technical support
support_team.print_response(
    "What is my billing address and how do I change it?",
    stream=True,
    session_id="session_1",
)

support_team.print_response(
    "Do I have multi-factor enabled? How do I disable it?",
    stream=True,
    session_id="session_1",
)

share_member_interactions=True appends interaction details to the task sent to a team member, for example:

<member_interaction_context>
- Member: Web Researcher
- Task: Find information about the web
- Response: I found information about the web

- Member: HackerNews Researcher
- Task: Find information about the web
- Response: I found information about the web
</member_interaction_context>

See the full example in the Share Member Interactions 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 team allowing it to read any message in the entire chat history.

from agno.team import Team
from agno.models.google.gemini import Gemini
from agno.db.sqlite import SqliteDb

team = Team(
    model=Gemini(id="gemini-2.0-flash-001"),
    members=[],
    db=SqliteDb(db_file="tmp/data.db"),
    read_chat_history=True,
    description="You are a helpful assistant that always responds in a polite, upbeat and positive manner.",
)

# Send lots of messages...

team.print_response("What was my first message?", stream=True)

Search the session history

In some scenarios, you might want to fetch messages from across multiple sessions to provide context or continuity in conversations.

To enable fetching messages from the last N sessions, you need to use the following flags:

• search_session_history: Set this to True to allow searching through previous sessions.
• num_history_sessions: Specify the number of past sessions to include in the search. In the example below, it is set to 2 to include only the last 2 sessions.

It’s advisable to keep this number low (2 or 3), as a larger number might fill up the context length of the model, potentially leading to performance issues.

Here’s an example of searching through the last 2 sessions:

session_history_search.py

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

if os.path.exists("tmp/data.db"):
    os.remove("tmp/data.db")

db = SqliteDb(db_file="tmp/data.db")

team = Team(
    members=[],
    model=OpenAIChat(id="gpt-5-mini"),
    user_id="user_1",
    db=db,
    search_session_history=True,  # allow searching previous sessions
    num_history_sessions=2,  # only include the last 2 sessions in the search to avoid context length issues
)

session_1_id = "session_1_id"
session_2_id = "session_2_id"
session_3_id = "session_3_id"
session_4_id = "session_4_id"
session_5_id = "session_5_id"

team.print_response("What is the capital of South Africa?", session_id=session_1_id)
team.print_response("What is the capital of China?", session_id=session_2_id)
team.print_response("What is the capital of France?", session_id=session_3_id)
team.print_response("What is the capital of Japan?", session_id=session_4_id)
team.print_response(
    "What did I discuss in my previous conversations?", session_id=session_5_id
)  # It should only include information from the last 2 sessions

Developer Resources

• View the Team schema
• View the Session schema
• View Cookbook