AgentOBSRFC-0001 Standard
Open Standard · Public Review

RFC-0001 AGENTOBS

An open event-schema standard for observability of agentic AI systems. Defines a structured event envelope, 10 observability namespaces, HMAC audit chains, PII redaction, and four conformance profiles — from basic AI spans to enterprise compliance.

Python SDK implementation →Validate events →
Background

Why a standard for AI observability?

Agentic AI systems produce observability data that is fundamentally different from traditional distributed-systems telemetry. A single agent run can span dozens of LLM calls, tool invocations, sub-agent delegations, and reasoning steps — each with its own cost, latency, and risk profile.

Yet today there is no broadly adopted cross-vendor standard for what an “AI observability event” looks like: what fields it carries, how it identifies its place in a multi-agent trace tree, how cost is attributed across nested steps, how PII is handled before data reaches a backend, or how the integrity of an audit trail is guaranteed.

AGENTOBS fills this gap. It is a community-driven specification (RFC process operated by the llm-toolkit community) designed for incremental adoption and vendor-neutral integration.

Specification

The Event Envelope

Every AGENTOBS event is wrapped in a typed envelope with six required fields and four optional fields. The envelope is serialised as JSON and is designed to be compatible with OpenTelemetry span context.

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"],
)
FieldTypeRequiredDescription
event_idstring (ULID)RequiredGlobally unique monotonic event identifier.
timestampISO-8601 UTCRequiredUTC timestamp with millisecond precision.
event_typestringRequiredDot-separated namespace path, e.g. llm.trace.span.
sourcestringRequiredEmitting tool and version, e.g. spanforge@1.0.0.
trace_idhex-32RequiredW3C TraceContext-compatible 128-bit trace identifier.
span_idhex-16Required64-bit span identifier within the trace.
payloadobjectRequiredNamespace-typed payload object (schema varies by event_type).
parent_span_idhex-16OptionalParent span_id for nested span trees.
tagsstring[]OptionalArbitrary string tags for filtering and grouping.
hmacstringOptionalHMAC-SHA256 signature for audit chain integrity.
Namespace Taxonomy

10 observability domains.

AGENTOBS defines 36 event types across 10 namespaces (plus one security domain — audit). Every event type is dot-separated, typed, and has a versioned JSON Schema payload definition.

llm.trace.*Span lifecycle events — agent runs, steps, tool calls, and OpenTelemetry-compatible span trees.
llm.cost.*Token usage and USD cost attribution across models, steps, and sessions.
llm.cache.*Semantic cache hit/miss/write/evict events with cosine-similarity scores.
llm.diff.*Prompt or output diff events for detecting changes between runs.
llm.eval.*Evaluation results — scores, pass/fail status, and evaluator metadata.
llm.fence.*Constraint boundary checks — input/output fenced against defined policies.
llm.guard.*Safety and content-policy checks with provider and outcome metadata.
llm.prompt.*Prompt rendering and template resolution events with variable bindings.
llm.redact.*PII detection and redaction events, including field-level re-identification risk.
llm.template.*Template registration, rendering, and version-diff events.
Security

HMAC-SHA256 audit chains.

AGENTOBS includes a tamper-evident audit logging mechanism. Each event can carry an HMAC-SHA256 signature that chains it to the preceding event in a session. Verifying the chain proves that the event stream has not been modified, re-ordered, or truncated after the fact.

Audit chain integrity can be verified programmatically via the Python SDK or on the command line with agentobs audit-chain events.jsonl.

bash
# Verify HMAC signing chain integrity
agentobs audit-chain production-events.jsonl

# Expected output:
# [OK] Chain verified: 1,204 events, no breaks detected.
Adoption

Four conformance profiles.

AGENTOBS is designed for incremental adoption. Start with the Core profile and layer in Security, Privacy, and Enterprise capabilities as your requirements grow.

Conformance Profile

AGENTOBS-Core-1.0

Structured event envelope with at least llm.trace.* events. The baseline for any compliant implementation.

Conformance Profile

AGENTOBS-Security-2.0

Core plus HMAC-SHA256 audit chains. Required for compliance-grade tamper-evident logging.

Conformance Profile

AGENTOBS-Privacy-2.0

Core plus PII redaction via llm.redact.* namespace before any event reaches a backend.

Conformance Profile

AGENTOBS-Enterprise-2.0

All four profiles combined. Export abstraction, governance primitives, and schema migration tooling included.

Versioning

Schema versions.

The AGENTOBS schema is versioned using semantic versioning. The v1.0 schema is the stable baseline; v2.0 extends it with additional namespace event types and governance primitives. Both schemas are published as JSON Schema Draft 2020-12 and can be exported via the validation CLI.

bash
# Export the current schema (v2.0 by default)
agentobs-validate --export-schema > agentobs-schema.json

# Pin validation to a specific schema version
agentobs-validate events.jsonl --schema-version 1.0
VersionStatusNotes
v1.0StableOriginal envelope + trace, cost, cache, eval, guard namespaces.
v2.0CurrentFull 10-namespace taxonomy, HMAC chains, PII redaction, governance primitives.
Get started

Implement the standard.

The Python SDK is the reference implementation. Zero required dependencies, pip-installable, covers all 10 namespaces.

Python SDK →Validate your events →
← AgentOBS overviewPython SDK →