Agent Framework Integration Guide¶

Connect your agent frameworks to Tokensor to track costs and detect inefficiencies in real-time.

Tokensor ingests OpenTelemetry traces from your agents, automatically detecting patterns like runaway loops (excessive agent retries), redundant tool calls, and context bloat. Cost appears in the Agents view within about 60 seconds of the first span arriving.

OpenLLMetry / Traceloop¶

If you use OpenLLMetry or Traceloop SDK to export traces, configure the exporter to point to Tokensor's OTel traces endpoint.

Recommended approach — signal-specific env var: Use the signal-specific OTEL_EXPORTER_OTLP_TRACES_ENDPOINT env var (used as-is with no path appended):

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://tokensor.dev/v1/otel/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="X-Tokensor-Key=<your-api-key>"

Also supported — base endpoint (exporter-appended path): Tokensor now also supports the base-endpoint config. If your exporter auto-appends /v1/traces (e.g., standard OTEL SDKs), you can use:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://tokensor.dev/v1/otel
export OTEL_EXPORTER_OTLP_HEADERS="X-Tokensor-Key=<your-api-key>"

Traceloop (built on the OTel Python SDK) respects both standard OTEL_EXPORTER_OTLP_TRACES_* and generic OTEL_EXPORTER_OTLP_* env vars. Traces for chat, text_completion, and generate_content operations automatically map to LLM call records. Data appears in the Agents view within about 60 seconds.

Example (Python):

from traceloop.sdk import Traceloop

Traceloop.init()  # Respects OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / _HEADERS env vars

LangChain OpenTelemetry Export¶

If you use LangChain and want to export traces via the standard OTEL SDK:

Recommended approach — signal-specific env var: Use the signal-specific traces env var (used as-is with no path appended):

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://tokensor.dev/v1/otel/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="X-Tokensor-Key=<your-api-key>"

Also supported — base endpoint (exporter-appended path): Tokensor now also supports the base-endpoint config. If using standard OTEL SDKs that auto-append /v1/traces:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://tokensor.dev/v1/otel
export OTEL_EXPORTER_OTLP_HEADERS="X-Tokensor-Key=<your-api-key>"

Then enable tracing in your LangChain application:

from langchain.callbacks.manager import tracing_v2_enabled

with tracing_v2_enabled(project_name="my-agent"):
    # Your LangChain agent code here
    pass

LangChain emits GenAI semantic convention spans (e.g., gen_ai.operation.name=chat) which Tokensor converts to cost records. Data appears in the Agents view within about 60 seconds.

agentgateway¶

If you run agentgateway, point its OTel trace exporter at Tokensor:

# agentgateway config
tracing:
  otel:
    endpoint: https://tokensor.dev/v1/otel/traces
    headers:
      X-Tokensor-Key: <your-api-key>

Traces from your gateway agents flow into Tokensor automatically. Data appears in the Agents view within about 60 seconds.

Troubleshooting¶

No data appearing? - Verify the X-Tokensor-Key header is present in requests (check exporter logs). - Ensure your agent code is actually invoking LLM calls or tool operations. - Give it up to 90 seconds; dashboard updates poll every 30-60 seconds.

Spans being dropped? - Check that spans include required GenAI semantic convention attributes: gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens. - Spans without these fields are silently skipped (not an error — OTel exporters retry on failure, so noisy errors would break exporters; see API docs for details).

What Gets Tracked¶

Once connected, Tokensor automatically: - Tracks LLM calls — model, input/output tokens, latency, cost. - Attributes LLM calls to agents — via service.name resource attribute (or gen_ai.agent.name span attribute). - Detects inefficiency patterns — runaway loops (many calls in one trace), redundant tool calls, context bloat (growing input without prompt caching). - Shows per-agent cost rollups — hourly/daily/monthly cost breakdown by agent.

See the dashboard Agents view for real-time analytics and findings.