> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Teams

> Define team members, roles, and structure for multi-agent coordination.

Start simple: a model, team members, and instructions. Add functionality as needed.

## Minimal Example

```python research_team.py theme={null}
from agno.team import Team
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.hackernews import HackerNewsTools
from agno.tools.yfinance import YFinanceTools

news_agent = Agent(
    name="News Agent",
    role="Get trending tech news from HackerNews",
    tools=[HackerNewsTools()]
)

finance_agent = Agent(
    name="Finance Agent",
    role="Get stock prices and financial data",
    tools=[YFinanceTools()]
)

team = Team(
    name="Research Team",
    members=[news_agent, finance_agent],
    model=OpenAIResponses(id="gpt-5.4-mini"),
    instructions="Delegate to the appropriate agent based on the request."
)

team.print_response("What are the trending AI stories and how is NVDA stock doing?", stream=True)
```

## Run the Minimal Example

<Snippet file="create-venv-step.mdx" />

**1. Install dependencies**

```bash theme={null}
uv pip install -U agno openai yfinance
```

**2. Export your OpenAI API key**

```bash Mac/Linux theme={null}
export OPENAI_API_KEY="your_openai_api_key_here"
```

```powershell Windows theme={null}
$Env:OPENAI_API_KEY="your_openai_api_key_here"
```

**3. Run the team**

```bash theme={null}
python research_team.py
```

## Team Modes

Teams default to coordinate mode (leader delegates and synthesizes). Set `mode` to change how the leader collaborates with members.

```python theme={null}
from agno.team.mode import TeamMode
from agno.models.openai import OpenAIResponses

team = Team(
    name="Language Router",
    members=[...],
    model=OpenAIResponses(id="gpt-5.4-mini"),
    mode=TeamMode.route
)
```

<Snippet file="team-snippet.mdx" />

Tasks mode runs an iterative task loop. Use `max_iterations` to cap how many cycles the leader can run.

```python theme={null}
from agno.team.mode import TeamMode
from agno.models.openai import OpenAIResponses

team = Team(
    name="Ops Team",
    members=[...],
    model=OpenAIResponses(id="gpt-5.4-mini"),
    mode=TeamMode.tasks,
    max_iterations=6
)
```

## Team Members

Each member should have a `name` and `role`. The team leader uses these to decide who handles what.

```python theme={null}
news_agent = Agent(
    name="News Agent",                              # Identifies the agent
    role="Get trending tech news from HackerNews",  # Tells the leader what this agent does
    tools=[HackerNewsTools()]
)
```

For better tracing, also set an `id`:

```python theme={null}
news_agent = Agent(
    id="news-agent",
    name="News Agent",
    role="Get trending tech news from HackerNews",
    tools=[HackerNewsTools()]
)
```

When both `id` and `name` are set on a member, team delegation uses `id` as the member identifier.

> [!NOTE]
>
> Members must be native Agno `Agent` or `Team` instances. External-framework
> adapters (`ClaudeAgent`, `LangGraphAgent`, `DSPyAgent`) can be served by
> AgentOS as standalone agents but cannot be a member agent of an Agno Team or an agent of a Workflow Step yet. See
> [Multi-Framework Support](https://agno-v2.mintlify.site/agent-os/multi-framework/overview.md).

## Nested Teams

Teams can contain other teams. The top-level leader delegates to sub-team leaders, who delegate to their members.

```python theme={null}
from agno.team import Team
from agno.agent import Agent

team = Team(
    name="Language Team",
    members=[
        Agent(name="English Agent", role="Answer in English"),
        Agent(name="Chinese Agent", role="Answer in Chinese"),
        Team(
            name="Germanic Team",
            role="Handle German and Dutch questions",
            members=[
                Agent(name="German Agent", role="Answer in German"),
                Agent(name="Dutch Agent", role="Answer in Dutch"),
            ],
        ),
    ],
)
```

## Model Inheritance

Agent members inherit the parent team's `model` when their own model is unset. Nested teams initialize their own model unless you set one explicitly.

```python theme={null}
from agno.team import Team
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.models.anthropic import Claude

# This agent uses its own model (Claude)
agent_with_model = Agent(
    name="Claude Agent",
    model=Claude(id="claude-sonnet-4-5"),
    role="Research with Claude"
)

# This agent inherits gpt-5.4-mini from the team
agent_without_model = Agent(
    name="Inherited Agent",
    role="Research with inherited model"
)

team = Team(
    name="Research Team",
    model=OpenAIResponses(id="gpt-5.4-mini"),  # Default for team and members without a model
    members=[agent_with_model, agent_without_model]
)
```

## Callable Factories

Pass a function instead of a static list for `members`, `tools`, or `knowledge`. Factories resolve during run setup. By default, results are cached by custom key, then user ID, then session ID. Set `cache_callables=False`, as below, to resolve on every run.

```python team_callable_members.py theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.team import Team

writer = Agent(
    name="Writer",
    role="Content writer",
    model=OpenAIResponses(id="gpt-5-mini"),
    instructions=["Write clear, concise content."],
)

researcher = Agent(
    name="Researcher",
    role="Research analyst",
    model=OpenAIResponses(id="gpt-5-mini"),
    instructions=["Research topics and summarize findings."],
)


def pick_members(session_state: dict):
    if session_state.get("needs_research", False):
        return [researcher, writer]
    return [writer]


team = Team(
    name="Content Team",
    model=OpenAIResponses(id="gpt-5-mini"),
    members=pick_members,
    cache_callables=False,
)

team.print_response(
    "Write a haiku about Python",
    session_state={"needs_research": False},
    stream=True,
)

team.print_response(
    "Research the history of Python and write a short summary",
    session_state={"needs_research": True},
    stream=True,
)
```

The same pattern works for `tools` and `knowledge`. Agents also support callable factories for `tools` and `knowledge`.

### Injected Parameters

Name your factory function parameters to receive context automatically:

| Parameter | Type | Description |
| - | - | - |
| `agent` | `Team` | Owning Team instance. This alias supports factories shared by Agents and Teams. |
| `team` | `Team` | Owning Team instance. |
| `run_context` | `RunContext` | Run context with `user_id`, `session_id`, `session_state` |
| `session_state` | `dict` | Session state dict directly (defaults to `{}` if `None`) |

Use any combination. A zero-argument factory also works.

### `add_tool` and `set_tools`

`add_tool()` raises `RuntimeError` when `tools` is a callable factory. Use `set_tools()` to replace the factory entirely:

```python theme={null}
team = Team(members=[...], tools=tools_for_user)

team.add_tool(some_tool)              # raises RuntimeError

team.set_tools(new_factory)           # replace with a new factory
team.set_tools([DuckDuckGoTools()])   # replace with a static list
```

### Callable Caching Settings

<Snippet file="concept-callable-factories-caching.mdx" />

## Team Features

Teams support the same features as agents:

| Feature | Description |
| - | - |
| Instructions | Guide the team leader on how to coordinate |
| Mode | Choose the coordination strategy (`coordinate`, `route`, `broadcast`, `tasks`) |
| Database | Persist session history and state |
| Reasoning | Enable the leader to plan before delegating |
| Knowledge | Give the leader access to a knowledge base |
| Memory | Store and recall information across sessions |
| Tools | Give the leader tools to use directly |
| Skills | Give the leader domain expertise via instructions, scripts, and references |

See the guides below to add these features.

## Next Steps

| Task | Guide |
| - | - |
| Run teams | [Running Teams](https://agno-v2.mintlify.site/teams/running-teams.md) |
| Control delegation | [Delegation](https://agno-v2.mintlify.site/teams/delegation.md) |
| Add skills | [Team Skills](https://agno-v2.mintlify.site/skills/team-skills.md) |
| Add chat history | [Chat History](https://agno-v2.mintlify.site/history/team/overview.md) |
| Manage sessions | [Sessions](https://agno-v2.mintlify.site/sessions/overview.md) |
| Handle input/output | [Input and Output](https://agno-v2.mintlify.site/input-output/overview.md) |
| Add knowledge | [Knowledge](https://agno-v2.mintlify.site/knowledge/overview.md) |
| Add guardrails | [Guardrails](https://agno-v2.mintlify.site/guardrails/overview.md) |

## Developer Resources

* [Team reference](https://agno-v2.mintlify.site/reference/teams/team.md)
* [Team examples](https://agno-v2.mintlify.site/examples/teams/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.