Schema compliance. In CI.

AgentOBSValidate is the reference validation CLI and Python SDK for the AGENTOBS event standard. Validate JSON and JSONL event streams, verify HMAC signing chains, and catch non-compliance at build time — before it reaches production.

AgentOBS SDK →Debug tooling →

Installation

One command to install.

pip install agentobs-validate

Quickstart · CLI

Validate from the terminal.

Point agentobs-validate at any JSONL file produced by the AgentOBS SDK. Pass a file path, pipe from stdin, or integrate it as a step in your CI workflow.

bash

# Validate a JSONL stream
agentobs-validate events.jsonl

# Validate a JSON array
agentobs-validate events.json

# JSON output for CI / downstream scripts
agentobs-validate events.jsonl --json

# Read from STDIN
cat events.jsonl | agentobs-validate

# OpenTelemetry compatibility: accept camelCase field names
agentobs-validate events.jsonl --otel

# Pin to a specific schema version
agentobs-validate events.jsonl --schema-version 0.1

# Cryptographic HMAC-SHA256 signature verification
agentobs-validate events.jsonl --key-file signing.key

# Export the AgentOBS event JSON Schema (Draft 2020-12)
agentobs-validate --export-schema > agentobs-schema.json

Exit codes

Code	Meaning
0	All events passed validation. Safe to proceed.
1	One or more events failed. Details printed to stdout.
2	Input could not be parsed (malformed JSON or unreadable file).

Quickstart · Python API

Programmatic validation.

Import agentobs_validate to validate individual events or entire streams in your test suite, CI scripts, or monitoring pipelines.

python

from agentobs_validate.validator.engine import validate_event, validate_stream
from agentobs_validate.validator.input_parser import iter_events
from agentobs_validate.validator.context import ValidationContext

# Validate a single dict
result = validate_event(1, {
    "event_id": "01HZQSN7PQVR2K4M0BXJD3GSTA",
    "timestamp": "2026-03-06T10:00:00.000Z",
    "event_type": "agent.plan.created",
    "source": "spanforge@1.0.0",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7",
})
print(result.status)  # "pass"

# Validate a stream from a file
with open("events.jsonl") as f:
    for result in validate_stream(iter_events(f)):
        if result.status == "fail":
            print(f"Line {result.line}: {result.errors}")

CLI Reference

All options.

<file>Validate a JSONL stream or JSON array file.

--jsonJSON output for CI systems and downstream scripts.

cat file | agentobs-validateRead from STDIN — pipe-friendly for CI step composition.

--otelOpenTelemetry compatibility mode — accept camelCase field names.

--schema-version <ver>Pin validation to a specific schema version, e.g. --schema-version 0.1.

--key-file <path>Cryptographic HMAC-SHA256 signature verification using a key file.

--export-schemaExport the AgentOBS event JSON Schema (Draft 2020-12) to stdout.

CI Integration

Add to your pipeline in two lines.

AgentOBSValidate exits 0 on success and 1 on failure, making it a natural CI gate. Run it in any GitHub Actions, GitLab CI, or Jenkins pipeline step.

yaml

# GitHub Actions example
- name: Validate AgentOBS events
  run: |
    pip install agentobs-validate
    agentobs-validate tests/fixtures/events.jsonl --json

Use --json to get structured output for downstream processing, test-result reporting, or integration with your existing observability stack.

The full stack

Standard. SDK. Debug. Validate.

Every layer of the AgentOBS observability stack is open, documented, and ready to instrument your production AI agents.

Read the standard →AgentOBS overview →

← AgentOBSDebug AgentOBS overview →