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
@agentdecorator -- 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
sessioncontext manager - Nested spans -- Nested
@agentcalls and manualtrack_agent/track_llm/track_toolspans - 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 toOTEL_EXPORTER_OTLP_ENDPOINT.headers-- Extra headers for OTLP requests (e.g.{"Authorization": "Bearer sk-xxx"}).service_name-- Value for theservice.nameresource 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
Metadata
Release files for agentq 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentq-0.1.0.tar.gz | 14.7 kB | With provenance | Details for agentq-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentq-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentq-0.1.0-py3-none-any.whl |
Total release size: 32.7 kB
Release files / agentq-0.1.0.tar.gz
| Download URL | agentq-0.1.0.tar.gz |
|---|---|
| Size | 14.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36123352d52353e3919b2c8cb6e1cccdd8a311aa5a9f42ca18ddbb789d71c639
|
|
BLAKE2b-256 checksum How to use checksums |
92b4920fee402a50785fa566df8b4c121997113462b4a5d05d15be714bd3ddcd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.
Transparency logRelease files / agentq-0.1.0-py3-none-any.whl
| Download URL | agentq-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a6ba590ae59742c0dea61b7f6da328bbf96f1700700bfbc361673edf1c64dcbd
|
|
BLAKE2b-256 checksum How to use checksums |
a423a9fa617222286f11e6ed5dd2becf87a69cb8e03dfd937ef8b5d7aac4c330
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.
Transparency logSecurity for agentq 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentq-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.