> 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/sdk-reference/kitaru/client.md).

# Python client

[Kitaru](https://docs.zenml.io/kitaru) is ZenML's sibling project for recording, replaying, and improving AI agents. The runs that happen in production become sessions you can replay against your real code. `KitaruAPIClient` is the async Python interface to a Kitaru server.

This page groups the client into thematic areas. For the complete, auto-generated API (every method and signature), see the [full Kitaru SDK reference](https://sdkdocs.kitaru.ai/reference/python/client/).

```python
from kitaru.client import KitaruAPIClient

async with KitaruAPIClient() as client:
    server = await client.info.get()
```

The client resolves its server URL from `KITARU_API_URL` or the server selected by `kitaru login`. It resolves credentials from the worker-provided `KITARU_API_TOKEN`, `KITARU_API_KEY`, or stored login credentials. If no server URL is configured, client creation fails instead of guessing a destination.

The client exposes its functionality through resource namespaces accessed as attributes.

## Sessions

`client.sessions` reads and writes the recordings:

* `list` / `iter` / `get` - find sessions, with filters for agent, tag, origin, and time
* `get_with_nodes` / `list_nodes` / `iter_nodes` - read the recorded model and tool calls, with payloads
* `create` / `ingest_nodes` - use the raw recording API that adapters build on
* `merge_evaluations` - attach externally produced evaluation results to a session
* `update` / `delete` - maintain recorded or imported sessions

## Replays and evaluations

* `client.replays` - create and inspect single-session replays: baseline session, optional override, tool policy, and evaluators
* `client.evaluations` - batch-evaluate stored sessions and read evaluation rows back

## Cohorts and experiments

* `client.cohorts` / `client.cohort_versions` - freeze immutable populations of sessions
* `client.experiments` - name a change and start it against a cohort version
* `client.experiment_runs` - inspect a run, its child jobs, and its cancellation state

## Registry

* `client.agents` / `client.agent_versions` - the agents sessions belong to, and the run commands replay executes
* `client.evaluators` / `client.importers` - versioned plugins registered from a script or package
* `client.imports` - import Langfuse, LangSmith, Braintrust, Logfire, or Kitaru JSONL traces as sessions

## Review

* `client.investigations` / `client.annotations` - structure human review as questions, evidence-linked answers, and session verdicts

## Execution and operations

* `client.session_runs` - submit a registered agent version as a job
* `client.workers` / `client.jobs` / `client.tasks` - register workers and inspect, cancel, or recover queued work
* `client.tags` - group sessions, versions, cohorts, and experiments
* `client.blobs` / `client.secrets` - store plugin source and runtime credentials

## Authentication

* `client.auth` / `client.devices` - authenticate interactive clients
* `client.api_keys` / `client.service_accounts` - issue and rotate process credentials
* `client.accounts` / `client.users` - inspect accounts and their users

***

For complete signatures and the full method list, see the [Python SDK reference](https://sdkdocs.kitaru.ai/reference/python/client/). For the command-line equivalents, see the [Kitaru CLI reference](https://sdkdocs.kitaru.ai/cli/). For the TypeScript client, see [How to use the SDK](https://docs.zenml.io/kitaru/get-help/sdks).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zenml.io/sdk-reference/kitaru/client.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.