Team State

There are multiple ways to share state between team members.

Shared Team State

Team Session State enables sophisticated state management across teams of agents, with both shared and private state capabilities. Teams often need to coordinate on shared information (like a shopping list) while maintaining their own private metrics or configuration. Agno provides an elegant three-tier state system for this. Agno’s Team state management provides three distinct levels:

Team’s team_session_state - Shared state accessible by all team members.
Team’s session_state - Private state only accessible by the team leader
Agent’s session_state - Private state for each agent members

Team state propagates through nested team structures as well

How to use Team Session State

You can set the team_session_state parameter on Team to share state between team members. This state is available to all team members and is synchronized between them. For example:

team = Team(
    members=[agent1, agent2, agent3],
    team_session_state={"shopping_list": []},
)

Members can access the shared state using the team_session_state attribute in tools. For example:

def add_item(agent: Agent, item: str) -> str:
    """Add an item to the shopping list and return confirmation.

    Args:
        item (str): The item to add to the shopping list.
    """
    # Add the item if it's not already in the list
    if item.lower() not in [
        i.lower() for i in agent.team_session_state["shopping_list"]
    ]:
        agent.team_session_state["shopping_list"].append(item)
        return f"Added '{item}' to the shopping list"
    else:
        return f"'{item}' is already in the shopping list"

Example

Here’s a simple example of a team managing a shared shopping list:

team_session_state.py

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.team import Team


# Define tools that work with shared team state
def add_item(agent: Agent, item: str) -> str:
    """Add an item to the shopping list."""
    if item.lower() not in [
        i.lower() for i in agent.team_session_state["shopping_list"]
    ]:
        agent.team_session_state["shopping_list"].append(item)
        return f"Added '{item}' to the shopping list"
    else:
        return f"'{item}' is already in the shopping list"


def remove_item(agent: Agent, item: str) -> str:
    """Remove an item from the shopping list."""
    for i, list_item in enumerate(agent.team_session_state["shopping_list"]):
        if list_item.lower() == item.lower():
            agent.team_session_state["shopping_list"].pop(i)
            return f"Removed '{list_item}' from the shopping list"
    
    return f"'{item}' was not found in the shopping list"


# Create an agent that manages the shopping list
shopping_agent = Agent(
    name="Shopping List Agent",
    role="Manage the shopping list",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[add_item, remove_item],
)


# Define team-level tools
def list_items(team: Team) -> str:
    """List all items in the shopping list."""
    # Access shared state (not private state)
    shopping_list = team.team_session_state["shopping_list"]
    
    if not shopping_list:
        return "The shopping list is empty."
    
    items_text = "\n".join([f"- {item}" for item in shopping_list])
    return f"Current shopping list:\n{items_text}"


def add_chore(team: Team, chore: str) -> str:
    """Add a completed chore to the team's private log."""
    # Access team's private state
    if "chores" not in team.session_state:
        team.session_state["chores"] = []
    
    team.session_state["chores"].append(chore)
    return f"Logged chore: {chore}"


# Create a team with both shared and private state
shopping_team = Team(
    name="Shopping Team",
    mode="coordinate",
    model=OpenAIChat(id="gpt-4o-mini"),
    members=[shopping_agent],
    # Shared state - accessible by all members
    team_session_state={"shopping_list": []},
    # Team's private state - only accessible by team
    session_state={"chores": []},
    tools=[list_items, add_chore],
    instructions=[
        "You manage a shopping list.",
        "Forward add/remove requests to the Shopping List Agent.",
        "Use list_items to show the current list.",
        "Log completed tasks using add_chore.",
    ],
    show_tool_calls=True,
)

# Example usage
shopping_team.print_response("Add milk, eggs, and bread", stream=True)
print(f"Shared state: {shopping_team.team_session_state}")

shopping_team.print_response("What's on my list?", stream=True)

shopping_team.print_response("I got the eggs", stream=True)
print(f"Shared state: {shopping_team.team_session_state}")
print(f"Team private state: {shopping_team.session_state}")

Notice how shared tools use agent.team_session_state, which allows state to propagate and persist across the entire team — even for subteams within the team. This ensures consistent shared state for all members.In contrast, tools specific to a team use team.session_state, allowing for private, team-specific state. For example, a team leader’s tools would maintain their own session state using team.session_state.

See a full example here.

Agentic Context

The Team Leader maintains a shared context that is updated agentically (i.e. by the team leader) and is sent to team members if needed. Agentic Context is critical for effective information sharing and collaboration between agents and the quality of the team’s responses depends on how well the team leader manages this shared agentic context. This could require higher quality models for the team leader to ensure the quality of the team’s responses.

The tasks and responses of team members are automatically added to the team context, but Agentic Context needs to be enabled by the developer.

Enable Agentic Context

To enable the Team leader to maintain Agentic Context, set enable_agentic_context=True. This will allow the team leader to maintain and update the team context during the run.

team = Team(
    members=[agent1, agent2, agent3],
    enable_agentic_context=True,  # Enable Team Leader to maintain Agentic Context
)

Team Member Interactions

Agent Teams can share interactions between members, allowing agents to learn from each other’s outputs:

team = Team(
    members=[agent1, agent2, agent3],
    share_member_interactions=True,  # Share interactions
)

Introduction

Concepts

Other

How to

Shared Team State

How to use Team Session State

Example

Agentic Context

Enable Agentic Context

Team Member Interactions

​Shared Team State

​How to use Team Session State

​Example

​Agentic Context

​Enable Agentic Context

​Team Member Interactions

Shared Team State

How to use Team Session State

Example

Agentic Context

Enable Agentic Context

Team Member Interactions