Use the SDK

Project-owned top-level traces

Create one SovaraClient for a stable project name. Use one top-level trace for a workflow, evaluation sample, batch job, or durable conversation. A recording session appends work to that trace; a turn groups one interaction within it.

import { SovaraClient, trace } from "@sovara/runner";

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

await sovara_client.trace("research-and-answer", () => traceAgent());

For a durable conversation or job, pass your own stable identifier as traceId, or reuse the ID from getTraceId() in a previous SDK trace. Reuse either value to add steps to the same trace in that project.

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

Keep prompts and secrets out of traceId. trace() returns the callback result. To read the trace ID, call sovara_client.getTraceId() inside the callback while the trace is active. Pass that ID to the CLI, here as TRACE_ID:

sovara probe "$TRACE_ID"

Steps and explicit tracing

Supported provider, framework tool, and MCP calls inside a trace 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.

Subtraces

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

await sovara_client.trace("finance-eval", () =>
  sovara_client.subtrace("sample-42", () => traceOneSample("sample-42")),
);

Use subtrace() for child work. Nesting trace() does not create a child trace.

Trace metadata

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

Await logging calls inside the active trace. Input and output accept strings or JSON-serializable values; metrics accept booleans and finite numbers with lowercase names such as latency_ms. See the API reference for validation rules.

Evaluation samples

Pass an existing evaluation run ID with evalRunId to record a sample under it:

await sovara_client.trace("sample-42", () => traceOneSample("sample-42"), {
  evalRunId,
});

The evaluation must exist in the same project. To create evaluations and log aggregate results, use the Python evaluation workflow.

Lessons

When automatic injection is enabled and the required models are configured, supported model calls retrieve from the project’s production lessons. Unapplied proposals are not used. Narrow retrieval with the trace’s lessonScope option:

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

Temporarily replace the active scope with sovara_client.lessonScope(...) inside the trace. Use null for all folders or [] for no lessons:

await sovara_client.trace("answer-question", async () => {
  return await sovara_client.lessonScope([], () => callModel(question));
});

See runtime retrieval for project settings.

Logs and concurrency

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

Run the application

Run the application normally. The SDK records the trace:

npm run start

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

Explicit conversation turns

trace() opens a recording session without an implicit turn. turn(options, fn) declares a scoped interaction and returns the callback result. Work outside turn callbacks is still captured, with no turn membership.

await sovara_client.trace("conversation", async () => {
  await setup();
  await sovara_client.turn({ turnInput: "Hi." }, async () => respond());
  await sovara_client.turn({ turnInput: "Another question." }, async () => respond());
  await cleanup();
}, { traceId: "chat-123" });

For one recording per interaction, reuse the same traceId and declare each interaction explicitly:

for (const message of messages) {
  await sovara_client.trace("conversation", async () => {
    return await sovara_client.turn({ turnInput: message }, () => respond());
  }, { traceId: "chat-123" });
}

turnInput is an optional string for the interaction; logged input and output describe the whole trace. Do not nest turns in the same trace. Await tasks and consume streams before the outer callback returns.

Get started

Reference

Use the SDK

Project-owned top-level traces

Steps and explicit tracing

Subtraces

Trace metadata

Evaluation samples

Lessons

Logs and concurrency

Run the application

Explicit conversation turns

​Project-owned top-level traces

​Steps and explicit tracing

​Subtraces

​Trace metadata

​Evaluation samples

​Lessons

​Logs and concurrency

​Run the application

​Explicit conversation turns

Project-owned top-level traces

Steps and explicit tracing

Subtraces

Trace metadata

Evaluation samples

Lessons

Logs and concurrency

Run the application

Explicit conversation turns