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.

1from kern.team import Team
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5news_agent = Agent(name="News Agent", role="Get the latest news")
6weather_agent = Agent(name="Weather Agent", role="Get weather forecasts")
7
8team = Team(
9    name="Research Team",
10    members=[news_agent, weather_agent],
11    model=OpenAIResponses(id="gpt-4o"),
12    debug_mode=True
13)
14
15team.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:

1team = Team(
2    name="Research Team",
3    members=[news_agent, weather_agent],
4    model=OpenAIResponses(id="gpt-4o"),
5    debug_mode=True,
6    debug_level=2
7)

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:

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

1# Bad: Roles are vague
2agent1 = Agent(name="Agent 1", role="Research things")
3agent2 = Agent(name="Agent 2", role="Look stuff up")
4
5# Good: Roles are specific and distinct
6news_agent = Agent(name="News Agent", role="Get tech news from HackerNews")
7finance_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:

1team.print_response("Research AI trends", show_members_responses=True)

Infinite Delegation Loop

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

Instructions are unclear about when to stop
Members are returning incomplete results

Add explicit stopping criteria to instructions:

1team = Team(
2    name="Research Team",
3    members=[...],
4    instructions=[
5        "Delegate to members to gather information.",
6        "Once you have enough information, synthesize and respond directly.",
7        "Do not delegate more than 3 times per request."
8    ]
9)

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:

1response = team.run("Research AI trends")
2print(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:

1from kern.team import Team
2from kern.agent import Agent
3from kern.db.sqlite import SqliteDb
4from kern.models.openai import OpenAIResponses
5
6news_agent = Agent(name="News Agent", role="Get the latest news")
7weather_agent = Agent(name="Weather Agent", role="Get weather forecasts")
8
9team = Team(
10    name="Research Team",
11    members=[news_agent, weather_agent],
12    model=OpenAIResponses(id="gpt-4o"),
13    db=SqliteDb(db_file="tmp/data.db"),
14    add_history_to_context=True,
15    num_history_runs=3
16)
17
18team.cli_app(stream=True)

Use await team.acli_app() for async.

Tracing with AgentOS

For production debugging, connect your team to AgentOS to get:

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