Tracing

Set tracing=True on AgentOS to record agent, team, workflow, model, and tool spans in a database. View stored traces in the AgentOS UI.

For a comprehensive introduction to Agno Tracing concepts (traces, spans, and what gets captured), see the Tracing Overview.

Prerequisites

Install the required packages:

uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno ddgs
export OPENAI_API_KEY=***

Database Configuration

How you configure tracing depends on your database setup:

Scenario	Configuration	Where Traces Are Stored
Single shared database	`tracing=True`	The shared database
Multiple databases	`tracing=True` + `db=...`	The dedicated `db`
No `db` specified	`tracing=True`	First database found (not recommended)

We recommend a separate, dedicated database for traces. It keeps them all in one place, which makes them easier to query and analyze.

Single Database Setup

If all your agents and teams share the same database instance, enabling tracing is simple:

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

# Single shared database for everything
db = SqliteDb(db_file="tmp/agno.db")

agent = Agent(
    name="Research Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,  # Uses shared db
)

# Enable tracing - traces stored in the shared db
agent_os = AgentOS(
    agents=[agent],
    db=db,
    tracing=True,  # Traces go to the shared db
)

app = agent_os.get_app()

In this setup, traces are automatically stored in the shared database alongside sessions and other data.

Multiple Databases Setup

When agents or teams have different databases, it is highly recommended that you specify a dedicated db to ensure all traces are stored in one central location.

If you have multiple agents with their own databases, traces need a dedicated database:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tools.hackernews import HackerNewsTools
from agno.tools.websearch import WebSearchTools

# Each agent has its own database
agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")

# Dedicated database for traces (separate from agent databases)
db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Agent 1 with its own database
hackernews_agent = Agent(
    name="HackerNews Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    db=agent1_db,
)

# Agent 2 with its own database
search_agent = Agent(
    name="Search Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[WebSearchTools()],
    db=agent2_db,
)

# AgentOS with dedicated tracing database
agent_os = AgentOS(
    agents=[hackernews_agent, search_agent],
    tracing=True,
    db=db,  # All traces go here
)

app = agent_os.get_app()

Why Use a Dedicated Tracing Database?

Without db, AgentOS stores all traces in the first database it finds from your agents, teams, or workflows. The selected database depends on component order. With a dedicated db:

Unified observability: All traces in one queryable location
Cross-agent analysis: Compare performance across agents
Independent scaling: Traces don’t affect agent data storage
Predictable behavior: You control exactly where traces go

Using setup_tracing() with AgentOS

You can also use setup_tracing() for more control over tracing configuration. In this case, you still need to ensure the tracing database is available to AgentOS:

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

# Agent databases
agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")

# Dedicated tracing database
db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Set up tracing with custom configuration
setup_tracing(
    db=db,
    batch_processing=True,
    max_queue_size=2048,
    schedule_delay_millis=3000,
)

# Create agents
agent1 = Agent(name="Agent 1", model=OpenAIResponses(id="gpt-5.2"), db=agent1_db)
agent2 = Agent(name="Agent 2", model=OpenAIResponses(id="gpt-5.2"), db=agent2_db)

# Pass db to AgentOS for trace querying via API
agent_os = AgentOS(
    agents=[agent1, agent2],
    db=db,  # Makes traces queryable via AgentOS API
)

app = agent_os.get_app()

Even when using setup_tracing(), pass db to AgentOS so traces are accessible through the AgentOS API and UI.

Use a dedicated db when traces need separate retention, access, or scaling policies.

Get Started

AgentOS

Example Usage

Prerequisites

Database Configuration

Single Database Setup

Multiple Databases Setup

Why Use a Dedicated Tracing Database?

Using setup_tracing() with AgentOS

​Prerequisites

​Database Configuration

​Single Database Setup

​Multiple Databases Setup

​Why Use a Dedicated Tracing Database?

​Using setup_tracing() with AgentOS

Prerequisites

Database Configuration

Single Database Setup

Multiple Databases Setup

Why Use a Dedicated Tracing Database?

Using setup_tracing() with AgentOS