> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the SDK

> Understand TypeScript project identity, runs, steps, subruns, metadata, and lessons.

<script src="/assets/sdk-nav.js" />

## 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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara record -- npm run start
sovara probe <run-id>
```

Use the [API reference](/sdks/typescript/api-reference) for exact signatures.