SDK reference

Configuration

The full options object, accepted by both watch() and the client constructor.

Options

apiKeystringrequired

Your AgentWatch API key (aw_live_...). Read it from the environment — it grants write access to your project.

agentIdstringrequired

UUID of the agent registered in your project. Determines which baseline the trace is scored against.

agentInstructionsstring

The instructions or system behaviour the agent is expected to follow. Gives the correctness gate something to judge the output against beyond the input alone.

metadataRecord<string, string | number | boolean>default {}

Tags attached to every trace, e.g. { environment: 'production', version: '2.1.0' }.

maxPreviewLengthnumberdefault 5000

Maximum characters captured from input and output. Longer values are truncated, not rejected.

timeoutMsnumberdefault 5000

Telemetry request timeout. The attempt is abandoned after this; your agent is never waiting on it either way.

debugbooleandefault false

Logs what the SDK captured and whether delivery succeeded. Useful while wiring the integration up, noisy afterwards.

Agent instructions

agentInstructions tells AgentWatch what the agent was supposed to do. The correctness gate scores an output against the input; giving it the agent's brief as well is what separates “answered the question” from “answered the question the way this agent is meant to.”

support-agent.ts

const runAgent = watch(myAgentFn, {
  apiKey: process.env.AGENTWATCH_KEY!,
  agentId: process.env.AGENTWATCH_AGENT_ID!,
  agentInstructions: `
    You are a customer support agent.
    Answer using the company knowledge base.
    Never invent order information.
  `,
})

the brief the output is judged against

Send the real system prompt

The closer this is to the instructions the model actually receives, the more useful the score. A paraphrase written for the dashboard describes an agent you are not running.

Metadata

Tags travel with every trace the wrapper produces and become filters in the console. The pair worth setting on day one is environment and version — without them, a staging deploy's traces land in the same baseline as production, and a regression cannot be attributed to the release that caused it.

agent.ts

const runAgent = watch(myAgentFn, {
  apiKey: process.env.AGENTWATCH_KEY!,
  agentId: process.env.AGENTWATCH_AGENT_ID!,
  metadata: {
    environment: process.env.NODE_ENV ?? 'development',
    version: process.env.APP_VERSION ?? 'dev',
  },
})

Tag the release, not the request

Metadata is fixed per wrapper, so it is the right place for build-time facts — environment, version, region. Anything that varies per call belongs in the trace itself, via aw.trace().

Debug mode

Because delivery failures are swallowed, a misconfigured integration looks exactly like a working one from the outside. debug is the way to see inside it: the SDK reports what it captured and what happened to the request.

const runAgent = watch(myAgentFn, {
  apiKey: process.env.AGENTWATCH_KEY!,
  agentId: process.env.AGENTWATCH_AGENT_ID!,
  debug: true,
})

development only — leave it off in production

Turn it off before you ship

Debug output includes captured inputs and outputs. In production that is your users' data going to your logs, at the volume of every traced call.

Truncation

Input and output are cut at maxPreviewLength characters. The default of 5,000 is chosen to hold a full exchange while keeping payloads small.

Raising it helps when your agent returns long structured documents and the tail is where quality degrades.
Lowering it is the lever if you're passing large inputs you would rather not send off-box at full length.