Tracing | Agno

Engineering teams use tracing to diagnose failed runs, slow tools, and unexpected model behavior. Set tracing=True to record AgentOS execution spans in a database.

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

db = SqliteDb(db_file="tmp/agentos.db")

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    agents=[research_agent],
    db=db,
    tracing=True,
)

app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="traced_agent_os:app", reload=True)

The AgentOS database stores the agent's sessions and its traces. View traces in the AgentOS Control Plane or query them through the AgentOS API.

What Tracing Captures

Span	What you can inspect
Agent, team, and workflow runs	Input, output, status, duration, and child operations
Model calls	Model execution within a run
Tool calls	Tool name, execution timing, result, and errors
Team coordination	Calls made while the team delegates or coordinates
Workflow steps	Execution order and duration for each step

AgentOS uses OpenTelemetry instrumentation and stores the resulting traces in an Agno database.

Tracing is process-wide. If a real OpenTelemetry TracerProvider already exists, setup_tracing() returns without installing a new exporter or changing its database. Start these examples in a fresh process, or configure the existing provider deliberately; a later AgentOS instance does not redirect its exporters.

Choose a Trace Database

Runtime setup	Configuration	Trace location
Components share one database	`db=shared_db, tracing=True`	Shared AgentOS database
Components use separate databases	`db=trace_db, tracing=True`	Dedicated AgentOS database
AgentOS has no `db`	`tracing=True`	First component database discovered

Set db explicitly when the runtime contains components with different databases. Component order determines the fallback database when AgentOS has no database of its own.

Use a Dedicated Trace Database

Give each component its application database and pass the trace database to AgentOS:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

agent_db = SqliteDb(db_file="tmp/agent.db", id="agent-db")
trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
    db=agent_db,
)

agent_os = AgentOS(
    agents=[research_agent],
    db=trace_db,
    tracing=True,
)

app = agent_os.get_app()

This layout separates trace data from application data in agent_db. Configure retention and access controls separately for the trace database; the constructor does not create those policies.

Configure the Span Processor

Use setup_tracing() when you need batched writes or explicit queue settings:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tracing import setup_tracing

trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")

setup_tracing(
    db=trace_db,
    batch_processing=True,
    max_queue_size=2048,
    max_export_batch_size=512,
    schedule_delay_millis=3000,
)

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    agents=[research_agent],
    db=trace_db,
)

app = agent_os.get_app()

setup_tracing() configures tracing globally, so call it before creating agents and omit tracing=True from AgentOS. Pass the same database to AgentOS so its API and Control Plane can read the stored traces.

Install Dependencies

The AgentOS extra includes the tracing packages:

uv pip install -U "agno[os]" openai
export OPENAI_API_KEY="your_openai_api_key"

Next Steps

Task	Guide
Understand traces and spans	Tracing concepts
Filter stored traces	Filter Options
Trace an agent	Basic Agent Tracing
Trace a team	Basic Team Tracing
Trace a workflow	Basic Workflow Tracing