Python APIstrands-agents

Core

Instrumentation

Python · Instrumentation

openinference-instrumentation-strands-agents

OpenInference span processor for Strands Agents - transforms native OpenTelemetry spans to OpenInference format

Module
openinference.instrumentation.strands_agents
Version
0.1.20
Python
>=3.10, <3.16
Instruments
strands-agents >= 1.19.0

Install

pip install openinference-instrumentation-strands-agents

openinference.instrumentation.strands_agents

OpenInference Instrumentation for Strands Agents.

This package provides a span processor that transforms Strands’ native OpenTelemetry spans (using GenAI semantic conventions) into OpenInference format for compatibility with OpenInference-supported OTEL backends (Phoenix, Arize, etc.).

Usage

from strands.telemetry import StrandsTelemetry
from openinference.instrumentation.strands_agents import StrandsAgentsToOpenInferenceProcessor

# Setup Strands native telemetry
telemetry = StrandsTelemetry()
telemetry.setup_otlp_exporter(endpoint="http://localhost:6006/v1/traces")

# Add OpenInference processor to transform spans
telemetry.tracer_provider.add_span_processor(
    StrandsAgentsToOpenInferenceProcessor(debug=False)
)

# Now use your Strands agents normally - spans will be automatically transformed
from strands import Agent
from strands.models.openai import OpenAIModel

model = OpenAIModel(model_id="gpt-4o-mini")
agent = Agent(name="MyAgent", model=model)
result = agent("Hello!")

The processor handles:

  • Span kind mapping (invoke_agent → AGENT, execute_event_loop_cycle → CHAIN, etc.)
  • Attribute transformation (gen_ai.* → llm., tool., agent.*)
  • Event extraction (gen_ai.user.message → llm.input_messages)
  • Token usage mapping (gen_ai.usage.* → llm.token_count.*)
  • Tool parameter extraction
  • Message structure flattening

For more information, see: https://github.com/Arize-ai/openinference

StrandsAgentsToOpenInferenceProcessor

classSource ↗
class StrandsAgentsToOpenInferenceProcessor(
    debug: bool = False,
    config: Optional[TraceConfig] = None,
)

Also importable from openinference.instrumentation.strands_agents.processor.

SpanProcessor that converts Strands Agents telemetry attributes to OpenInference format for compatibility with OpenInference-compliant backends.

Important: This processor mutates spans in-place. Add it BEFORE any span processors/exporters that should receive the transformed OpenInference spans.

Example

# Correct order: processor first, then exporter
tracer_provider.add_span_processor(StrandsAgentsToOpenInferenceProcessor())
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

Attributes

NameType and value
debugdebug

on_start

methodSource ↗
def on_start(
    span: Span,
    parent_context: Optional[Context] = None,
) -> None

Called when a span is started.

on_end

methodSource ↗
def on_end(span: ReadableSpan) -> None

Called when a span ends. Transform the span attributes from Strands format to OpenInference format.

shutdown

methodSource ↗
def shutdown() -> None

Shutdown the processor. No-op for this processor.

force_flush

methodSource ↗
def force_flush(timeout_millis: Optional[int] = None) -> bool

get_migration_guide

staticmethodSource ↗
def get_migration_guide() -> Dict[str, str]

openinference.instrumentation.strands_agents.semantic_conventions

Strands-specific GenAI semantic convention constants.

This module provides constants from OpenTelemetry’s GenAI semantic conventions, along with additional constants commonly used for mapping GenAI attributes to OpenInference format.

These constants are kept local to the strands instrumentation package to avoid coupling issues with the volatile gen_ai conventions as different 3rd party tools update their OTEL usage at different rates.

GEN_AI_PROVIDER_NAME

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_PROVIDER_NAME.

GEN_AI_REQUEST_MODEL

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_REQUEST_MODEL.

GEN_AI_SYSTEM

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_SYSTEM.

GEN_AI_TOOL_CALL_ID

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_TOOL_CALL_ID.

GEN_AI_TOOL_NAME

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_TOOL_NAME.

GEN_AI_USAGE_INPUT_TOKENS

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_USAGE_INPUT_TOKENS.

GEN_AI_USAGE_OUTPUT_TOKENS

re-export

Re-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_USAGE_OUTPUT_TOKENS.

GEN_AI_REQUEST_MAX_TOKENS

attributeSource ↗
GEN_AI_REQUEST_MAX_TOKENS = 'gen_ai.request.max_tokens'

GEN_AI_REQUEST_TEMPERATURE

attributeSource ↗
GEN_AI_REQUEST_TEMPERATURE = 'gen_ai.request.temperature'

GEN_AI_REQUEST_TOP_P

attributeSource ↗
GEN_AI_REQUEST_TOP_P = 'gen_ai.request.top_p'

GEN_AI_INPUT_MESSAGES

attributeSource ↗
GEN_AI_INPUT_MESSAGES = 'gen_ai.input.messages'

GEN_AI_OUTPUT_MESSAGES

attributeSource ↗
GEN_AI_OUTPUT_MESSAGES = 'gen_ai.output.messages'

GEN_AI_SYSTEM_INSTRUCTIONS

attributeSource ↗
GEN_AI_SYSTEM_INSTRUCTIONS = 'gen_ai.system_instructions'

GEN_AI_TOOL_CALL_ARGUMENTS

attributeSource ↗
GEN_AI_TOOL_CALL_ARGUMENTS = 'gen_ai.tool.call.arguments'

GEN_AI_TOOL_CALL_RESULT

attributeSource ↗
GEN_AI_TOOL_CALL_RESULT = 'gen_ai.tool.call.result'

GEN_AI_USAGE_CACHE_CREATION_TOKENS

attributeSource ↗
GEN_AI_USAGE_CACHE_CREATION_TOKENS = 'gen_ai.usage.cache_creation.input_tokens'

GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS

attributeSource ↗
GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read_input_tokens'

GEN_AI_USAGE_CACHE_READ_TOKENS

attributeSource ↗
GEN_AI_USAGE_CACHE_READ_TOKENS = 'gen_ai.usage.cache_read.input_tokens'

GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS

attributeSource ↗
GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS = 'gen_ai.usage.cache_write_input_tokens'

GenAIAttributes

classSource ↗
class GenAIAttributes

GenAI attribute names used by Strands agents.

Attributes

NameType and value
USAGE_PROMPT_TOKENS'gen_ai.usage.prompt_tokens'
USAGE_COMPLETION_TOKENS'gen_ai.usage.completion_tokens'
USAGE_TOTAL_TOKENS'gen_ai.usage.total_tokens'
AGENT_NAME'gen_ai.agent.name'
AGENT_TOOLS'gen_ai.agent.tools'
TOOL_CALL_ID'gen_ai.tool.call.id'
SYSTEM_PROMPT'system_prompt'
PROMPT'gen_ai.prompt'
COMPLETION'gen_ai.completion'

GenAIEventNames

classSource ↗
class GenAIEventNames

GenAI event names for OTEL events.

Attributes

NameType and value
SYSTEM_MESSAGE'gen_ai.system.message'
USER_MESSAGE'gen_ai.user.message'
ASSISTANT_MESSAGE'gen_ai.assistant.message'
TOOL_MESSAGE'gen_ai.tool.message'
CHOICE'gen_ai.choice'

safe_json_dumps

functionSource ↗
def safe_json_dumps(obj: Any, **kwargs: Any = {}) -> str

A convenience wrapper around json.dumps that ensures that any object can be safely encoded without a TypeError and that non-ASCII Unicode characters are not escaped.