Transport

How AOP events travel from your agent to the collector.

Overview

AOP uses a deliberately simple transport layer: a single HTTP POST endpoint. There is no websocket upgrade, no gRPC, no message queue. This keeps the SDK thin, the collector easy to implement, and the failure mode predictable.

Endpoint

POST /events

By default, the SDK sends events to:

http://localhost:4317/events

This can be configured via the endpoint option on AOPClient:

const aop = new AOPClient({
  agentId: 'my-agent',
  endpoint: 'http://my-server:9090'
})

Request format

Each request sends a single event as a JSON body.

POST /events HTTP/1.1
Host: localhost:4317
Content-Type: application/json

{
  "spec": "aop/1.0",
  "session_id": "sess_abc123",
  "agent_id": "my-agent",
  "sequence": 1,
  "timestamp": "2026-04-03T10:00:00.000Z",
  "type": "session.started",
  "payload": { "goal": "Summarize the document" }
}

Fire-and-forget semantics

The SDK does not wait for a response, retry on failure, or buffer events. Every call is fire-and-forget:

  • The HTTP request has a 500ms timeout. If the collector does not respond in time, the request is silently dropped.
  • Network errors, connection refused, and non-2xx responses are all silently swallowed.
  • The SDK methods return immediately. They do not await the HTTP call internally — they fire and move on.
  • If the collector is down, your agent keeps running with zero impact on performance or correctness.
This is the core AOP guarantee: observability never interferes with agent execution. Your agent cannot fail because of AOP.

Response

The collector responds with 202 Accepted on success. The SDK ignores this response. Collectors should keep response bodies minimal or empty.

Content-Type

All requests use Content-Type: application/json. The collector should reject requests with other content types with 415 Unsupported Media Type.

Conformance

Any HTTP server that accepts POST requests at /events with a JSON body matching the AOP envelope schema is a valid AOP collector. The official @useaop/collector package is the reference implementation.

Related