Snippets

Copyable tracing patterns for providers, frameworks, agents, tool loops, structured outputs, prompt caching, handoffs, and custom subprocess work.

These examples are copy-paste ready. Each one shows what gets captured and links to the integration page that covers the surface in depth.

For setup and configuration, start with the Traces Quickstart. For an end-to-end view of a real production agent, see the Production Agent Example.

OpenAI Chat Completion

Initialize tracing before constructing the OpenAI client. The SDK patches Chat Completions and emits an LLM span with input messages, output messages, model name, invocation parameters, finish reason, and token counts.

See OpenAI traces for tool calls, structured outputs, and the Responses API.

OpenAI Tool Round Trip

Tool calls are captured on the model span. The first turn records the assistant tool call and arguments; the second turn records the tool result in the input message list.

This captures the model-side view of tool calling: what the LLM asked for and the result you passed back. For a caller-side view that wraps the actual function execution in its own TOOL span, see Manual spans.

OpenAI Structured Output

Structured-output requests keep the schema in llm.invocation_parameters and the model response in output.value.

OpenAI Responses API

The Responses API is traced separately from Chat Completions. Function-call items are normalized into the same OpenInference tool-call attributes used by Chat Completions, so the dashboard renders them the same way.

Anthropic Messages

Anthropic Messages calls emit LLM spans with user and assistant content blocks, model name, invocation parameters, finish reason, and usage.

Anthropic Prompt Caching

When Anthropic returns prompt-cache usage fields, Inference platform maps them to OpenInference token detail attributes so they show up alongside the regular token counts on the LLM span.

The cache attributes show up on the LLM span as llm.token_count.prompt_details.cache_write and llm.token_count.prompt_details.cache_read. See the Attributes reference for the full set of token-detail keys.

Manual Parent Around Automatic Children

Use an outer agent span around orchestration code when you want nested LLM, tool, or framework spans grouped under one product-level operation. Spans created inside the callback auto-parent under the agent span via OTel context propagation.

OpenAI Agents With Outer Span

Pair OpenAI Agents with OpenAI instrumentation. Use agentSpan() / agent_span() for an explicit outer span; nested OpenAI calls are captured automatically and parent under it.

OpenAI Agents Handoff

Handoffs create a useful trace tree when wrapped in an outer agent span: the triage agent, specialist agent, model calls, and tools are all grouped under one customer request.

TypeScript

import { agentSpan, setup } from "@inference/tracing";
import * as agents from "@openai/agents";
import { Agent, handoff, run, tool } from "@openai/agents";
import OpenAI from "openai";
import { z } from "zod";

const tracing = await setup({
  modules: { openai: OpenAI, openaiAgents: agents },
});

const issueRefund = tool({
  name: "issue_refund",
  description: "Issue a refund for an order.",
  parameters: z.object({ orderId: z.string(), amount: z.number() }),
  execute: async ({ orderId, amount }) =>
    JSON.stringify({ ok: true, orderId, refundId: "RFD-2201", amount }),
});

const refundsAgent = new Agent({
  name: "RefundsAgent",
  instructions: "Handle refund requests and use issue_refund.",
  tools: [issueRefund],
  model: "gpt-4o-mini",
});
const billingAgent = new Agent({
  name: "BillingAgent",
  instructions: "Answer billing questions. Do not issue refunds.",
  model: "gpt-4o-mini",
});
const triageAgent = new Agent({
  name: "TriageAgent",
  instructions: "Route refund requests to RefundsAgent.",
  handoffs: [handoff(refundsAgent), handoff(billingAgent)],
  model: "gpt-4o-mini",
});

await agentSpan(
  {
    agentId: "triage-agent-prod",
    agentName: "Triage Agent",
    spanName: "triage-agent.run",
    sessionId: "conversation-refund-abc-123",
    system: "openai",
  },
  async (span) => {
    const input = "I need a refund for order ABC-123, total $42.50.";
    span.setInput(input);
    const result = await run(triageAgent, input, { maxTurns: 8 });
    span.setOutput(String(result.finalOutput ?? ""));
  },
);

await tracing.shutdown();

Pi Agent With Outer Span

Current Pi Agent applications use an explicit Models collection. Pass that collection to setup() before you register providers. The model spans then nest under the outer agent span.

TypeScript

import { Agent } from "@earendil-works/pi-agent-core";
import { createModels } from "@earendil-works/pi-ai";
import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
import { agentSpan, setup } from "@inference/tracing";

const models = createModels();
const tracing = await setup({
  serviceName: "pi-agent",
  autoInstrument: false,
  modules: { piAgent: models },
});
models.setProvider(anthropicProvider());

const model = models.getModel("anthropic", "claude-sonnet-4-6");
if (!model) throw new Error("Pi model not found");

const agent = new Agent({
  initialState: { systemPrompt: "Answer concisely.", model },
  streamFn: models.streamSimple.bind(models),
});

await agentSpan(
  {
    agentId: "pi-support-agent",
    agentName: "Pi Support Agent",
    spanName: "pi-support-agent.run",
    sessionId: "conversation-abc-123",
    system: "pi-agent",
  },
  async (span) => {
    const input = "Summarize order ABC-123.";
    span.setInput(input);
    await agent.prompt(input);
    span.setOutput(agent.state.messages.at(-1));
  },
);

await tracing.shutdown();

See Pi Agent traces for tool execution and manual setup.

LangChain Agent With Tools

LangChain instrumentation hooks the callback manager. You do not need to wrap each tool or model call manually; chain, LLM, and tool spans are emitted from the framework callbacks.

If the same agent is already wrapped with LangSmith @traceable, keep that decorator in place and install the langsmith extra. Inference platform uses the LangSmith OTel span as the active parent, so the LangChain and provider spans stay grouped under the decorated run.

Pydantic AI Structured Agent (Python)

Pydantic AI ships native OpenTelemetry instrumentation. Inference platform registers its provider and enables Pydantic AI instrumentation during setup().

Python

from inference_tracing import setup
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

class CityWeather(BaseModel):
    city: str
    temp_c: float = Field(description="Temperature in Celsius.")
    condition: str

class WeatherReport(BaseModel):
    cities: list[CityWeather]
    summary: str

tracing = setup()

agent = Agent(
    "openai:gpt-4o-mini",
    output_type=WeatherReport,
    system_prompt="Use get_weather for every requested city.",
)

@agent.tool
def get_weather(_ctx: RunContext[None], city: str) -> str:
    """Look up current weather for a city."""
    return f'{{"city": "{city}", "temp_c": 12, "condition": "overcast"}}'

result = agent.run_sync("What's the weather in Paris and Tokyo?")
print(result.output.summary)
tracing.shutdown()

Claude Agent SDK

Python can patch the SDK during setup() before query is imported. TypeScript uses an explicit wrapper because ESM namespace bindings cannot be safely patched.

CLI Or Subprocess Work

When a tool has no instrumentable SDK, wrap the subprocess call in an agent span and set the input, output, and token usage when available.