# openinference-instrumentation-strands-agents

**Python · Instrumentation**

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

- **Module**: `openinference.instrumentation.strands_agents`
- **Version**: 0.1.21
- **Python**: >=3.10, <3.16
- **Instruments**: `strands-agents >= 1.19.0`

[PyPI](https://pypi.org/project/openinference-instrumentation-strands-agents/) · [README](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/README.md) · [Source](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-strands-agents)

## Install

```sh
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**

```python
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`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L99-L1242)

```python
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**

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

**Attributes**

| Name | Type and value |
| - | - |
| [`debug`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.StrandsAgentsToOpenInferenceProcessor.debug) | `debug` |

#### `on_start`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L126-L128)

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

Called when a span is started.

#### `on_end`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L130-L175)

```python
def on_end(span: ReadableSpan) -> None
```

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

#### `shutdown`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L1215-L1217)

```python
def shutdown() -> None
```

Shutdown the processor. No-op for this processor.

#### `force_flush`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L1219-L1220)

```python
def force_flush(timeout_millis: Optional[int] = None) -> bool
```

#### `get_migration_guide`

_staticmethod_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L1222-L1242)

```python
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`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L55)

```python
GEN_AI_REQUEST_MAX_TOKENS = 'gen_ai.request.max_tokens'
```

### `GEN_AI_REQUEST_TEMPERATURE`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L56)

```python
GEN_AI_REQUEST_TEMPERATURE = 'gen_ai.request.temperature'
```

### `GEN_AI_REQUEST_TOP_P`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L57)

```python
GEN_AI_REQUEST_TOP_P = 'gen_ai.request.top_p'
```

### `GEN_AI_INPUT_MESSAGES`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L59)

```python
GEN_AI_INPUT_MESSAGES = 'gen_ai.input.messages'
```

### `GEN_AI_OUTPUT_MESSAGES`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L60)

```python
GEN_AI_OUTPUT_MESSAGES = 'gen_ai.output.messages'
```

### `GEN_AI_SYSTEM_INSTRUCTIONS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L58)

```python
GEN_AI_SYSTEM_INSTRUCTIONS = 'gen_ai.system_instructions'
```

### `GEN_AI_TOOL_CALL_ARGUMENTS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L61)

```python
GEN_AI_TOOL_CALL_ARGUMENTS = 'gen_ai.tool.call.arguments'
```

### `GEN_AI_TOOL_CALL_RESULT`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L62)

```python
GEN_AI_TOOL_CALL_RESULT = 'gen_ai.tool.call.result'
```

### `GEN_AI_USAGE_CACHE_CREATION_TOKENS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L66)

```python
GEN_AI_USAGE_CACHE_CREATION_TOKENS = 'gen_ai.usage.cache_creation.input_tokens'
```

### `GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L68)

```python
GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read_input_tokens'
```

### `GEN_AI_USAGE_CACHE_READ_TOKENS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L65)

```python
GEN_AI_USAGE_CACHE_READ_TOKENS = 'gen_ai.usage.cache_read.input_tokens'
```

### `GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS`

_attribute_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L69)

```python
GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS = 'gen_ai.usage.cache_write_input_tokens'
```

### `GenAIAttributes`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L72-L91)

```python
class GenAIAttributes
```

GenAI attribute names used by Strands agents.

**Attributes**

| Name | Type and value |
| - | - |
| [`USAGE_PROMPT_TOKENS`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.USAGE_PROMPT_TOKENS) | `'gen_ai.usage.prompt_tokens'` |
| [`USAGE_COMPLETION_TOKENS`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.USAGE_COMPLETION_TOKENS) | `'gen_ai.usage.completion_tokens'` |
| [`USAGE_TOTAL_TOKENS`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.USAGE_TOTAL_TOKENS) | `'gen_ai.usage.total_tokens'` |
| [`AGENT_NAME`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.AGENT_NAME) | `'gen_ai.agent.name'` |
| [`AGENT_TOOLS`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.AGENT_TOOLS) | `'gen_ai.agent.tools'` |
| [`TOOL_CALL_ID`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.TOOL_CALL_ID) | `'gen_ai.tool.call.id'` |
| [`SYSTEM_PROMPT`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.SYSTEM_PROMPT) | `'system_prompt'` |
| [`PROMPT`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.PROMPT) | `'gen_ai.prompt'` |
| [`COMPLETION`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIAttributes.COMPLETION) | `'gen_ai.completion'` |

### `GenAIEventNames`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L94-L101)

```python
class GenAIEventNames
```

GenAI event names for OTEL events.

**Attributes**

| Name | Type and value |
| - | - |
| [`SYSTEM_MESSAGE`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIEventNames.SYSTEM_MESSAGE) | `'gen_ai.system.message'` |
| [`USER_MESSAGE`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIEventNames.USER_MESSAGE) | `'gen_ai.user.message'` |
| [`ASSISTANT_MESSAGE`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIEventNames.ASSISTANT_MESSAGE) | `'gen_ai.assistant.message'` |
| [`TOOL_MESSAGE`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIEventNames.TOOL_MESSAGE) | `'gen_ai.tool.message'` |
| [`CHOICE`](https://openinf.dev/python/openinference-instrumentation-strands-agents.html.md#openinference.instrumentation.strands_agents.semantic_conventions.GenAIEventNames.CHOICE) | `'gen_ai.choice'` |

### `safe_json_dumps`

_function_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/semantic_conventions.py#L104-L110)

```python
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.
