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).