In Traccia, an agent is an autonomous AI system that uses LLMs to make decisions and take actions. Traccia treats agents as first-class citizens, providing specialized instrumentation and monitoring for AI workloads.

Agent Identity and Metadata

Traccia enriches traces with hierarchical metadata that identifies agents, sessions, users, and organizational context. This metadata flows through all spans and enables fine-grained cost attribution and filtering in the Traccia Platform.

agent.id

Unique identifier for the agent (e.g., "research-assistant", "customer-support-bot")

session.id

Session identifier for grouping related interactions (e.g., a conversation thread)

user.id

End-user identifier for per-user cost tracking and debugging

tenant.id

Organization/tenant identifier for multi-tenant applications

project.id

Project identifier for organizing agents within a tenant

Setting Agent Metadata

agent.py

python

from traccia import init

# Set at initialization (applies to all traces)
init(
    agent_id="research-assistant",
    session_id="conv-12345",
    user_id="user-67890",
    tenant_id="acme-corp",
    project_id="customer-insights"
)

# Or set dynamically using runtime config
from traccia import runtime_config

runtime_config.set_agent_id("summarization-agent")
runtime_config.set_session_id("session-abc123")
runtime_config.set_user_id("user-xyz789")

Hierarchical metadata

These identifiers form a hierarchy: Tenant → Project → Agent → Session → User. The Traccia Platform uses this to provide cost attribution, access control, and filtering at every level.

Multi-Agent Systems

Traccia excels at tracing multi-agent systems where multiple agents collaborate on a task. Each agent can have its own agent.id, while sharing the same session.id to show they're part of the same workflow.

Trace: Customer Support Workflow

Agent: triage-agent(session: sup-001)

LLM: Classify inquiry → 'billing'

Route to billing-agent

Agent: billing-agent(session: sup-001)

Tool: Lookup account

LLM: Generate response

Route to approval-agent

Agent: approval-agent(session: sup-001)

LLM: Review and approve

multi_agent.py

python

from traccia import observe, runtime_config

# Orchestrator agent
@observe()
def orchestrator(query: str):
    runtime_config.set_agent_id("orchestrator")
    runtime_config.set_session_id("workflow-123")
    
    # Route to specialized agents
    if "billing" in query.lower():
        return billing_agent(query)
    elif "technical" in query.lower():
        return technical_agent(query)

# Specialized agents keep the same session ID
@observe()
def billing_agent(query: str):
    runtime_config.set_agent_id("billing-agent")
    # session_id remains "workflow-123"
    return process_billing_query(query)

@observe()
def technical_agent(query: str):
    runtime_config.set_agent_id("technical-agent")
    # session_id remains "workflow-123"
    return process_technical_query(query)

Agent-Level Cost Attribution

Traccia automatically calculates costs for LLM calls and attributes them to the appropriate agent, session, user, or tenant. This enables:

Per-Agent Budgets

Track costs for each agent independently

Per-User Billing

Bill customers based on their actual usage

Cost Optimization

Identify expensive agents or sessions

Multi-Tenant Fair Share

Allocate costs across organizations

Automatic cost calculation

Traccia includes a cost processor that automatically calculates costs based on token usage and model pricing. You can customize pricing tables via environment variables or config.

Agent-Specific Policies (Platform)

The Traccia Platform allows you to set policies and guardrails at the agent level:

Cost Limits

Alert if agent spends > $100/day

Latency SLOs

Alert if p95 latency > 3 seconds

Error Rate Thresholds

Alert if error rate > 5%

Retry Limits

Block agent after 10 consecutive failures

Agent Development Lifecycle

Develop & Instrument

Add @observe() decorators and set agent metadata

Test Locally

Export traces to console or local Jaeger for debugging

Monitor in Production

Export to Traccia Platform or your OTLP backend for production monitoring

Apply Policies

Set up cost limits, error thresholds, and latency SLOs

Optimize & Iterate

Use cost and performance insights to improve your agents

Why Agent-First Observability?

Traditional observability tools focus on services and endpoints. Traccia is built specifically for AI agents, with these key differences:

Traditional APM

• Service-centric
• HTTP request/response
• Database queries
• Infrastructure metrics

Traccia

• Agent-centric
• LLM calls & token usage
• Tool invocations
• Cost attribution & optimization

Next Steps

Instrument Your Agent

Learn how to use @observe() decorator

Multi-Agent Tracing Guide

Trace multiple agents working together

Cost Attribution

Track and optimize agent costs

Agents