API reference

`new SovaraClient(options)`

Creates a project-bound client. Project identity and connection configuration belong to the client, not to individual runs.

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

Option	Required	Purpose
`projectName`	Yes	Stable, immutable project name selected by SDK code.
`url`	No	Exec server URL; normally resolved from Sovara configuration.
`agentToken`	No	Project-scoped token for an agent host without a signed-in Sovara user. Defaults to `SOVARA_AGENT_TOKEN`.
`fetch`	No	Caller-owned `fetch` implementation used for lifecycle and runtime requests.

`sovara_client.run(name, fn, options?)`

Creates and finalizes a top-level run around a synchronous or asynchronous callback.

await sovara_client.run("agent-task", async () => runAgent());

Option	Purpose
`clientRunId`	Project-scoped application ID for appendable workflows.
`captureLogs`	Captures stdout/stderr unless set to `false`.
`lessonScope`	Folder path, path list, `null` for root/all, or `[]` to disable retrieval.

Returns Promise<T> for the callback result and rethrows callback errors after finalization. For a remote agent host, keep the token in its secret manager or an excluded .env file and configure the client once. A custom fetch is optional:

const sovara_client = new SovaraClient({
  projectName: "support-agent",
  url: "https://exec.example.com",
  agentToken: process.env.SOVARA_AGENT_TOKEN,
  fetch: customFetch, // Optional: proxy, custom CA, or other transport behavior.
});

await sovara_client.run("agent-task", async () => runAgent());

`sovara_client.subrun(name, fn, options?)`

Creates a child run under the active run. The optional lessonScope replaces the inherited lesson scope for that child.

await sovara_client.subrun("research", () => research(question));

Returns Promise<T> for the callback result and throws when no run is active.

`trace(fn, options?)`

Wraps a synchronous or asynchronous function as a step, recording arguments, return values, latency, status, and exceptions.

const lookupCustomer = trace(
  async function lookupCustomer(customerId: string) {
    return crm.get(customerId);
  },
  { name: "lookup_customer", meta: { system: "crm" } },
);

name defaults to the function or method name. meta adds step metadata. Stage 3 method-decorator use is also supported when the TypeScript compiler is configured for decorators.

`sovara_client.lessonScope(scope, fn)`

Temporarily replaces the active lesson scope. Paths include descendants; null or a root marker selects all lessons, and [] disables retrieval.

await sovara_client.lessonScope(["conventions/", "markets/"], runOneSample);

`sovara_client.injectLessons(context)`

Retrieves a prompt-ready lesson block for the active run. Returns Promise<string> and resolves to "" outside a run or when nothing matches.

`sovara_client.logInput(value)`

Stores the latest user-visible input on the active run. This value appears in the Input column of the Runs table and replaces the previously logged input. Objects and arrays are serialized as JSON.

await sovara_client.logInput({ question, customerId });

Returns Promise<void>. Outside an active run, it warns once and does nothing.

`sovara_client.logOutput(value)`

Stores the latest user-visible output on the active run. This value appears in the Output column of the Runs table and replaces the previously logged output. Objects and arrays are serialized as JSON.

await sovara_client.logOutput({ answer, sources });

Returns Promise<void>. Outside an active run, it warns once and does nothing.

`sovara_client.logMetrics(metrics)`

Adds filterable custom metrics to the active run. Values must be booleans or finite numbers; keys must be lower snake case and at most 32 characters.

await sovara_client.logMetrics({ answered: true, latency_ms: 842 });

Returns Promise<void>. Logging the same key again updates its latest value. Outside an active run, it warns once and does nothing.

`sovara_client.getRunId()`

Returns the current run or subrun ID as a string, or undefined when called outside an active run.

const runId = sovara_client.getRunId();

Get started

Use the SDK

Reference

`new SovaraClient(options)`

`sovara_client.run(name, fn, options?)`

`sovara_client.subrun(name, fn, options?)`

`trace(fn, options?)`

`sovara_client.lessonScope(scope, fn)`

`sovara_client.injectLessons(context)`

`sovara_client.logInput(value)`

`sovara_client.logOutput(value)`

`sovara_client.logMetrics(metrics)`

`sovara_client.getRunId()`

​new SovaraClient(options)

​sovara_client.run(name, fn, options?)

​sovara_client.subrun(name, fn, options?)

​trace(fn, options?)

​sovara_client.lessonScope(scope, fn)

​sovara_client.injectLessons(context)

​sovara_client.logInput(value)

​sovara_client.logOutput(value)

​sovara_client.logMetrics(metrics)

​sovara_client.getRunId()

`new SovaraClient(options)`

`sovara_client.run(name, fn, options?)`

`sovara_client.subrun(name, fn, options?)`

`trace(fn, options?)`

`sovara_client.lessonScope(scope, fn)`

`sovara_client.injectLessons(context)`

`sovara_client.logInput(value)`

`sovara_client.logOutput(value)`

`sovara_client.logMetrics(metrics)`

`sovara_client.getRunId()`