Metadata-Version: 2.1
Name: respan-exporter-anthropic-agents
Version: 1.0.14
Summary: Exporter for Anthropic Agent SDK telemetry to Respan
License: Apache 2.0
Author: Respan
Author-email: team@respan.ai
Requires-Python: >=3.11,<3.14
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: claude-agent-sdk (>=0.1.0)
Requires-Dist: respan-sdk (>=2.3.1,<3.0.0)
Requires-Dist: respan-tracing (>=2.1.0,<3.0.0)
Description-Content-Type: text/markdown

# Respan Exporter for Anthropic Agent SDK

**[respan.ai](https://respan.ai)** | **[Documentation](https://respan.ai/docs)**

Exporter for Anthropic Agent SDK telemetry to Respan.

## Configuration

### 1. Install

```bash
pip install claude-agent-sdk respan-exporter-anthropic-agents
```

### 2. Set Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `RESPAN_API_KEY` | Yes | Respan API key used for telemetry export. |
| `RESPAN_BASE_URL` | No | Respan base URL for telemetry export. Defaults to `https://api.respan.ai`. |
| `ANTHROPIC_BASE_URL` | No | Inference/proxy base URL used by the Anthropic SDK. |
| `ANTHROPIC_API_KEY` | Usually | Key used by the Anthropic SDK for inference calls. |
| `ANTHROPIC_AUTH_TOKEN` | Optional | Alternate auth token used by some Anthropic client flows. |

Set both groups together when needed. `RESPAN_*` controls tracing export, while `ANTHROPIC_*` controls where model requests are sent.

```bash
# Tracing export (Respan telemetry)
RESPAN_API_KEY=your_respan_key
RESPAN_BASE_URL=https://api.respan.ai/api

# Inference/proxy routing (Anthropic SDK)
ANTHROPIC_BASE_URL=http://localhost:8000/api
ANTHROPIC_API_KEY=your_inference_key
ANTHROPIC_AUTH_TOKEN=your_inference_key
```

`RESPAN_BASE_URL` controls telemetry export only. The exporter automatically appends `/api/v1/traces/ingest` to build the full ingest endpoint.

### Constructor Parameters (Optional)

All configuration can also be passed directly to the constructor.

Recommended pattern (matches the runnable examples):

```python
exporter = RespanAnthropicAgentsExporter(
    api_key="your_respan_key",        # Optional; falls back to RESPAN_API_KEY
    base_url="https://api.respan.ai", # Optional; falls back to RESPAN_BASE_URL
)
```

Local gateway/proxy override:

```python
exporter = RespanAnthropicAgentsExporter(
    api_key="your_respan_key",
    base_url="http://localhost:8000/api",
)
```

Resolution order:
- `api_key`: constructor `api_key` -> `RESPAN_API_KEY`
- `endpoint`: constructor `endpoint` -> derived from constructor `base_url` -> derived from `RESPAN_BASE_URL`

In normal usage you should set `base_url` (or `RESPAN_BASE_URL`) and let the exporter derive the ingest endpoint automatically.
`endpoint` exists for internal/advanced cases and takes precedence over `base_url` if both are set.

## Quickstart

### 3. Run Script

Save this as `quickstart.py`:

```python
import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions
from respan_exporter_anthropic_agents.respan_anthropic_agents_exporter import (
    RespanAnthropicAgentsExporter,
)

respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api").rstrip("/")
anthropic_base_url = os.getenv("ANTHROPIC_BASE_URL", f"{respan_base_url}/anthropic")
anthropic_api_key = os.getenv("ANTHROPIC_API_KEY", respan_api_key)

exporter = RespanAnthropicAgentsExporter(
    api_key=respan_api_key,
    base_url=respan_base_url,
)

async def main() -> None:
    options = exporter.with_options(
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="acceptEdits",
            env={
                "ANTHROPIC_BASE_URL": anthropic_base_url,
                "ANTHROPIC_API_KEY": anthropic_api_key,
                "ANTHROPIC_AUTH_TOKEN": os.getenv("ANTHROPIC_AUTH_TOKEN", anthropic_api_key),
            },
        )
    )

    async for message in exporter.query(
        prompt="Analyze this repository and summarize architecture.",
        options=options,
    ):
        print(message)

asyncio.run(main())
```

Run it:

```bash
python quickstart.py
```

### 4. View Dashboard

Open:

- `https://platform.respan.ai/platform/traces`

## Further Reading

Runnable examples with full setup instructions:

- **Python examples root:** [python/tracing/anthropic-agents-sdk](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/anthropic-agents-sdk)
- **Python basic scripts:**
  - [hello_world_test.py](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/anthropic-agents-sdk/basic/hello_world_test.py)
  - [wrapped_query_test.py](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/anthropic-agents-sdk/basic/wrapped_query_test.py)
  - [tool_use_test.py](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/anthropic-agents-sdk/basic/tool_use_test.py)
  - [gateway_test.py](https://github.com/respanai/respan-example-projects/blob/main/python/tracing/anthropic-agents-sdk/basic/gateway_test.py)
- **TypeScript examples root:** [typescript/tracing/anthropic-agents-sdk](https://github.com/respanai/respan-example-projects/tree/main/typescript/tracing/anthropic-agents-sdk)

## Dev Guide

### Running Tests

```bash
# Unit tests
python -m unittest tests.test_exporter -v

# Live integration test (opt-in, makes real API calls)
export RESPAN_API_KEY="your_respan_key"
export IS_REAL_GATEWAY_TESTING_ENABLED=1
python -m unittest tests.test_real_gateway_integration -v
```

