> For the complete documentation index, see [llms.txt](https://docs.zenml.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenml.io/kitaru/get-help/sdks.md).

# How to use the SDK

Kitaru has two SDKs, and both talk to the same server over the same REST API: the typed async **Python client** that ships in the `kitaru` package, and the framework-neutral **TypeScript client** `@zenml-io/kitaru`. Everything the CLI and the UI do is available from either. The `kitaru` command itself ships with the Python package; there is no separate TypeScript CLI.

## The Python SDK

The plain `kitaru` package is the SDK alone: the async client and the API models, which is all a production service needs to record sessions. The [CLI, worker, and server extras](/kitaru/getting-started/installation.md) layer on top of it.

```python
from kitaru.client import KitaruAPIClient

async with KitaruAPIClient() as client:
    session = await client.sessions.get(session_id)
    print(session.status, session.cost)
```

`KitaruAPIClient()` resolves its connection on its own: the server URL from `KITARU_API_URL`, falling back to the URL stored by `kitaru login` (no URL anywhere is an error); the credential from the task token a worker injects (`KITARU_API_TOKEN`), then `KITARU_API_KEY`, then the stored `kitaru login` credential. [Configuration](/kitaru/get-help/configuration.md) covers the full resolution order, and [Authentication & API keys](/kitaru/running-in-production/authentication.md) covers how keys are issued.

The client reaches everything, including single-session replay creation and blob upload, which the MCP server deliberately leaves out. The concept pages show it in context: [replay a session](/kitaru/core-concepts/replay.md), [build a cohort](/kitaru/core-concepts/cohorts.md), [start an experiment run](/kitaru/core-concepts/experiments.md).

## The TypeScript SDK

`@zenml-io/kitaru` creates and inspects Kitaru resources, records sessions, submits evaluations and experiments, and waits for exact jobs. The [Mastra](/kitaru/adapters/mastra.md) and [Vercel AI SDK](/kitaru/adapters/vercel-ai.md) adapters build on it.

{% hint style="info" %}
The TypeScript packages require Node `>=22.22.0 <23` and are versioned and released together. Install with `pnpm add @zenml-io/kitaru`; see [Installation](/kitaru/getting-started/installation.md).
{% endhint %}

### Reuse a developer login

First select a server with the CLI:

```bash
kitaru login https://kitaru.your-team.example
```

Then create a Node client without exporting its token:

```ts
import { createKitaruClient } from "@zenml-io/kitaru/node";

const client = await createKitaruClient();
const account = await client.accounts.getCurrent();
console.log(account.id);
```

The Node entry reads the Python CLI's selected server and stored credential. It binds the credential to that exact server, renews an expired renewable login in memory, and never rewrites the CLI store. Explicit `apiUrl`, `apiKey`, or `credentialProvider` options override stored selection. `KITARU_API_TOKEN` takes precedence over `KITARU_API_KEY` when no credential option is supplied.

The Node entry accepts HTTPS servers and cleartext HTTP only on loopback addresses, even if the Python CLI has stored another HTTP URL. If you run `kitaru login` again while a Node client is active, create a new client afterward. An existing client fails closed when the stored identity changes instead of silently adopting the replacement login.

Importing `@zenml-io/kitaru` or `@zenml-io/kitaru/client` never reads CLI files. Use those runtime-neutral entries in browsers, edge runtimes, and processes that receive credentials explicitly.

### Use explicit process credentials

CI, deployed applications, and long-running workers should use a dedicated API key or the task token injected by a Kitaru worker:

```ts
import { KitaruClient } from "@zenml-io/kitaru";

const client = new KitaruClient({
  apiUrl: process.env.KITARU_API_URL,
  apiKey: process.env.KITARU_API_TOKEN ?? process.env.KITARU_API_KEY,
});
```

Do not copy a developer's stored login into a container or CI secret. Create a separate process credential so it can be rotated and revoked independently.

### Resource namespaces

| Namespace                       | Operations                                                                    |
| ------------------------------- | ----------------------------------------------------------------------------- |
| `accounts`, `info`              | Read the current account and server information                               |
| `agents`                        | Create, read, list, update, and delete agents and agent versions              |
| `sessions`                      | Create, read, list, update, and delete sessions; read full sessions and nodes |
| `sessionRuns`                   | Submit a registered agent version as a job                                    |
| `blobs`                         | Upload, read, download, and delete evaluator or plugin source                 |
| `investigations`, `annotations` | Build and complete reviewed evidence                                          |
| `evaluators`, `evaluations`     | Register evaluator versions, submit evaluations, and inspect results          |
| `cohorts`, `cohortVersions`     | Define versioned session sets                                                 |
| `experiments`, `experimentRuns` | Create experiments, start runs, inspect child jobs, wait, cancel, and delete  |
| `jobs`                          | List, inspect, wait for, cancel, and delete jobs; inspect their tasks         |
| `tasks`                         | Inspect task status and execution specifications for recovery                 |
| `replays`                       | Create, inspect, list, wait for, and resolve recorded tool results            |

List methods accept cursor pagination and JSON filters. Matching `iter()` methods, including specialized methods such as `iterVersions()` and `iterNodes()`, follow opaque cursors without mutating the caller's parameters.

### Wait and cancellation behavior

`jobs.wait(id)`, `experimentRuns.wait(id)`, and `replays.wait(id)` poll only the supplied ID. They return completed, failed, and canceled terminal responses instead of converting remote failure states into transport errors. A local timeout or `AbortSignal` stops polling only; the remote job continues.

Cancellation is a separate explicit call. `jobs.cancel(id)` and `experimentRuns.cancel(id)` send one request and do not blindly retry after response loss. A durable workflow should record the exact ID before cancellation, then read that ID to reconcile a timeout, conflict, or interrupted response. Replays have no cancel endpoint; cancel their `job_id` through `jobs`.

### Hand work to the existing CLI worker

Persist a submitted job ID before starting a worker, then scope the worker to that exact job:

```bash
kitaru worker start --job-id "$JOB_ID" --concurrency 1 --timeout 1800
```

An exact-job worker will not claim unrelated work. This is claim filtering, not a global reservation: another already-running broad worker can still claim the job first. On a shared server, stop broad workers or give them an appropriate server-side scope before submitting a workflow that requires a particular runtime or working directory.

The canonical TypeScript and Mastra examples keep a local manifest, commit remote IDs before handing them to a worker, and distinguish `awaiting_worker`, failed, and ambiguous recovery states. Those manifests are example workflow code, not automatic behavior in the client.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zenml.io/kitaru/get-help/sdks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.