SDK reference

watch()

Wrap any async function and capture a trace on every call — fire-and-forget.

watch() returns a function with the same signature as the one you passed it. Callers cannot tell the difference: same arguments, same resolved value, same thrown errors.

agent.ts

import { watch } from '@agentwatch-beta/sdk'

const runAgent = watch(myAgentFn, {
  apiKey: 'aw_live_...',
  agentId: '<agent-uuid>',
})

const result = await runAgent(userQuery)

Signature

fn(...args) => Promise<T>required

The async function to trace. Its first argument becomes the trace input and its resolved value becomes the trace output.

optionsWatchOptionsrequired

At minimum apiKey and agentId; agentInstructions and metadata are the two most worth setting beyond them. See Configuration for the full set.

What is captured

The first argument is captured as the input and the return value as the output. Both are stringified and truncated to maxPreviewLength characters.

Only the first argument

If your function takes several parameters and the meaningful one is not first, either reorder them or reach for a manual trace, where you name the input explicitly.

If the return value is an OpenAI-compatible response, the model name, token counts, and tool names are extracted automatically — no extra wiring. See OpenAI-compatible providers.

Errors

When your function throws, the trace is captured with status error and the error is re-thrown unchanged. Your caller behaves exactly as it did before the wrapper existed — the same error object, with its stack intact, reaches the same catch.

const runAgent = watch(myAgentFn, { apiKey, agentId })

try {
  await runAgent(query)
} catch (err) {
  // the original error, unwrapped — the trace was recorded on the way through
}

failures are traced, then rethrown untouched

Latency

The wrapper measures around your function and returns as soon as it resolves. The trace is POSTed after that, outside the awaited path, so the request your caller is waiting on never waits on ours.

Delivery failures are swallowed — a network problem on our side is not your outage.
The request abandons itself after timeoutMs so a hung connection cannot pile up.

The reasoning behind both is on Guarantees.

Wrapping several functions

Passing the same apiKey and agentId to every watch() call gets repetitive. AgentWatchClient holds the config once and hands out wrappers.