Wrap LLMs and tools

The SDK can wrap LLM clients and tool functions so each call appears as part of the session timeline.

When to use this

Use this page when you want to inspect:

Which model was called
What input and output were sent
How long the call took
Token usage and estimated cost when available
Which tool ran, with what arguments, and whether it failed

Wrap an LLM client

instrumentLLM() returns a proxy with the same public shape as the original client. Known generation methods are recorded automatically.

import OpenAI from "openai";

const openai = lynx.instrumentLLM(
  new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  }),
  {
    modelLabel: "openai",
  },
);

await lynx.run("SupportAgent", async () => {
  const response = await openai.chat.completions.create({
    model: "gpt-4.1-mini",
    messages: [{ role: "user", content: "Summarize this ticket" }],
  });

  lynx.decision("summarized ticket for support triage");
  return response;
});

Lynx records model metadata, input and output according to your capture settings, latency, token usage when available, span IDs, and errors. When issue reporting is enabled, an instrumented LLM error produces LLM_ERROR. Calls that cross the configured latency threshold produce LLM_SLOW_RESPONSE after two consecutive slow observations by default. Use reportFailures: false, reportSlowResponses: false, or a wrapper-specific slowResponseThresholdMs when a client has different expected behavior. For async iterable streaming APIs such as streamText, Lynx keeps the original iterator behavior and records the end of the LLM call only when iteration reaches completion. An error raised while consuming the stream is recorded on the same span. If a stream is created but never consumed, it has a start event without an end event.

Guard an LLM client

Use guardLLM() when managed policies must inspect model input and output in addition to recording the call.

const guardedOpenAI = lynx.guardLLM(openai, {
  modelLabel: "support-model",
  firewall: {
    input: {
      select: (request) => request.messages,
      riskLevel: "HIGH",
    },
    output: {
      select: (response) => response.output_text,
      riskLevel: "HIGH",
    },
  },
});

For async iterable streams, Lynx evaluates output before yielding each chunk. A bounded trailing text buffer detects policy matches split across adjacent chunks. If a policy blocks, iteration throws LynxPolicyError before the matching chunk is returned.

Wrap a tool

Use instrumentTool() when you want to record a tool call without adding a policy check.

const searchOrders = lynx.instrumentTool(
  "orders.search",
  async ({ userId }: { userId: string }) => {
    return db.orders.findMany({ where: { userId } });
  },
  {
    toolVersion: "2026-06-01",
    sideEffect: false,
    riskLevel: "LOW",
    timeoutMs: 5000,
  },
);

await lynx.run("SupportAgent", async () => {
  const orders = await searchOrders({ userId: "usr_123" });
  lynx.context("orders", orders);
});

Enable issue reporting on the tracer to turn supported failures into issue candidates.

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

The same setting also reports:

RUN_ERROR when the root run() callback throws and the failure is not already represented by a more specific Tool, LLM, or firewall detection
RUN_FAILED when outcome() explicitly records a failed technical or business result
LLM_ERROR for an instrumented LLM failure
LLM_SLOW_RESPONSE after the configured number of consecutive slow calls

A thrown tool error produces a TOOL_ERROR record. An asynchronous call that exceeds its configured timeoutMs produces TOOL_TIMEOUT. The server groups repeated records by stable tool and error metadata, without putting the raw error message in the fingerprint. Later successful calls produce a recovery record after the configured threshold. These records request asynchronous server review. They do not synchronously create or close a final Issue, and issue-record delivery does not replace normal application error handling. Use reportFailures: false when a tool’s errors are expected and fully handled by your application. A wrapper timeout cannot cancel the underlying operation, so use the tool’s own AbortSignal or cancellation API when side effects must stop after a timeout. Synchronous work cannot be interrupted by timeoutMs. Use firewallTool() instead when the tool needs a policy check before it runs.

Custom LLM clients

If your client uses custom method names, pass a custom rule.

const model = lynx.instrumentLLM(customClient, {
  modelLabel: "custom.llm",
  customRule: {
    isTargetMethod: (path) => path.join(".") === "responses.generate",
    extractInput: (args) => args[0],
    extractOutput: (result) => result.text,
    extractUsage: (result) => result.usage,
  },
});

What you can see in Lynx

After wrapping LLMs and tools, Lynx can show:

LLM calls in the session timeline
Tool calls and tool results
Failed or slow calls
Retry patterns and repeated call loops
Token usage, latency, and cost signals
Related session and trace links

Security note

LLM inputs, model outputs, tool arguments, and tool results may contain sensitive data. Use metadata-only, captureInput: false, captureOutput: false, or application-level redaction when needed.

Getting started

TypeScript SDK

OpenAPI

Wrap LLMs and tools

When to use this

Wrap an LLM client

Guard an LLM client

Wrap a tool

Custom LLM clients

What you can see in Lynx

Security note

Next steps

​When to use this

​Wrap an LLM client

​Guard an LLM client

​Wrap a tool

​Custom LLM clients

​What you can see in Lynx

​Security note

​Next steps

When to use this

Wrap an LLM client

Guard an LLM client

Wrap a tool

Custom LLM clients

What you can see in Lynx

Security note

Next steps