AgentOBSPython SDK
agentobs · Python 3.9+

The reference implementation.

pip install agentobs — zero required dependencies, all 10 AGENTOBS namespaces, a full CLI, and integrations for OpenAI, LangChain, LlamaIndex, CrewAI, and Datadog.

Debug tooling →Read the standard →
Installation

Get started in one command.

Install the base SDK with no required dependencies. Add optional extras for the integrations and export targets you need.

pip install agentobs

Verify the installation:

bash
agentobs --version
# agentobs 1.0.8 [AGENTOBS-Enterprise-2.0]

Optional extras

ExtraWhat it adds
agentobs[jsonschema]Enables runtime schema validation of every emitted event against the published JSON Schema.
agentobs[openai]Auto-instrumentation for the openai Python client — wraps chat completions, embeddings, and responses.
agentobs[http]OTLP/HTTP export and webhook export targets.
agentobs[pydantic]Pydantic v2 model support for typed payload validation.
agentobs[otel]Full OpenTelemetry SDK integration — exports spans as OTLP proto via grpc or http.
agentobs[kafka]Apache Kafka export backend for streaming event pipelines.
agentobs[langchain]LangChain callback handler — instruments chain, tool, and LLM calls automatically.
agentobs[llamaindex]LlamaIndex event handler — instruments query, retrieval, and LLM calls.
agentobs[crewai]CrewAI task-and-agent lifecycle instrumentation.
agentobs[datadog]Datadog exporter — ships events to DD APM as custom spans.
agentobs[all]Installs all optional extras in a single command.
Quickstart

Your first event.

Every event in the AGENTOBS standard is an Event object with three required arguments: event_type, source, and payload.

python
from agentobs import Event

# Minimal event
event = Event(
    event_type="llm.trace.span",
    source="my-service@0.1.0",
    payload={"span_name": "summarise", "status": "ok"},
)

# Event is ready to emit or inspect
print(event.event_id)    # ULID e.g. 01HZQSN7PQVR2K4M0BXJD3GSTA
print(event.timestamp)   # ISO-8601 UTC
print(event.trace_id)    # W3C-compatible 128-bit hex

Typed namespace payloads

Use the typed payload classes from each namespace for full schema validation and IDE autocompletion. The classes map 1-to-1 to the published JSON Schema.

python
from agentobs import Event
from agentobs.namespaces.trace import SpanPayload, TokenUsage, ModelInfo

event = Event(
    event_type="llm.trace.span",
    source="spanforge@1.0.0",
    payload=SpanPayload(
        span_name="summarise_document",
        span_kind="LLM",
        status="ok",
        duration_ms=830,
        token_usage=TokenUsage(prompt=411, completion=128, total=539),
        model_info=ModelInfo(provider="openai", model="gpt-4o"),
    ),
    tags=["prod", "summarisation"],
)

# Export to OTLP
from agentobs.export import OTLPExporter
exporter = OTLPExporter(endpoint="http://localhost:4317")
exporter.export(event)
Integrations

Works with your existing stack.

Install the relevant extra and add one line of code. AGENTOBS events are emitted automatically — you retain full visibility without rewriting your instrumentation.

OpenAI · agentobs[openai]

OpenAI

One-line auto-instrumentation for the openai Python client. Wraps chat completions, embeddings, and the Responses API. Emits llm.trace.span and llm.cost.* events automatically.

LangChain · agentobs[langchain]

LangChain

Drop-in callback handler. Instruments chain invocations, tool calls, and LLM calls. Compatible with LangChain v0.1 and v0.2.

LlamaIndex · agentobs[llamaindex]

LlamaIndex

Event handler for the LlamaIndex instrumentation API. Captures query, retrieval, embedding, and LLM events with full trace context.

CrewAI · agentobs[crewai]

CrewAI

Task and agent lifecycle instrumentation for CrewAI. Captures agent run start/end, task assignment, and tool delegation events.

Datadog · agentobs[datadog]

Datadog

Export agentobs span events as custom Datadog APM spans. Compatible with the Datadog Agent and the dd-trace-py client.

OpenTelemetry · agentobs[otel]

OpenTelemetry

Full OTLP bridge. Converts agentobs span events to OpenTelemetry proto-compatible dicts and exports via gRPC or HTTP. Works with any OTEL-compatible backend.

Command-line interface

Operational tooling included.

The agentobs CLI is installed automatically with the SDK. Use it for health checks, schema validation, audit-chain verification, and migration tooling.

agentobs checkEnd-to-end health check: config, event creation, schema validation, export pipeline, trace store.
agentobs check-compatValidate a batch of events against the v1.0 compatibility checklist (CHK-1 through CHK-5).
agentobs validateValidate every event in a JSONL file against the published JSON Schema.
agentobs audit-chainVerify HMAC-SHA256 signing chain integrity of events in a JSONL file.
agentobs inspectPretty-print a single event by event_id from a JSONL file.
agentobs statsPrint event-type counts, trace count, and time range for a JSONL file.
agentobs list-deprecatedPrint all deprecated event types from the global deprecation registry.
agentobs migration-roadmapPrint the planned v1 → v2 migration roadmap.
agentobs check-consumersAssert all registered consumers are compatible with the installed schema.
bash
# End-to-end health check
agentobs check
# [1/5] Config ............. OK
# [2/5] Event creation ..... OK
# [3/5] Schema validation .. OK
# [4/5] Export pipeline .... OK
# [5/5] Trace store ........ OK
# All checks passed.

# Validate a JSONL event stream
agentobs validate production-events.jsonl

# Lint your instrumentation code
python -m agentobs.lint src/
Code quality

SDK instrumentation linter.

The built-in linter parses your Python source with ast and runs five checks to catch common instrumentation mistakes before they reach production. Integrates natively with flake8 and ruff.

AO001Event() missing one of event_type, source, or payload.
AO002Bare str literal passed to actor_id, session_id, or user_id — wrap in Redactable().
AO003event_type= string not present in registered EventType values.
AO004LLM provider API call outside a tracer.span() / agent_run() context.
AO005emit_span / emit_agent_* called outside agent_run() / agent_step() context.
Next steps

Inspect. Validate. Ship.

Use AgentOBSDebug to inspect and replay traces, and AgentOBSValidate to enforce schema compliance in your CI pipeline.

AgentOBSDebug →AgentOBSValidate →
← RFC-0001 StandardAgentOBSDebug →