> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# AgentOps (tracing)

> Export AgentOps Python decorator spans through Respan with AgentOps-native operation details.

[AgentOps](https://github.com/AgentOps-AI/agentops) provides OpenTelemetry-backed decorators for tracing agent applications. Respan uses the spans AgentOps already creates, translates its native kinds and content into the Respan span contract, and exports them through the active Respan pipeline.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [Complete Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/agentops)
* [Decorator hierarchy](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/agentops/01_decorator_hierarchy.py)
* [Agent decorator and expected failure](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/agentops/02_agent_and_failure.py)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-agentops agentops
```

#### Set your API key

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

#### Initialize and run

Initialize Respan before calling AgentOps-decorated code. You do not need to call `agentops.init()` or configure a second exporter.

**`Python`**

```python Python
from agentops import guardrail, task, tool, trace, workflow
from respan import Respan
from respan_instrumentation_agentops import AgentOpsInstrumentor

respan = Respan(
    instrumentations=[AgentOpsInstrumentor()],
)


@guardrail
def validate_city(city: str) -> str:
    if not city:
        raise ValueError("city is required")
    return city


@tool
def lookup_temperature(city: str) -> dict[str, object]:
    return {"city": city, "temperature_c": 21}


@task
def format_forecast(payload: dict[str, object]) -> str:
    return f"{payload['city']}: {payload['temperature_c']} C"


@workflow
def weather_workflow(city: str) -> str:
    return format_forecast(lookup_temperature(validate_city(city)))


@trace
def run() -> str:
    return weather_workflow("Paris")


try:
    print(run())
finally:
    respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to inspect the decorator hierarchy, inputs and outputs, and failures.

## What gets traced

The integration adapts the span kinds emitted by the installed AgentOps SDK.

| AgentOps kind                        | Respan span | Captured details                                                  |
| ------------------------------------ | ----------- | ----------------------------------------------------------------- |
| `session`, `workflow`                | `workflow`  | Decorator name, input, output, end state, tags                    |
| `agent`                              | `agent`     | Agent name and AgentOps decorator content                         |
| `task`, `operation`, `chain`, `http` | `task`      | Operation identity and decorator content                          |
| `tool`                               | `tool`      | Tool name, input, output, and status                              |
| `guardrail`                          | `guardrail` | Guardrail name, input, output, and status                         |
| `llm`                                | `chat`      | AgentOps GenAI messages, functions, model, and usage when emitted |
| `text`                               | `text`      | AgentOps text-generation attributes when emitted                  |

The adapter promotes only attributes AgentOps actually emits. It does not synthesize model, token, tool-call, or response fields for decorator kinds that do not provide them.

## Content controls

Content capture is enabled by default. Disable it when decorator arguments or results may contain sensitive data:

```python
from respan import Respan
from respan_instrumentation_agentops import AgentOpsInstrumentor

respan = Respan(
    instrumentations=[AgentOpsInstrumentor(capture_content=False)]
)
```

Operation names, kinds, tags, end state, and success/error status remain available.

## Lifecycle

`AgentOpsInstrumentor` connects AgentOps' tracing core to the active Respan tracer provider without starting AgentOps' exporter or metrics pipeline. `activate()` and `deactivate()` are reference-counted across instrumentor instances, and Respan retains ownership of tracer-provider shutdown.

Initialize Respan before the first decorated call. Call `respan.shutdown()` during application shutdown to flush pending spans and restore the prior AgentOps tracing state.