OpenTelemetry (OTel)

Agnost AI runs a hosted OTLP collector at otel.agnost.ai. Any framework that emits OpenTelemetry spans can ship them straight to Agnost AI: no SDK required.

Your AI App  →  otel.agnost.ai  →  Agnost AI Dashboard

Quick Setup

Set two environment variables before starting your app:

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.agnost.ai
OTEL_EXPORTER_OTLP_HEADERS="X-Agnost-Org-ID=<your-org-id>"

Get your org ID from app.agnost.ai. For SDKs that take an explicit URL, use https://otel.agnost.ai/v1/traces.

Framework Guides

Custom Tool Spans

If your stack doesn’t have a framework integration, wrap each agent / tool call in an OTel span. Name the span with a tool. prefix so Agnost AI classifies it as a tool call.

1. Install

Already have an OTel SDK and the OTLP exporter installed? Skip. No OTel yet?

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/api

2. Wire the OTLP exporter pointing at Agnost AI

Already have an OTel TracerProvider? Append Agnost AI as an additional span processor:

from opentelemetry import trace
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://otel.agnost.ai/v1/traces",
            headers={"X-Agnost-Org-ID": os.environ["AGNOST_ORG_ID"]},
        )
    )
)

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

provider.addSpanProcessor(
  new BatchSpanProcessor(
    new OTLPTraceExporter({
      url: 'https://otel.agnost.ai/v1/traces',
      headers: { 'X-Agnost-Org-ID': process.env.AGNOST_ORG_ID! },
    }),
  ),
);

No OTel yet? Full setup:

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource

provider = TracerProvider(resource=Resource.create({"service.name": "my-app"}))
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://otel.agnost.ai/v1/traces",
            headers={"X-Agnost-Org-ID": os.environ["AGNOST_ORG_ID"]},
        )
    )
)
trace.set_tracer_provider(provider)

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://otel.agnost.ai/v1/traces',
    headers: { 'X-Agnost-Org-ID': process.env.AGNOST_ORG_ID! },
  }),
}).start();

3. Wrap each tool call in a span with userId / sessionId

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("tool.search_web") as span:
    span.set_attribute("agnost.user_id", "user-42")
    span.set_attribute("agnost.session_id", "conv-abc123")
    span.set_attribute("input", query)
    try:
        result = search_web(query)
        span.set_attribute("output", str(result))
    except Exception as exc:
        span.record_exception(exc)
        raise

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app');

const span = tracer.startSpan('tool.search_web');
span.setAttribute('agnost.user_id', 'user-42');
span.setAttribute('agnost.session_id', 'conv-abc123');
span.setAttribute('input', query);
try {
  const result = await searchWeb(query);
  span.setAttribute('output', JSON.stringify(result));
} catch (err) {
  span.setStatus({ code: SpanStatusCode.ERROR });
  throw err;
} finally {
  span.end();
}

Additional properties

Agnost AI recognizes these OTel fields and preserves non-reserved custom span attributes as event metadata:

Type	Fields
Parent span	`parentSpanId` on the child span
GenAI convention attributes	`gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`
Custom metadata	`customer.tier`, `feature.name`, or another non-reserved OTel attribute

Note: If you don’t set agnost.session_id or another supported session attribute, Agnost AI uses the trace ID as the session ID. Each trace therefore appears as a separate session. Reuse a stable session ID to group multiple traces into one conversation.

Send a trace with curl

This sends one completion span with its input/output and GenAI attributes, plus a child tool.get_weather span with its own input/output:

curl https://otel.agnost.ai/v1/traces \
  -X POST \
  -H "X-Agnost-Org-ID: $AGNOST_ORG_ID" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "resourceSpans": [{
      "resource": {
        "attributes": [{
          "key": "service.name",
          "value": { "stringValue": "support-agent" }
        }]
      },
      "scopeSpans": [{
        "scope": { "name": "custom-otel-example" },
        "spans": [{
          "traceId": "0102030405060708090a0b0c0d0e0f10",
          "spanId": "0102030405060708",
          "name": "chat.completion",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000002000000000",
          "attributes": [{
            "key": "agnost.user_id",
            "value": { "stringValue": "user-42" }
          }, {
            "key": "agnost.session_id",
            "value": { "stringValue": "conversation-abc123" }
          }, {
            "key": "input",
            "value": { "stringValue": "What is the weather in San Francisco?" }
          }, {
            "key": "output",
            "value": { "stringValue": "It is 72°F and sunny." }
          }, {
            "key": "gen_ai.request.model",
            "value": { "stringValue": "gpt-5" }
          }, {
            "key": "gen_ai.response.model",
            "value": { "stringValue": "gpt-5-2025-08-07" }
          }, {
            "key": "gen_ai.usage.input_tokens",
            "value": { "intValue": "120" }
          }, {
            "key": "gen_ai.usage.output_tokens",
            "value": { "intValue": "48" }
          }, {
            "key": "customer.tier",
            "value": { "stringValue": "enterprise" }
          }]
        }, {
          "traceId": "0102030405060708090a0b0c0d0e0f10",
          "spanId": "1112131415161718",
          "parentSpanId": "0102030405060708",
          "name": "tool.get_weather",
          "startTimeUnixNano": "1700000000200000000",
          "endTimeUnixNano": "1700000001800000000",
          "attributes": [{
            "key": "agnost.session_id",
            "value": { "stringValue": "conversation-abc123" }
          }, {
            "key": "input",
            "value": { "stringValue": "San Francisco" }
          }, {
            "key": "output",
            "value": { "stringValue": "72°F and sunny" }
          }, {
            "key": "feature.name",
            "value": { "stringValue": "weather" }
          }]
        }]
      }]
    }]
  }'

A successful export returns HTTP 200.

What appears in Agnost AI

Events: every received span/event.
Conversations: spans grouped by agnost.session_id, session.id, or framework-specific session metadata.
Tool calls: spans named with tool.* or framework tool-call attributes.
Errors: spans marked failed or exceptions recorded on spans.

Verify

Start your app with the OTel exporter configured.
Run one agent turn or tool call.
Open app.agnost.ai.
Check Events first, then Conversations or Tool calls.

Troubleshooting

No data: confirm the endpoint is https://otel.agnost.ai/v1/traces when your SDK expects a trace URL.
Wrong org: confirm X-Agnost-Org-ID is attached to the OTLP exporter.
No input/output text: your framework may not export message content by default, or you may have disabled it.

Next steps

Events: verify the spans Agnost AI received.
Tool calls: inspect tool reliability and latency.
Intents: organize production conversations by what users wanted.

Getting started

Agent frameworks

Voice agents

Custom applications

MCP server analytics

Platforms

OpenTelemetry (OTel)

Quick Setup

Framework Guides

Custom Tool Spans

1. Install

2. Wire the OTLP exporter pointing at Agnost AI

3. Wrap each tool call in a span with userId / sessionId

Additional properties

Send a trace with curl

What appears in Agnost AI

Verify

Troubleshooting

Next steps

​Quick Setup

​Framework Guides

​Custom Tool Spans

​1. Install

​2. Wire the OTLP exporter pointing at Agnost AI

​3. Wrap each tool call in a span with userId / sessionId

​Additional properties

​Send a trace with curl

​What appears in Agnost AI

​Verify

​Troubleshooting

​Next steps

Quick Setup

Framework Guides

Custom Tool Spans

1. Install

2. Wire the OTLP exporter pointing at Agnost AI

3. Wrap each tool call in a span with userId / sessionId

Additional properties

Send a trace with curl

What appears in Agnost AI

Verify

Troubleshooting

Next steps