🔁🔗🤖 otel-a2a-relay (o2r)

Agent activity as OTel spans. Every agent message, handoff, and task transition becomes a queryable trace any OTel-native tool can render. A2A is the current wire format; the session derivation generalizes to any transport-keyed channel (GitHub issue, Slack thread, Linear ticket), so the same trace shape holds when other wire formats land.

otel-a2a-relay is the canonical name (repo, package, protocol doc). o2r is the dictation-friendly shortname used in CLI entrypoints, span identifiers (service.name=o2r), and prose.

A real run, animated: four agents coordinating a live cross-node k3s flannel fix through one relay, rendered straight from the channel's OTel spans in start-time order, host/network identifiers scrubbed. See docs/visualization.md.

What it ships

Agent peers coordinate through this relay; every message becomes OTel spans exported via OTLP/HTTP to whatever OTEL_EXPORTER_OTLP_ENDPOINT points at. The trace IS the operations view. Two coordination shapes share one span schema:

1. A2A wire format - JSON-RPC 2.0 over HTTP into traces, with a deterministic sha256(<repo>:<issue>) session ID for issue-rooted coordination.
2. Agent Channel - a Postgres-backed channel with 4-character dictatable IDs, an append-only event log (spec/state/status/comms/log), and a self-describing onboarding endpoint. Spec: docs/channels-protocol.md. Every channel event also emits one OTel span.

Trace propagation is W3C traceparent end-to-end (client → relay → peer is one trace). Default visualizer is Phoenix; anything OTLP-native works. Full inventory: docs/FEATURES.md.

Workspace layout

A uv workspace: a backend-agnostic core plus per-backend extensions, each a publishable package.

• otel-a2a-relay-core - relay HTTP server, tracing.bootstrap(), echo peer, task store. No backend coupling.
• otel-a2a-relay-channels - the Agent Channel layer (FastAPI router + Postgres + Pydantic).
• otel-a2a-relay-arize-phoenix - Phoenix harness, query helpers, animated topology GIF renderer, make view.
• otel-a2a-relay-tempo-grafana - Tempo bootstrap helper, harness probe, dockerized Tempo+Grafana stack.
• luca-flow - the AURORA microsite multi-agent demo, backend-agnostic.

Where to go next

• docs/quickstart.md - run it against Phoenix, Tempo, or any OTLP backend; A2A methods.
• docs/protocol.md - the span shape and the v0.1 decisions behind it.
• docs/visualization.md - static topology and the animated session hero.
• examples/luca-flow/README.md - the multi-agent choreography and validation rules.

Deploy

Deploy artifacts live in-tree (core/chart/, core/Dockerfile) so they version with the code; only the GitOps deployment state lives elsewhere. See docs/FEATURES.md.

See also

• AGENTS.md - agent-facing operating rules.
• docs/FEATURES.md - inventory of what ships today.
• .coily/coily.yaml and .ward/ward.yaml - allowlisted commands; route through the gate, not bare make / uv / python.

Cross-reference convention from coilysiren/agentic-os#59. This repo is the worked example.

License

MIT.