Metadata-Version: 2.4
Name: agentq
Version: 0.1.0
Summary: AgentQ SDK — agent observability for Python.
Author: Ryan Dao
License-Expression: MIT
Project-URL: Homepage, https://github.com/ryandao/agentq
Project-URL: Repository, https://github.com/ryandao/agentq
Project-URL: Issues, https://github.com/ryandao/agentq/issues
Keywords: observability,ai-agents,llm,tracing,opentelemetry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Provides-Extra: celery
Requires-Dist: celery>=5.0; extra == "celery"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: google-genai>=1.0; extra == "all"
Requires-Dist: celery>=5.0; extra == "all"

# AgentQ SDK

A Python SDK for instrumenting AI agents with observability. Traces agent runs, LLM calls, and tool invocations, sending data to an AgentQ server via OpenTelemetry.

## Installation

```bash
pip install agentq
```

For auto-instrumentation of specific LLM providers, install them alongside:

```bash
pip install agentq openai anthropic google-genai
```

## Quick Start

```python
import agentq

# Point to your AgentQ server
agentq.init(endpoint="http://localhost:3000")

# Auto-patch supported LLM libraries
agentq.instrument()

@agentq.agent(name="my-agent")
def run_task(prompt: str) -> str:
    # Any OpenAI/Anthropic/Gemini calls inside here are traced automatically
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content
```

## Features

- **`@agent` decorator** -- Wraps functions and classes to create traced runs with input/output capture
- **Auto-instrumentation** -- Monkey-patches OpenAI, Anthropic, and Google Gemini to trace every LLM call
- **Session tracking** -- Group related runs into sessions with the `session` context manager
- **Nested spans** -- Nested `@agent` calls and manual `track_agent`/`track_llm`/`track_tool` spans
- **Celery integration** -- Captures queue wait time for Celery tasks
- **OpenTelemetry native** -- Built on OpenTelemetry, compatible with any OTLP endpoint

## API Reference

### `agentq.init(endpoint, headers, service_name)`

Initialize the SDK. Call once at startup.

- `endpoint` -- OTLP HTTP base URL (e.g. `http://localhost:3000`). Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`.
- `headers` -- Extra headers for OTLP requests (e.g. `{"Authorization": "Bearer sk-xxx"}`).
- `service_name` -- Value for the `service.name` resource attribute (default: `"agentq"`).

### `agentq.instrument()`

Activate auto-instrumentation for OpenAI, Anthropic, Google Gemini, and Celery. Safe to call even if libraries aren't installed.

### `@agentq.agent(name, entry_method, description, version, metadata)`

Decorator for functions or classes. Creates a traced run for each invocation.

For classes, `entry_method` specifies which method(s) to instrument (default: `"execute"`).

### `agentq.session(name, session_id, run_id, metadata)`

Context manager that groups runs into a session:

```python
with agentq.session(name="user-chat"):
    run_task("Hello")
    run_task("Follow up")
```

### Manual Span Context Managers

```python
with agentq.track_agent("sub-agent") as span:
    ...

with agentq.track_llm("gpt-4") as span:
    ...

with agentq.track_tool("web-search") as span:
    ...
```

## License

[MIT](../LICENSE)
