Skip to content

architecture.md

Latest commit

 

History

History
91 lines (66 loc) · 4.41 KB

architecture.md

File metadata and controls

91 lines (66 loc) · 4.41 KB
Raw

Architecture

Boundary

AgentTrust Telemetry is a schema-first instrumentation layer between governance sources and adopter-owned telemetry/evidence destinations.

policy / approval / usage / data hooks
                 │
                 v
        normalized event contract
                 │
          schema + privacy gate
                 │
        ┌────────┴─────────┐
        v                  v
 OTel projection     evidence projection
 (best effort)       (future, durable)
        │                  │
 adopter's OTLP       TRACE finalizer
 collector/backend      (future)

Current components

Normative contract

JSON Schema 2020-12 files in spec/schema define the six event families. Closed schemas reject unknown top-level fields. A shared envelope supplies event, run, workflow, agent, task, producer, trace, and span correlation.

Conformance suite

Valid and invalid fixtures exercise each family, privacy rejection, missing measurements, and malformed trace context. The runner resolves schemas from an offline registry and never retrieves remote schema URLs.

Python reference SDK

The SDK validates an event before any projection. Under the default profile it rejects known content fields and all extension attributes unless each key is explicitly allowlisted.

If OpenTelemetry is installed, the SDK uses the caller's current span and adds a normalized span event. It does not create a tracer provider, processor, exporter, or duplicate agent/tool/model span.

A caller-owned structured-log emitter may receive a defensive deep copy of the validated event. Projection failures are reported independently in EmitResult.

TypeScript reference SDK

The Node reference package in packages/typescript shares the normative schemas, metadata-only privacy gate, normalized event factory, OTel span/log projection, and W3C plus AgentTrust context propagation semantics. Its schema copies are byte-compared to spec/schema in CI. It requires a caller-owned OTel provider, exporters, and global propagator.

Evidence accumulator

The optional accumulator receives validated events before OTel or log projection. It assigns a monotonic sequence and chains canonical event bytes with SHA-256. Memory mode is development-only. Callback mode requires the adopter's callback to acknowledge durable commit and to be idempotent by event_id; failure aborts operational projection and leaves local accumulator state retryable.

Sealing requires an explicit caller assessment of complete, incomplete, or unknown. An open run always reports unknown. This assessment is an input to future TRACE mapping, not proof generated by the accumulator.

Correlation semantics

  • run_id is the durable execution correlation key.
  • trace_id and span_id are optional lowercase W3C identifiers.
  • Nanosecond Unix timestamps are canonical decimal strings so JSON runtimes with IEEE-754 numbers preserve their exact 64-bit value.
  • When an active span exists, supplied IDs must match it.
  • Without an active span, the SDK never fabricates context; logs remain correlated by run_id.
  • Synchronous cross-process work uses extract_context(...).otel_context as the remote parent when starting the receiving span.
  • Asynchronous handoff/fan-in uses extract_context(...).link() and starts a new root span, preserving causal correlation without asserting synchronous parentage.
  • x-agentrust-run-id, x-agentrust-workflow-id, and x-agentrust-agent-id preserve durable run and agent-delegation metadata alongside standard W3C traceparent/tracestate. Extracted metadata is untrusted input.

Delivery semantics

Operational OTel signals are best effort and may be sampled or dropped. Future evidence accumulation will occur before OTel sampling through an explicit durability callback. A TRACE record must never be reconstructed from an observability backend while claiming completeness.

Dependency boundary

  • Core runtime: JSON Schema validation and standard library.
  • OTel integration: optional opentelemetry-api, caller configured.
  • Test integration: opentelemetry-sdk only.
  • No dependency on AGT, an agent framework, collector, backend, or TRACE package in core.

Version axes

Contract, SDK, OpenTelemetry semantic-convention profile, and TRACE schema versions evolve independently. Releases must state the supported combination and include golden fixtures for wire behavior.