Quickstart

Initialize once at startup

import tracely_sdk as tracely
 
tracely.init(
    endpoint="http://localhost:8000",   # your Tracely API
    api_key="tracely_dev_key",          # an ingest key
    service_name="support-agent",
    env="prod",                         # prod | staging | ci | dev  — the gating axis
    instrument="auto",                  # auto-detect openai / anthropic / google / mistral / langchain
)

Your agent’s name is what you declare — service_name names it by default, agent= on init() overrides that for the app, agent= on trace() for one run. It is never guessed from framework attributes: a harness stamps its own gen_ai.agent.name on every sub-agent it spins up, which would fill your workspace with agents you never chose. Name neither and every trace lands under one default agent. One codebase, many customers? Add trace(tenant=customer_id): each tenant becomes its own Agent — endpoint, scenarios, CI gate, failure clusters and regression cases are per-tenant, the traces list shows and filters by it — while agent= stays the per-span label (“supervisor”, “billing”) in the trace’s Agent column.

Call your model — no span code

Your normal OpenAI/Anthropic/… calls are captured automatically. Wrap a run in tracely.trace(...) to attach the agent / conversation / user to every span.

from openai import OpenAI
client = OpenAI()
 
with tracely.trace(agent="support-agent", conversation="conv-1", user="u_42"):
    client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Where is order ORD-4471?"}],
    )

That produces a GENERATION span with model, messages, tokens, latency, tool calls, and cost — with zero span code. See Automatic instrumentation for @observe, streaming, threads, and LiteLLM. Need a span for your own logic? The manual API is at Custom spans.

Flush before the process exits

tracely.flush()   # force-flush the OTLP exporter