Use the SDK

Project-owned top-level runs

Create one SovaraClient for a stable project name. Use one top-level run for one user request, conversation turn, eval sample, batch job, or other execution you want to inspect.

const sovara_client = new SovaraClient({ projectName: "support-agent" });

await sovara_client.run("research-and-answer", () => runAgent());

The client ensures the exec server is reachable, registers the run, executes the callback in an AsyncLocalStorage scope, and finalizes the run in finally. For a durable conversation or job, pass an application-owned correlation ID. Reusing it within the same project appends to the canonical Sovara run.

await sovara_client.run(
  "support chat",
  () => agent.reply(message),
  { runKey: chatId },
);

Keep prompts and secrets out of runKey. clientRunId remains accepted as a deprecated alias during the compatibility period. The returned runId is Sovara’s durable canonical UUID.

Steps and explicit tracing

Supported provider, framework tool, and MCP calls inside a run become ordered steps. Wrap an important uncaptured application boundary with trace:

const lookupCustomer = trace(async function lookupCustomer(customerId: string) {
  return crm.lookup(customerId);
});

Prefer shared tool or dispatch chokepoints. A trace filled with miscellaneous helper calls is harder to understand than one that exposes agent decisions and actions.

Subruns

Use sovara_client.subrun(...) for child agents, delegated branches, parallel work, and coherent multi-step phases:

await sovara_client.run("finance-eval", () =>
  sovara_client.subrun("sample-42", () => runOneSample("sample-42")),
);

Nested top-level runs are ignored with a warning. Use a subrun when child work should appear in the run tree.

Run metadata

await sovara_client.run("answer-question", async () => {
  await sovara_client.logInput(question);
  const answer = await agent(question);
  await sovara_client.logOutput(answer);
  await sovara_client.logMetrics({ answered: true, latencyBudgetMs: 2500 });
});

Metrics accept booleans, integers, and finite numbers.

Lessons

Automatic lesson injection is project-wide by default for supported model calls. Narrow retrieval with the run’s lessonScope option:

await sovara_client.run(
  "answer-question",
  () => callModel(question),
  { lessonScope: "support/refunds/" },
);

Temporarily replace the active scope with sovara_client.lessonScope(...). Sovara retrieves lessons independently for each supported model call and adds a supplementary user message only to the copied request sent to the provider. It does not change the conversation objects owned by your app.

Logs and concurrency

Log capture is enabled by default. Pass { captureLogs: false } as the third argument to run() for concurrent top-level runs to avoid mixing process output.

Run the application

Run the application normally. The SDK records the run:

npm run start

Open Sovara to inspect the recorded run. Use the API reference for exact signatures.

Get started

Reference

Use the SDK

Project-owned top-level runs

Steps and explicit tracing

Subruns

Run metadata

Lessons

Logs and concurrency

Run the application

​Project-owned top-level runs

​Steps and explicit tracing

​Subruns

​Run metadata

​Lessons

​Logs and concurrency

​Run the application

Project-owned top-level runs

Steps and explicit tracing

Subruns

Run metadata

Lessons

Logs and concurrency

Run the application