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),
  { clientRunId: chatId },
);

Keep prompts and secrets out of clientRunId.

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(...). Use sovara_client.injectLessons(...) only when the application must place the managed lesson block itself.

await sovara_client.run("answer-question", async () => {
  const lessonContext = await sovara_client.injectLessons({ question });
  const prompt = lessonContext ? `${lessonContext}\n\n${question}` : question;
  return callModel(prompt);
});

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.

Inspect the result

sovara record -- npm run start
sovara probe <run-id>

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

Inspect the result

​Project-owned top-level runs

​Steps and explicit tracing

​Subruns

​Run metadata

​Lessons

​Logs and concurrency

​Inspect the result

Project-owned top-level runs

Steps and explicit tracing

Subruns

Run metadata

Lessons

Logs and concurrency

Inspect the result