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

> Troubleshoot Agno issues by configuring agent telemetry and debug logging. Learn how to enable verbose logs and disable analytics for effective debugging.

- Repository: [Agno/agno](https://github.com/agno-agi/agno)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/agent/agent.py) | 440-449 | Defines `debug_mode`, `debug_level`, and `telemetry` attributes |
| **Agent Telemetry** | [`libs/agno/agno/agent/_telemetry.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/agent/_telemetry.py) | 39-61 | Implements `log_agent_telemetry()` and `alog_agent_telemetry()` |
| **Workflow** | [`libs/agno/agno/workflow/workflow.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/workflow/workflow.py) | 440-449 | Defines observability flags for workflow instances |
| **Workflow Debug** | [`libs/agno/agno/workflow/workflow.py`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/workflow/workflow.py) | 4696-4704 | Contains `_log_workflow_telemetry()` emission logic |
| **Team** | [`libs/agno/agno/team/team.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/team/team.py) | 418-427 | Defines flags for team orchestration |
| **Team Telemetry** | [`libs/agno/agno/team/_telemetry.py`](https://github.com/agno-agi/agno/blob/main/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

```python
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

```python
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`](https://github.com/agno-agi/agno/blob/main/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

```python
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`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/team/team.py) and [`libs/agno/agno/workflow/workflow.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/workflow/workflow.py):

```python
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.

```bash
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`](https://github.com/agno-agi/agno/blob/main/agent/_init.py), [`team/_init.py`](https://github.com/agno-agi/agno/blob/main/team/_init.py), and [`workflow/_init.py`](https://github.com/agno-agi/agno/blob/main/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:

```python
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`](https://github.com/agno-agi/agno/blob/main/workflow/workflow.py), the code executes:

```python
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:

```python
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`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/agent.py), [`workflow.py`](https://github.com/agno-agi/agno/blob/main/workflow.py), and [`team.py`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/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`](https://github.com/agno-agi/agno/blob/main/agent/_telemetry.py).