Debugging Agents

Inspect execution flow, tool calls, and intermediate steps.

Debug mode helps you understand the flow of execution and intermediate steps:

  • Inspect the messages sent to the model and the response it generates
  • Trace intermediate steps and monitor metrics like token usage and execution time
  • Inspect tool calls, errors, and their results

Before you run

Create and activate a Python virtual environment, then install the packages and set your provider key:

uv pip install -U agno anthropic sqlalchemy
export ANTHROPIC_API_KEY="your-anthropic-api-key"

On Windows PowerShell, set $Env:ANTHROPIC_API_KEY instead. Save each complete example in its own Python file and run it from the activated environment. SQLite storage in the CLI example uses the local tmp/data.db file.

Debug Mode

To enable debug mode:

  1. Set debug_mode=True on your agent to enable it for all runs.
  2. Set debug_mode=True on the run method to enable it for a single run.
  3. Set the AGNO_DEBUG=True environment variable to enable debug mode globally.
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    instructions="Write a report on the topic. Output only the report.",
    markdown=True,
    debug_mode=True,
    # debug_level=2, # Uncomment for more detailed logs
)

# Run agent and print response to the terminal
agent.print_response("Trending startups and products.")

Set debug_level=2 for more detailed logs.

Interactive CLI

Agno includes a pre-built interactive CLI that runs your Agent as a command-line application. Use it to test multi-turn conversations:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    db=SqliteDb(db_file="tmp/data.db"),
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

# Run agent as an interactive CLI app
agent.cli_app(stream=True)