agentq

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

pip install agentq

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

pip install agentq openai anthropic google-genai

Quick Start

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:

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

Manual Span Context Managers

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