Tracing

Configure tracing for your agents, teams, and workflows in AgentOS

When running agents in production, understanding what’s happening inside your system becomes critical. Agents make autonomous decisions, call external APIs, and coordinate in ways that aren’t visible from logs alone. Tracing gives you the observability you need to debug failures, identify performance bottlenecks, and understand agent behavior.

AgentOS provides built-in tracing support that integrates seamlessly with the AgentOS UI. Enable tracing with a simple flag and instantly gain visibility into every agent run, model call, and tool execution—all viewable directly in your AgentOS dashboard.

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

This guide covers how to configure tracing in AgentOS based on your database setup.

After running your agent/team, you can view the traces in the AgentOS UI.

Prerequisites

Install the required OpenTelemetry packages:

uv pip install -U opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno

Understanding 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)

It is recommended to use a seperate dedicated database for traces. This ensures all traces are stored in one central location, making it 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.hackernews import HackerNewsTools

# 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=[HackerNewsTools()],
    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 will store traces in the first database it finds from your agents or teams. This leads to:

• Fragmented traces: Traces scattered across different databases
• Incomplete observability: Can’t query all traces from one place
• Unpredictable behavior: Which database gets traces depends on agent 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.

Best Practice: Always use a dedicated db in production, even with a single agent. This keeps observability data separate and makes it easier to scale or migrate later.