API reference

This page summarizes the primary SDK APIs. Use the feature guides for longer examples.

`LynxTracer`

LynxTracer records events, manages the active run context, and delivers event batches to Lynx.

import { LynxTracer } from "@lynxops/sdk";

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
});

`lynx`

lynx is a default tracer configured from environment variables.

import { lynx } from "@lynxops/sdk";

Use this for simple applications. Use new LynxTracer() when you need explicit configuration per process, tenant, or test.

Run methods

`run(agentName, callback)`

Runs code inside a Lynx context.

await lynx.run("SupportAgent", async () => {
  lynx.userInput("Help me reset my password");
});

`run(options, callback)`

Runs code with structured run metadata.

await lynx.run(
  {
    agentName: "SupportAgent",
    workspaceId: "workspace_123",
    agentId: "agent_123",
    sessionId: "session_123",
  },
  async () => {
    // Agent work
  },
);

Managed prompts

`getPrompt(id)`

Returns the active immutable prompt by stable name or prompt UUID. Call it inside run() to pin the selected version and attach its versionId to related events.

await lynx.run("SupportAgent", async () => {
  const prompt = await lynx.getPrompt("support-system");
  await callModel({ instructions: prompt.content });
});

The promise rejects when no valid runtime configuration is available or the prompt is not deployed for the API key environment and Agent scope.

`initialize()`

Loads managed prompts and firewall policies immediately. Concurrent calls share one request. Most applications can use runtimeConfig.enabled: true instead.

Semantic helpers

Method	Purpose
`userInput(input, metadata?)`	Records user input.
`decision(reasonOrDecision, options?)`	Records an agent decision.
`context(labelOrData, dataOrMetadata?, metadata?)`	Records retrieved or constructed context.
`memory(operation, data, metadata?)`	Records memory access.
`outcome(options)`	Records an explicit technical and business outcome. A root `run()` records a technical outcome automatically when omitted.
`setAttributes(attributes)`	Attaches attributes to later events in the current run.
`annotate(label, payload)`	Records a custom breadcrumb.
`log(label, payload)`	Records a custom context event.

LLM and tool helpers

Method	Purpose
`instrumentLLM(client, options?)`	Wraps an LLM client object.
`guardLLM(client, options?)`	Wraps an LLM client with local input, output, and streaming policy checks.
`instrumentTool(name, fn, metadata?)`	Wraps a tool function.
`firewallTool(name, fn, options?)`	Wraps a tool with local policy evaluation.

LLM options

Option	Description
`modelLabel`	Stable model or provider label used by events and issue grouping.
`reportFailures`	Reports instrumented LLM errors when issue reporting is enabled. Defaults to `true`.
`reportSlowResponses`	Reports consecutive slow LLM calls when issue reporting is enabled. Defaults to `true`.
`slowResponseThresholdMs`	Overrides the tracer-wide slow LLM threshold for this wrapper.

Tool metadata

Option	Description
`toolVersion`	Version label attached to tool events and issue evidence.
`sideEffect`	Whether the tool can change external state.
`riskLevel`	`LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`externalTarget`	Optional external system or target label.
`timeoutMs`	Optional async call timeout. It rejects the wrapper but does not cancel the underlying operation.
`reportFailures`	Reports thrown errors and configured timeouts when issue reporting is enabled. Defaults to `true`.

Delivery helpers

Method	Purpose
`flush()`	Sends queued events now.
`shutdown(options?)`	Clears timers and performs a best-effort final flush.
`getStatus()`	Returns telemetry, issue reporting, circuit breaker, and runtime configuration state.

`LynxPolicyError`

firewallTool() throws LynxPolicyError when a tool call is blocked.

import { LynxPolicyError } from "@lynxops/sdk";

if (error instanceof LynxPolicyError) {
  console.log(error.action);
  console.log(error.policyId);
  console.log(error.reason);
}

Configuration options

Option	Description
`clientId`	Required client or service identifier.
`endpoint`	Lynx API endpoint. Defaults to `https://api.lynxops.co`.
`workspaceId`	Default workspace ID attached to events.
`agentId`	Default agent ID attached to events.
`apiKey`	API key for event ingestion.
`appVersion`	Application version metadata.
`deploymentId`	Deployment ID metadata.
`environment`	Runtime environment metadata.
`policyVersion`	Default policy version metadata.
`sampleRate`	Sampling ratio from `0` to `1`.
`captureInput`	Whether input fields may be recorded.
`captureOutput`	Whether output fields may be recorded.
`captureMode`	`full`, `metadata-only`, or `smart`.
`maxPayloadLength`	Maximum string length kept in `smart` mode.
`runtimeConfig.enabled`	Loads managed prompts and policies before the first `run()`.
`runtimeConfig.refreshIntervalMs`	Background refresh interval. Defaults to 60 seconds.
`runtimeConfig.maxStaleAgeMs`	Maximum age of the last validated bundle. Defaults to 24 hours.
`runtimeConfig.requireSignature`	Rejects unsigned runtime bundles.
`runtimeConfig.requireTargetMatch`	Rejects an environment mismatch or unresolved Agent.
`runtimeConfig.cache.enabled`	Persists the last validated bundle. Defaults to `false`.
`runtimeConfig.cache.path`	Optional exact path for the `.lynxconf` cache.
`issueReporting.enabled`	Sends issue candidates for detected failures when `true`.
`issueReporting.reportRunFailures`	Reports root Run errors and explicit failed outcomes.
`issueReporting.reportLlmFailures`	Reports errors from instrumented LLM calls.
`issueReporting.slowLlmThresholdMs`	Slow LLM threshold. Defaults to 10 seconds; `0` disables it.
`issueReporting.slowLlmConsecutiveOccurrences`	Consecutive slow observations required. Defaults to `2`.
`issueReporting.recoverySuccessThreshold`	Healthy observations required before sending recovery.
`delivery.mode`	`BACKGROUND` or `BLOCKING`.
`delivery.timeoutMs`	Timeout for one delivery request.
`delivery.flushOnRunEnd`	Whether `run()` tries to flush after the callback finishes.
`delivery.flushIntervalMs`	Background flush interval.
`delivery.batchSize`	Event batch size.
`delivery.maxQueueSize`	Maximum queued event count in memory.
`delivery.overflowStrategy`	`DROP_OLDEST` or `DROP_NEWEST`.
`circuitBreaker.enabled`	Enables delivery circuit breaker protection.
`circuitBreaker.failureThreshold`	Consecutive failures before opening the breaker.
`circuitBreaker.cooldownMs`	Cooldown before another send attempt.

Getting started

TypeScript SDK

OpenAPI

API reference

`LynxTracer`

`lynx`

Run methods

`run(agentName, callback)`

`run(options, callback)`

Managed prompts

`getPrompt(id)`

`initialize()`

Semantic helpers

LLM and tool helpers

LLM options

Tool metadata

Delivery helpers

`LynxPolicyError`

Configuration options

​LynxTracer

​lynx

​Run methods

​run(agentName, callback)

​run(options, callback)

​Managed prompts

​getPrompt(id)

​initialize()

​Semantic helpers

​LLM and tool helpers

​LLM options

​Tool metadata

​Delivery helpers

​LynxPolicyError

​Configuration options

​Related pages

`LynxTracer`

`lynx`

Run methods

`run(agentName, callback)`

`run(options, callback)`

Managed prompts

`getPrompt(id)`

`initialize()`

Semantic helpers

LLM and tool helpers

LLM options

Tool metadata

Delivery helpers

`LynxPolicyError`

Configuration options

Related pages