Trace Strands Agents with OpenTelemetry

Replace openai with your model provider’s extra (anthropic, litellm; Bedrock needs none).

pip install 'strands-agents[otel,openai]>=1.57'

uv add 'strands-agents[otel,openai]>=1.57'

Install the SDK with its OpenTelemetry packages:

npm install @strands-agents/sdk @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-http

pnpm add @strands-agents/sdk @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-http

bun add @strands-agents/sdk @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-http

Then start the tracer once, before your first agent runs:

# telemetry.py: import this from your entry point before creating any Agent
from strands.telemetry import StrandsTelemetry

telemetry = StrandsTelemetry().setup_otlp_exporter()

If your app already sets up a global TracerProvider (for example opentelemetry-instrument or the ADOT distro on AgentCore), skip StrandsTelemetry() and add a BatchSpanProcessor(OTLPSpanExporter(...)) pointing at Maple to that provider.

Use the same OTEL_EXPORTER_OTLP_* variables, with OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental,gen_ai_span_attributes_only" (the SDK doesn’t support the third value). Then:

import { Agent, FileStorage, SessionManager } from "@strands-agents/sdk"
import { OpenAIModel } from "@strands-agents/sdk/models/openai"
import { setupTracer } from "@strands-agents/sdk/telemetry"

const provider = setupTracer({ exporters: { otlp: true } }) // reads OTEL_EXPORTER_OTLP_* env vars

Pass the conversation id in trace_attributes:

from strands import Agent
from strands.models.openai import OpenAIModel
from strands.session.file_session_manager import FileSessionManager

model = OpenAIModel(model_id="gpt-4o-mini", params={"max_tokens": 600})


def handle_message(conversation_id: str, text: str) -> str:
    agent = Agent(
        name="support_agent",
        model=model,
        tools=[get_weather, calculate],
        system_prompt="You are a concise support assistant.",
        session_manager=FileSessionManager(session_id=conversation_id, storage_dir="./sessions"),
        trace_attributes={"session.id": conversation_id},
        callback_handler=None,
    )
    return str(agent(text))

The session manager restores history but doesn’t put its session_id on the spans, so you need both arguments. Use the conversation id your app already has, never a fresh UUID per request.

Create the agent per request, as above. A shared module-level Agent would carry one user’s id into everyone’s traces. Give every agent a name, or sub-agents merge into one lane.

With agent.as_tool() sub-agents, only the orchestrator needs session.id. For a Swarm, pass trace_attributes={"session.id": conversation_id} to the Swarm. For a Graph, set graph.trace_attributes = {"session.id": conversation_id} after builder.build().

const model = new OpenAIModel({ modelId: "gpt-4o-mini", params: { max_tokens: 600 } })

async function handleMessage(conversationId: string, text: string): Promise<string> {
	const agent = new Agent({
		name: "support_agent",
		model,
		tools: [getWeather],
		systemPrompt: "You are a concise support assistant.",
		traceAttributes: { "session.id": conversationId },
		sessionManager: new SessionManager({
			sessionId: conversationId,
			storage: { snapshot: new FileStorage("./sessions") },
		}),
		printer: false,
	})
	return String(await agent.invoke(text))
}

Create the agent per request here too.

from telemetry import telemetry

try:
    handle_message(conversation_id, "What's the weather in Berlin?")
finally:
    telemetry.tracer_provider.force_flush()
    telemetry.tracer_provider.shutdown()

On AWS Lambda, call telemetry.tracer_provider.force_flush() at the end of each invocation and don’t call shutdown().

try {
	await handleMessage(conversationId, "What's the weather in Berlin?")
} finally {
	await provider.forceFlush()
	await provider.shutdown()
}