Tracing

Store AgentOS traces to inspect run behavior, latency, errors, model calls, and tool calls.

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.

traced_agent_os.py

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.

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 gives traces their own retention and access policy while the agent keeps its application data in agent_db.

Configure the Span Processor

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

custom_tracing.py

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

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