How to Configure Agent Telemetry and Debug Logging in Agno for Troubleshooting

Enable debug_mode=True for verbose internal logs and set telemetry=False to disable analytics events when constructing any Agent, Workflow, or Team instance.

Agno provides two orthogonal observability mechanisms—telemetry and debug logging—that you can toggle independently to balance privacy, performance, and diagnostic visibility. This guide explains how to configure agent telemetry and debug logging in Agno using constructor flags and environment variables, based on the actual implementation in the agno-agi/agno repository.

Understanding Agno Observability Flags

Agno implements two distinct switches that control runtime behavior:

• Telemetry (telemetry: bool = True): Sends minimal "run started / finished" events to the Agno telemetry service for usage analytics and internal diagnostics. Enabled by default for all components.
• Debug Logging (debug_mode: bool = False, debug_level: Literal[1, 2] = 1): Emits verbose internal logs including stack traces, executed tool calls, and environment-variable-driven debug levels. Disabled by default.

Both flags are stored as plain attributes on the core classes and propagate to every sub-component that performs work, including executors, runners, and learning machines.

Where Telemetry and Debug Flags Live

The implementation follows a consistent pattern across Agents, Workflows, and Teams:

Component	Source File	Key Lines	Purpose
Agent	libs/agno/agno/agent/agent.py	440-449	Defines debug_mode, debug_level, and telemetry attributes
Agent Telemetry	libs/agno/agno/agent/_telemetry.py	39-61	Implements log_agent_telemetry() and alog_agent_telemetry()
Workflow	libs/agno/agno/workflow/workflow.py	440-449	Defines observability flags for workflow instances
Workflow Debug	libs/agno/agno/workflow/workflow.py	1503-1510	Activates debug mode via if self.debug_mode or getenv("AGNO_DEBUG", "false")...
Workflow Telemetry	libs/agno/agno/workflow/workflow.py	4696-4704	Contains _log_workflow_telemetry() emission logic
Team	libs/agno/agno/team/team.py	418-427	Defines flags for team orchestration
Team Telemetry	libs/agno/agno/team/_telemetry.py	41-74	Implements log_team_telemetry() and alog_team_telemetry()

Enabling Debug Logging for Troubleshooting

Pass debug_mode=True when instantiating any component to capture verbose execution details.

Debug Mode for Agents

from agno import Agent

agent = Agent(
    name="DebugAgent",
    model="gpt-4o-mini",
    debug_mode=True,
    debug_level=2,  # 1 = concise, 2 = very verbose

)

response = agent.run("Analyze this codebase structure")

Debug Mode for Workflows

from agno import Workflow, Agent

agent = Agent(name="Helper", model="gpt-4o-mini")
wf = Workflow(
    agents=[agent],
    debug_mode=True,
)

wf.run([{"role": "user", "content": "Summarize the last three messages"}])

When enabled, the runner checks self.debug_mode or the AGNO_DEBUG environment variable at lines 1503-1510 in workflow.py, then propagates the flag to nested executors that expose a debug_mode attribute.

Configuring Telemetry Settings

Telemetry emits lightweight payloads containing session_id, run_id, component ID, and timestamps to the Agno API. Disable it for privacy-sensitive deployments.

Disable Telemetry for a Single Agent

from agno import Agent

private_agent = Agent(
    name="PrivateAgent",
    model="gpt-4o-mini",
    telemetry=False,  # Prevents telemetry emission for this instance

)

response = private_agent.run("Process confidential data")

Disable Telemetry for Teams and Workflows

The same constructor parameter applies to Team and Workflow classes defined in libs/agno/agno/team/team.py and libs/agno/agno/workflow/workflow.py:

from agno import Team

team = Team(
    agents=[agent1, agent2],
    telemetry=False,
)

Global Configuration via Environment Variables

Set environment variables to apply debug settings globally across all Agno components without modifying constructor calls.

export AGNO_DEBUG=true          # Enable debug mode everywhere

export AGNO_DEBUG_LEVEL=2       # Set verbosity (1 or 2)

python my_script.py

The *_init.py helpers in agent/_init.py, team/_init.py, and workflow/_init.py (around lines 50-55) read these variables during object initialization and cast them to the appropriate literal types.

Overriding Global Settings Locally

Instance-level constructor arguments override environment variables:

import os
os.environ["AGNO_DEBUG"] = "true"

from agno import Team

# Global debug is on, but disabled for this specific team

team = Team(agents=[agent1], debug_mode=False)

Propagation to Sub-Components

When you invoke run(), the underlying runner (_run.run_sync or _run.run_async) receives the parent instance and propagates flags to nested objects. At lines 1503-1510 in workflow/workflow.py, the code executes:

if self.debug_mode or getenv("AGNO_DEBUG", "false").lower() == "true":
    self.debug_mode = True
    if hasattr(executor, "debug_mode"):
        executor.debug_mode = True

This ensures that executors, agent runners, and team runners inherit the debug setting for consistent logging across the execution chain.

Manual Telemetry Emission

For advanced use cases such as custom cookbooks or external monitoring, call the low-level telemetry functions directly:

from agno.agent._telemetry import log_agent_telemetry

log_agent_telemetry(
    agent=my_agent,
    session_id="sess-123",
    run_id="run-abc"
)

The function respects the current debug_mode flag and outputs a debug line if debugging is active, as implemented in libs/agno/agno/agent/_telemetry.py lines 39-61.

Summary

• Telemetry is enabled by default (telemetry=True) and sends minimal usage events to Agno; disable it with telemetry=False for privacy.
• Debug logging is disabled by default (debug_mode=False); enable it with debug_mode=True or AGNO_DEBUG=true to capture tool calls and stack traces.
• Flags are defined in agent.py, workflow.py, and team.py (lines 440-449, 418-427) and propagated to sub-components during execution.
• Environment variables AGNO_DEBUG and AGNO_DEBUG_LEVEL provide global control, while constructor arguments allow per-instance overrides.
• Manual telemetry emission is available via log_agent_telemetry() in agent/_telemetry.py for custom instrumentation.

Frequently Asked Questions

How do I completely disable telemetry in Agno for a production deployment?

Set telemetry=False in every Agent, Workflow, and Team constructor. According to the source code in libs/agno/agno/agent/agent.py (lines 440-449), this boolean attribute defaults to True and controls whether _log_agent_telemetry() executes at the end of a run. There is currently no global environment variable to disable telemetry across all components; you must explicitly set the flag per instance.

What is the difference between debug_mode=True and AGNO_DEBUG=true?

debug_mode=True is an instance-level constructor parameter that affects only that specific object, while AGNO_DEBUG=true is an environment variable that the *_init.py helpers check to set debug mode globally. If both are set, the instance-level flag takes precedence. The environment variable check appears in initialization helpers around lines 50-55 and uses getenv("AGNO_DEBUG", "false").lower() == "true" for evaluation.

Why am I not seeing tool call details in my logs even with debug mode enabled?

Ensure you set debug_level=2 for maximum verbosity. In libs/agno/agno/workflow/workflow.py (lines 1503-1510), the debug activation logic checks both self.debug_mode and the environment variable, but the verbosity of output depends on the debug_level attribute (1 for concise, 2 for verbose). Some internal utilities in libs/agno/agno/utils/print_response/ also gate detailed tool-call printing behind these flags.

Can I emit custom telemetry events from my own code?

Yes. Import the private telemetry helpers from agno.agent._telemetry, agno.workflow.workflow, or agno.team._telemetry and call log_agent_telemetry(), _log_workflow_telemetry(), or log_team_telemetry() respectively. These functions accept component instances, session IDs, and run IDs, then POST to the Agno telemetry endpoint via the internal API client, as seen in lines 39-61 of agent/_telemetry.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}