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

# Debugging Teams

> Troubleshoot and inspect team behavior with debug mode, tracing, and common failure patterns.

Teams add coordination complexity. When something goes wrong, you need to trace execution across the leader and all members.

## Debug Mode

Enable debug mode to see the messages sent to the model, tool calls, delegation patterns, and metrics.

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

news_agent = Agent(name="News Agent", role="Get the latest news")
weather_agent = Agent(name="Weather Agent", role="Get weather forecasts")

team = Team(
    name="Research Team",
    members=[news_agent, weather_agent],
    model=OpenAIResponses(id="gpt-4o"),
    debug_mode=True
)

team.print_response("What is the weather in Tokyo?", show_members_responses=True)
```

Three ways to enable debug mode:

| Method                       | Scope                  |
| ---------------------------- | ---------------------- |
| `debug_mode=True` on Team    | All runs for this team |
| `debug_mode=True` on `run()` | Single run only        |
| `AGNO_DEBUG=True` env var    | All teams globally     |

Set `debug_level=2` for more detailed logs:

```python theme={null}
team = Team(
    name="Research Team",
    members=[news_agent, weather_agent],
    model=OpenAIResponses(id="gpt-4o"),
    debug_mode=True,
    debug_level=2
)
```

## What to Look For

When debugging, check:

| Issue                 | What to inspect                                |
| --------------------- | ---------------------------------------------- |
| Wrong member selected | Leader's reasoning, member roles               |
| Member not responding | Member's tool calls, errors                    |
| Slow execution        | Token counts, sequential vs parallel execution |
| Unexpected output     | Leader's synthesis step, member responses      |
| High token usage      | Coordination overhead, context size            |

## Common Failure Modes

### Leader Delegates to Wrong Member

The leader picks members based on their `role`. If delegation is wrong:

1. Check that roles clearly describe what each member does
2. Make roles distinct (avoid overlap)
3. Add instructions to the team leader

```python theme={null}
# Bad: Roles are vague
agent1 = Agent(name="Agent 1", role="Research things")
agent2 = Agent(name="Agent 2", role="Look stuff up")

# Good: Roles are specific and distinct
news_agent = Agent(name="News Agent", role="Get tech news from HackerNews")
finance_agent = Agent(name="Finance Agent", role="Get stock prices from Yahoo Finance")
```

### Member Fails Silently

If a member fails, the leader may synthesize a response without that member's output. Enable `show_members_responses=True` to see what each member returned:

```python theme={null}
team.print_response("Research AI trends", show_members_responses=True)
```

### Infinite Delegation Loop

The leader keeps delegating without producing a final response. This usually means:

1. Instructions are unclear about when to stop
2. Members are returning incomplete results

Add explicit stopping criteria to instructions:

```python theme={null}
team = Team(
    name="Research Team",
    members=[...],
    instructions=[
        "Delegate to members to gather information.",
        "Once you have enough information, synthesize and respond directly.",
        "Do not delegate more than 3 times per request."
    ]
)
```

### High Token Usage

Multi-agent coordination burns tokens. A 4-member team can easily use 10x the tokens of a single agent.

Check token usage in debug output or metrics:

```python theme={null}
response = team.run("Research AI trends")
print(f"Total tokens: {response.metrics.total_tokens}")
```

To reduce tokens:

* Use fewer members
* Keep member responses concise
* Use `mode=TeamMode.route` (or `respond_directly=True`) to skip synthesis

## Interactive CLI

Test multi-turn conversations with the built-in CLI:

```python theme={null}
from agno.team import Team
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses

news_agent = Agent(name="News Agent", role="Get the latest news")
weather_agent = Agent(name="Weather Agent", role="Get weather forecasts")

team = Team(
    name="Research Team",
    members=[news_agent, weather_agent],
    model=OpenAIResponses(id="gpt-4o"),
    db=SqliteDb(db_file="tmp/data.db"),
    add_history_to_context=True,
    num_history_runs=3
)

team.cli_app(stream=True)
```

Use `await team.acli_app()` for async.

## Tracing with AgentOS

For production debugging, connect your team to [AgentOS](/agent-os/overview) to get:

* Visual trace of all delegation and tool calls
* Token usage breakdown by member
* Session history and replay
* Error tracking

## Developer Resources

* [Team reference](/reference/teams/team)
* [Team examples](/cookbook/teams/overview)