OpenInference Documentation

OpenInference is a semantic convention specification for AI application observability, built on top of OpenTelemetry. It standardizes how AI-specific workloads—such as LLM calls, agent reasoning, tool invocations, and retrieval operations—are represented as distributed traces.

Because OpenTelemetry's default attribute model is generic, OpenInference provides a concrete schema and span-kind taxonomy to handle AI-specific requirements like:

• Structured inputs/outputs: Handling multi-turn messages and multimodal content.
• Token economics: Tracking prompt, completion, and reasoning token counts.
• Agentic control flow: Providing consistent identity for reasoning loops and tool calls.
• Privacy: Enabling granular masking of sensitive prompt/completion fields.
• Quality feedback: Associating scores and labels from human or LLM judges with specific operations.

The @arizeai/openinference-core package is organized into several functional modules that provide tracing capabilities, helpers, and type definitions:

• src/index.ts: The main entry point that re-exports the public API.
• src/helpers/: Contains utility functions for tracing, including:
  • withSpan.ts: Implementation of the withSpan pattern.
  • wrappers.ts: High-level wrappers like traceChain, traceAgent, and traceTool.
  • decorators.ts: The @observe decorator for easy instrumentation.
  • attributeHelpers.ts: Functions to extract attributes like getLLMAttributes and getEmbeddingAttributes.
  • tracerHelpers.ts: Utilities for managing tracers via getTracer and wrapTracer.
  • types.ts: Core types such as SpanTraceOptions, SpanInput/Output, Message, and TokenCount.
• src/trace/: Contains the core tracing logic:
  • contextAttributes.ts: Functions to set context like setSession, setUser, and setMetadata.
  • types.ts: Definitions for Session, User, Metadata, PromptTemplate, and Tags.
  • trace-config/: Configuration management, including OITracer, OISpan (a masking-aware wrapper), and maskingRules.
• src/utils/: General purpose utilities for safety and type checking.

This package provides auto-instrumentation for two main patterns in the Claude Agent SDK:

query()

Each call is wrapped in a single AGENT span named ClaudeAgentSDK.query. It captures:

• Input: Prompt text or JSON.
• Output: Result text/JSON from the SDK result message.
• Metadata: session.id, llm.model_name, token counts, and llm.cost.total (when available).
• Tools: Tool calls are captured as child TOOL spans via SDK hooks.

ClaudeSDKClient

Used for continuous/multi-turn conversations. Each iteration of receive_response() (or receive_messages()) is wrapped in an AGENT span named ClaudeAgentSDK.ClaudeSDKClient.receive_response with the same input/output/metadata/tool spans as query().

Note: To capture detailed LLM and tool spans inside the agent runs (the underlying Anthropic API calls), you must also install and use openinference-instrumentation-anthropic.

When implementing stateless (ZDR) multi-turn conversations involving tool use, you must echo the canonical sequence of items in the input[] array. The correct order is:

1. reasoning item (leads the turn)
2. function_call item
3. function_call_output item

Warning: Do not drop the leading reasoning item when rebuilding the next turn from tool outputs. The server will reject requests that omit the reasoning items that preceded the tool calls. On parallel tool calls, you must echo the reasoning items for every branch.

{
  "model": "gpt-5",
  "store": false,
  "include": ["reasoning.encrypted_content"],
  "reasoning": { "effort": "medium" },
  "input": [
    { "role": "user", "content": "What's the weather in Paris?" },
    {
      "type": "reasoning",
      "id": "rs_1",
      "summary": [{ "type": "summary_text", "text": "Need to call get_weather for Paris." }],
      "encrypted_content": "gAAAAA...=="
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "call_id": "call_1",
      "name": "get_weather",
      "arguments": "{\"city\":\"Paris\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_1",
      "output": "{\"temp_c\":12,\"conditions\":\"cloudy\"}"
    }
  ],
  "tools": [{ "type": "function", "name": "get_weather", "parameters": { /* ... */ } }]
}

The OpenAIAgentsInstrumentor().instrument(...) method automatically traces agents.realtime.RealtimeSession (the OpenAI Agents SDK's voice/audio runtime) if the realtime extras are installed. No additional configuration is required; the instrumentor applies patches whenever agents.realtime is importable.

For each turn, the instrumentor produces a span tree structured as follows:

• conversation.turn (Parent): Contains aggregated input/output transcripts, llm.model_name, and llm.invocation_parameters.
  • user (Child): Contains input.audio.url (WAV data URI), input.audio.transcript, or input.value for text.
  • assistant (Child): Contains output.audio.url, output.audio.transcript, token counts, and time_to_first_token_ms.
    • <tool_name> (Grandchild): One span per function call within the turn.
  • Additional user or assistant siblings may exist for split inputs or tool round-trips.