Skip to content
Browse the documentation
Reference

OpenTelemetry convention

The span attributes that turn an agent runtime's OpenTelemetry traces into outcome claims and runtime-context facts, with the OTLP endpoint to send them to.

Last changed Markdown versionllms.txt

Send OTLP/HTTP JSON traces to your tenant's keyed endpoint:

POST {API_URL}/v1/otel/{endpoint_key}/v1/traces
Content-Type: application/json

Any span that carries the outcome attributes becomes a claim with vendor = internal. Any span with action attributes becomes a fact. All other attributes are dropped at ingestion; message bodies are never accepted.

Span attributes

Attribute Required Meaning
agent.outcome.type yes (claim) Outcome type: resolution, procedure_handoff, lead_qualified, meeting_booked, refund_processed, record_processed, or a custom type mapped in the source's mapping
agent.outcome.subject_id yes (claim) The system-of-record id the outcome is about (ticket id, case id, order id). Must match the subject id used by your fact sources (e.g. zendesk_ticket_123) or be linkable through identity resolution
agent.outcome.claimed_at no ISO-8601 timestamp; defaults to the span end time
agent.outcome.unit_price no Internal transfer price for definition-delta reporting
agent.name no Agent identifier, kept as a claim attribute
agent.channel no chat, email, voice, … (used by channel_in exclusions)
agent.action.type yes (fact) status_change, escalate, handoff, reply, or a custom action
agent.action.subject_id yes (fact) Subject the action was taken on
agent.action.from / agent.action.to no Status transition for status_change

Minimal example (no SDK)

curl -X POST "$API_URL/v1/otel/$ENDPOINT_KEY/v1/traces" -H 'Content-Type: application/json' -d '{
  "resourceSpans": [{"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "billing-agent"}}]},
    "scopeSpans": [{"spans": [{
      "traceId": "5b8aa5a2d2c872e8321cf37308d69df2", "spanId": "051581bf3cb55c13", "name": "resolve_ticket",
      "startTimeUnixNano": "1756742400000000000", "endTimeUnixNano": "1756742460000000000",
      "attributes": [
        {"key": "agent.outcome.type", "value": {"stringValue": "resolution"}},
        {"key": "agent.outcome.subject_id", "value": {"stringValue": "zendesk_ticket_48213"}},
        {"key": "agent.name", "value": {"stringValue": "billing-agent"}}
      ]}]}]}]}'

Claims created this way flow through the same contract engine and statements as vendor claims, under the internal_agent_otel contract (or the contract mapped per outcome type in the source mapping).