> 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/adapters/custom.md).

# No adapter for your framework

Kitaru ships adapters for a handful of frameworks. If yours isn't one of them you are not stuck, and you do not have to wait for us. There are three ways forward, and the right one depends on how much control you have over the agent's code.

| Your situation                                    | Do this                                                                    |
| ------------------------------------------------- | -------------------------------------------------------------------------- |
| You can wrap the agent, and want native recording | [Build a project-local adapter](#build-a-project-local-adapter)            |
| You already emit traces somewhere                 | [Import instead](/kitaru/guides/importing-sessions.md) — no adapter needed |
| You cannot or will not change the agent's code    | [Let Kitaru call your agent](#let-kitaru-call-your-agent)                  |

Importing is the cheapest of the three and the one to reach for first. An imported session replays and evaluates exactly like a recorded one, so "no adapter" costs you nothing except live recording — see [Import any trace format](/kitaru/guides/importing-sessions.md).

## Build a project-local adapter

An adapter is not a privileged plugin. It is ordinary code that calls the recording API, and it can live in your repository forever — there is no requirement to contribute it upstream.

The job of an adapter is narrow: observe the seams your framework already exposes, and write each model request and tool call as a node on a session. What makes an adapter *honest* is that it reports what it can and cannot see. A wrapper that silently misses nested tool calls is worse than one that declares the gap.

The fastest path is the `kitaru-adapter-builder` [agent skill](/kitaru/getting-started/skills.md), which is built for exactly this:

```bash
npx skills add zenml-io/kitaru-skills
```

Point your coding assistant at it and it will build the smallest adapter that works inside your project, in Python or TypeScript, and tell you what it observed and what it could not. It deliberately preserves your framework's public entrypoint rather than replacing it, and it finishes locally — nothing is registered until you approve it.

Two rules worth keeping whichever way you build it:

* **Wrap the public entrypoint, change nothing else.** The shipped adapters do not recompile graphs, replace checkpointers, or alter results. Yours should not either — a recording that changes behavior is not a recording.
* **Recording and replaying are one wrapper, not two.** The same code that records must apply the override at the model boundary and answer tool calls per the [tool policy](/kitaru/guides/tool-policies.md) during a replay. Splitting them is how baselines stop reproducing.

Read the [PydanticAI adapter](/kitaru/adapters/pydantic-ai.md) as the reference implementation, and the [LangGraph capability matrix](/kitaru/adapters/langgraph.md#capability-matrix) for how to express partial support honestly.

## Let Kitaru call your agent

Sometimes wrapping is not on the table. The agent runs inside a service you don't control, or in another language, or behind a queue. For that there is a third mode: register the agent version as a **function** and Kitaru asks *your* system to run it.

An agent version's run spec is one of two shapes. The familiar one is a command Kitaru executes on a worker:

```python
CommandRunSpec(command="python support.py", timeout_seconds=3600)
```

The other points at a Python function, as `module:attribute`:

```python
FunctionRunSpec(
    entrypoint="my_service.kitaru_hooks:run_replay",
    import_deadline_seconds=86400,
)
```

The flow is inverted, and that is the point:

1. Kitaru calls your function instead of running your agent itself.
2. Your function runs the agent however your system already runs it — your process, your language, your infrastructure.
3. It returns the **external id** of the session that run produced.
4. Kitaru creates a placeholder session in `pending_import` status against that id.
5. When you import the trace for that external id, it **adopts the placeholder**. Evaluations run against the imported content, and the replay and experiment settle as normal.

`import_deadline_seconds` bounds step 5. If no import arrives in time the replay fails rather than hanging forever — the default is 24 hours, which is generous because the import is usually a batch job on your side.

The trade-off is honest: you get replay and experiments with no adapter and no code change inside the agent, but the fidelity of the replay is the fidelity of whatever your system exports. Kitaru cannot substitute a tool result it was never shown.

## Which to choose

If you can wrap the agent, wrap it — native recording sees the most and needs the least from you. If you cannot, import; it is a first-class path and most of Kitaru works identically on imported sessions. Reach for function runs when the agent is genuinely out of reach and you still want its runs inside experiments.


---

# 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/adapters/custom.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.