Delivery and reliability

Lynx delivery is designed so event delivery problems do not stop your AI service by default.

When to use this

Read this page before using the SDK in production, serverless functions, workers, or request paths where event delivery should not block user traffic.

How it works

The SDK keeps events in memory and sends them in batches. Delivery runs in the background by default. If delivery fails, events move to a retry buffer and the SDK backs off. After repeated failures, the circuit breaker opens and pauses delivery attempts for a cooldown period.

Production defaults

Option	Default
`delivery.mode`	`"BACKGROUND"`
`delivery.timeoutMs`	`1000`
`delivery.flushOnRunEnd`	`false`
`delivery.flushIntervalMs`	`3000`
`delivery.batchSize`	`50`
`delivery.maxQueueSize`	`1000`
`delivery.overflowStrategy`	`"DROP_OLDEST"`
`circuitBreaker.enabled`	`true`
`circuitBreaker.failureThreshold`	`3`
`circuitBreaker.cooldownMs`	`30000`

Background delivery

In background mode, run() records events locally and returns without waiting for event delivery.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BACKGROUND",
    timeoutMs: 1000,
    flushOnRunEnd: false,
  },
});

The SDK sends events from:

The background flush timer
An explicit flush() call
A shutdown() call

Blocking mode

Use BLOCKING mode only when the current process should attempt delivery during the request lifecycle.

const lynx = new LynxTracer({
  clientId: "worker",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BLOCKING",
    flushOnRunEnd: true,
    timeoutMs: 1500,
  },
});

Delivery errors are still handled inside the SDK. They do not become agent workflow errors.

Flush and shutdown

Use flush() when you want to send the current queue and keep using the SDK.

await lynx.flush();

Use shutdown() before a process exits or at the end of a serverless handler when you want a best-effort final send.

await lynx.shutdown({ timeoutMs: 1000 });

Local status

Use getStatus() to inspect local SDK delivery state.

const status = lynx.getStatus();

console.log(status.queueSize);
console.log(status.circuitState);
console.log(status.droppedEvents);
console.log(status.pendingTransmissions);

If the Lynx API is unavailable

Your service keeps running by default. The SDK:

Catches network, timeout, and non-2xx response errors
Moves failed batches into an in-memory retry queue
Uses backoff before retrying
Opens the circuit breaker after repeated failures
Drops events according to overflowStrategy when the queue is full

Notes

Events are stored in memory, not on disk. If the process exits before events are sent, unsent events may be lost. Use shutdown() when graceful exit matters. Firewall decisions run locally. The Lynx API being unavailable does not decide whether a protected tool call is allowed or blocked.

Getting started

TypeScript SDK

OpenAPI

Delivery and reliability

When to use this

How it works

Production defaults

Background delivery

Blocking mode

Flush and shutdown

Local status

If the Lynx API is unavailable

Notes

Next steps

​When to use this

​How it works

​Production defaults

​Background delivery

​Blocking mode

​Flush and shutdown

​Local status

​If the Lynx API is unavailable

​Notes

​Next steps

When to use this

How it works

Production defaults

Background delivery

Blocking mode

Flush and shutdown

Local status

If the Lynx API is unavailable

Notes

Next steps