# openinference-instrumentation-agentspec

**Python · Instrumentation**

OpenInference Open Agent Spec Instrumentation

- **Module**: `openinference.instrumentation.agentspec`
- **Version**: 0.1.23
- **Python**: >=3.10, <3.15
- **Instruments**: `opentelemetry-sdk, pyagentspec >= 26.1.0`

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

## Install

```sh
pip install openinference-instrumentation-agentspec
```

## Usage

Instrument once, at startup, before the library is used. The [`AgentSpecInstrumentor`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.AgentSpecInstrumentor) reference below lists the options.

```python
from opentelemetry.sdk.trace import TracerProvider
from openinference.instrumentation.agentspec import AgentSpecInstrumentor

tracer_provider = TracerProvider()
# ...add a span processor that exports to Phoenix or any OTLP backend.

AgentSpecInstrumentor().instrument(tracer_provider=tracer_provider)
```

## `openinference.instrumentation.agentspec`

### `AgentSpecInstrumentor`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/__init__.py#L19-L85)

```python
class AgentSpecInstrumentor(BaseInstrumentor)
```

An instrumentor for Agent Spec Tracing

#### `instrument`

_method_

```python
def instrument(
    *,
    tracer_provider: Optional[TracerProvider] = None,
    skip_dep_check: bool = False,
) -> None
```

Start tracing `opentelemetry-sdk`, `pyagentspec`: patch it so its calls make OpenInference spans. Calling it again does nothing. Inherited from OpenTelemetry’s [`BaseInstrumentor`](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/base/instrumentor.html).

**Parameters**

| Name | Description |
| - | - |
| `tracer_provider` | The tracer provider the spans are made with. Defaults to the global one, `opentelemetry.trace.get_tracer_provider()`. |
| `skip_dep_check` | Instrument even if the installed version of `opentelemetry-sdk`, `pyagentspec` is outside the supported range. |

#### `uninstrument`

_method_

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

Stop tracing: undo the patches `instrument()` made. Inherited from OpenTelemetry’s [`BaseInstrumentor`](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/base/instrumentor.html).

#### `instrumentation_dependencies`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/__init__.py#L24-L25)

```python
def instrumentation_dependencies() -> Collection[str]
```

#### `instrument_context`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/__init__.py#L77-L85)

```python
def instrument_context(**kwargs: Any = {}) -> Generator[None, Any, None]
```

Context manager to instrument and uninstrument the library

### `OpenInferenceSpanProcessor`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_openinference_spanprocessor.py#L196-L244)

```python
class OpenInferenceSpanProcessor(
    resource: Optional[OtelSdkResource] = None,
    otel_span_processor: Optional[OtelSdkSpanProcessor] = None,
    span_exporter: Optional[OtelSdkSpanExporter] = None,
    use_batch_span_processor: bool = True,
    mask_sensitive_information: bool = True,
)
```

**Attributes**

| Name | Type and value |
| - | - |
| [`span_exporter`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.OpenInferenceSpanProcessor.span_exporter) | `span_exporter` |
| [`resource`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.OpenInferenceSpanProcessor.resource) | `resource` |
| [`span_model_dump_func`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.OpenInferenceSpanProcessor.span_model_dump_func) | `span_model_dump_func` |
| [`span_processor`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.OpenInferenceSpanProcessor.span_processor) | `otel_span_processor` |
| [`use_batch_span_processor`](https://openinf.dev/python/openinference-instrumentation-agentspec.html.md#openinference.instrumentation.agentspec.OpenInferenceSpanProcessor.use_batch_span_processor) | `use_batch_span_processor` |

#### `on_start`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L338-L358)

```python
def on_start(span: AgentSpecSpan) -> None
```

Method called at the start of a Span.

**Parameters** span: The AgentSpec span that is starting

#### `on_end`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L360-L387)

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

Method called at the end of a Span.

**Parameters** span: The AgentSpec span that is ending

#### `on_event`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L389-L391)

```python
def on_event(event: AgentSpecEvent, span: AgentSpecSpan) -> None
```

#### `startup`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L393-L394)

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

#### `shutdown`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L396-L403)

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

#### `on_start_async`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L408-L409)

```python
async def on_start_async(span: AgentSpecSpan) -> None
```

#### `on_end_async`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L411-L412)

```python
async def on_end_async(span: AgentSpecSpan) -> None
```

#### `on_event_async`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L414-L415)

```python
async def on_event_async(
    event: AgentSpecEvent,
    span: AgentSpecSpan,
) -> None
```

#### `startup_async`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L417-L418)

```python
async def startup_async() -> None
```

#### `shutdown_async`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L420-L421)

```python
async def shutdown_async() -> None
```

#### `force_flush`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-agentspec/src/openinference/instrumentation/agentspec/_opentelemetry_spanprocessor.py#L423-L434)

```python
def force_flush(timeout_millis: int = 30000) -> bool
```

Export all ended spans to the configured Exporter that have not yet been exported.

Forwards the call to the internal OpenTelemetry span processor.
