AOPClient

The core class of @useaop/sdk — a zero-dependency, fire-and-forget client for emitting Agent Observability Protocol (AOP) events.

Constructor

import { AOPClient } from '@useaop/sdk'

const aop = new AOPClient(options)

Options

Option	Type	Default	Description
`agentId`	string	required	Unique identifier for this agent
`endpoint`	string	`http://localhost:4317`	Base URL of the collector
`sessionId`	string	auto-generated UUID	Override the session ID (useful for child agents)
`parentSessionId`	string \| null	`null`	Links this session to a parent in the session tree
`agentVersion`	string	`undefined`	Semantic version of the agent, included in session.started
`timeout`	number	`500`	HTTP timeout in milliseconds for each event POST

Fire-and-forget principle

Every method on AOPClient is fire-and-forget. Internally, the SDK issues an HTTP POST but does not await the response or throw on failure. This means:

Your agent never blocks waiting for the collector.
If the collector is unreachable, events are silently dropped — no errors, no retries, no backpressure.
The SDK methods return synchronously (they return a Promise for API ergonomics, but it resolves immediately).

Enable / disable

You can dynamically enable or disable event emission:

aop.disable()  // All subsequent calls become no-ops
aop.enable()   // Resume emitting events

// Check current state
console.log(aop.enabled) // true | false

This is useful for conditionally disabling observability in production, test environments, or based on feature flags.

Properties

aop.sessionId       // string — the current session ID
aop.agentId         // string — the agent ID passed at construction
aop.enabled         // boolean — whether events are being emitted
aop.sequence        // number — the next sequence number

Method groups

Lifecycle methods — sessionStarted, heartbeat, sessionEnded
Cognition methods — thought, goal, decision, uncertainty
Operation methods — toolStart, toolEnd, agentSpawn, memory, externalCall