> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentOps

> Integrate AgentOps observability with PraisonAI agents

# AgentOps Integration

[AgentOps](https://agentops.ai/) provides agent monitoring, debugging, and optimization.

<Note>
  AgentOps is treated as a soft optional dependency. If the package isn't installed, PraisonAI skips telemetry without raising; if `end_session()` fails at runtime, the failure is logged as a warning and the agent run still returns its result.
</Note>

## Setup

### 1. Install Dependencies

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install agentops
```

### 2. Set Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export AGENTOPS_API_KEY=xxx
```

### 3. Initialize

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools.observability import obs

obs.init(provider="agentops")
```

### How Integration Works

* AgentOps is **optional**: if `pip install agentops` hasn't been run, PraisonAI silently skips session telemetry.
* After every agent execution — on both success and failure paths — the wrapper calls `praisonai.observability.hooks.finalize_observability(adapter_name, status=…)` from a `finally` block. `status` is `"Success"` when no exception is propagating and `"Failure"` otherwise (errors, `KeyboardInterrupt`, cancellation, rate limits). Failures inside the end-session call are logged at `WARNING` level and never propagate.
* Detection happens once at module import via `importlib.util.find_spec("agentops")`. Installing `agentops` after the process started will not be picked up — restart the process.
* PraisonAI auto-inits AgentOps for you if `AGENTOPS_API_KEY` is set in the environment. The init is centralized in `praisonai.observability.hooks.init_observability(framework_tag, tags=...)` and is called automatically by the orchestrator before any adapter runs. You can call it yourself from a custom framework adapter's `setup()` hook if you need control over the tags.

<Info>
  See [Observability Hooks](/docs/features/observability-hooks) for details on the centralized observability system and how to use it in custom adapters. The centralized `finalize_observability(...)` hook is documented in [Observability Hooks → Quick Start](/docs/features/observability-hooks#quick-start).
</Info>

## Usage

### Auto-Instrumentation (Recommended)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools.observability import obs
from praisonaiagents import Agent

obs.init(provider="agentops")

# Everything is auto-traced!
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    model="gpt-4o-mini",
)

response = agent.chat("Hello!")
print(response)
```

### Explicit Tracing (For Fine Control)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools.observability import obs
from praisonaiagents import Agent

obs.init(provider="agentops", auto_instrument=False)

agent = Agent(
    instructions="You are a helpful assistant.",
    model="gpt-4o-mini",
)

with obs.trace("session"):
    response = agent.chat("Hello!")
    print(response)
```

## Configuration Options

| Option               | Environment Variable | Description                        |
| -------------------- | -------------------- | ---------------------------------- |
| `api_key`            | `AGENTOPS_API_KEY`   | Your AgentOps API key              |
| `tags`               | -                    | Default tags for sessions          |
| `auto_start_session` | -                    | Auto-start session (default: True) |

## Dashboard

View your agent sessions at [app.agentops.ai](https://app.agentops.ai)