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

# Claude Agent SDK Engine

> @obversa/engine-claude-agent-sdk: Claude through the Agent SDK, one fresh query() per request, with memory as a tool.

`@obversa/engine-claude-agent-sdk` runs requests through the Claude Agent
SDK: each request is a fresh SDK `query()` call, so every step starts with a
clean context. Use it instead of the [Claude CLI engine](/docs/packages/engine-claude-cli)
when you want Claude to reach a memory adapter as a tool, or when the SDK's
process model suits your host better.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @obversa/engine-claude-agent-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @obversa/engine-claude-agent-sdk
  ```
</CodeGroup>

Included in `@obversa/obversa`.

Each query runs [clean](#clean) by default: with your own login and the
repository's settings and instruction files, but without your own settings,
hooks, plugins, skills and MCP servers. Set `clean: false` to run it the way
Claude Code runs for you: the plugin then loads the setting sources Claude
Code loads (`user`, `project` and `local`). Either way it adds only what the
step needs.

## Requirements

* Claude Code signed in on the machine that runs the engine. The SDK uses
  its sign-in, and the plugin has no API key option.
* The plugin is tested with Claude Agent SDK 0.3.241, the version it
  depends on.

## Identity

The plugin reports `provider: 'anthropic'`, with the model family read from
the model name. It runs the model the request names, or `defaultModel` when
the request names none.

## Quickstart

Construct the engine with a default model:

```ts examples/engine-claude-agent-sdk-binding.ts {5-7} theme={null}
import type { Engine } from '@obversa/api';
import { AgentSdkEngine } from '@obversa/engine-claude-agent-sdk';

// The SDK engine has no `admit`: it reports its identity when it runs.
const engine: Engine = new AgentSdkEngine({
  defaultModel: 'claude-sonnet-4-5',
});

console.log(JSON.stringify({
  name: engine.name,
  admits: typeof engine.admit === 'function',
}, null, 2));
```

This engine has no `admit`, so it reports its identity when it runs, not
before; a plan that asks for engine checks treats it as `unsupported` and
says whether that blocks the run. Run it with
`npx tsx engine-claude-agent-sdk-binding.ts`:

```json Output theme={null}
{
  "name": "agent-sdk",
  "admits": false
}
```

Pass the engine to `run()` in `engines`, or bind it to a graph node.

## Give Claude memory

Pass any adapter that implements the `Memory` contract from `@obversa/api`
as the `memory` option, such as `openGitMemory` from
[Git Memory](/docs/packages/memory-git), and Claude reaches it as an MCP tool.
`AGENT_SDK_MEMORY_TOOL_DESCRIPTION` is the tool's description, and
`AGENT_SDK_MEMORY_INSTRUCTIONS` the warning that memory content is
untrusted data. `agentSdkMemoryAllowedTools` and `agentSdkMemoryToolResult`
are the pieces that wire the tool to a `Memory` adapter.

## Options

### `permissionMode`

`default`, `acceptEdits`, `bypassPermissions`, `plan`, `dontAsk` or `auto`.
In the `read` workspace mode Claude gets only the `Read`, `Grep` and `Glob`
tools the request names; in `none` it gets no tools. Both modes block
`Bash`, `Edit`, `Write`, the sub-agent tools and every MCP tool. With
`clean: false` the SDK also loads your own settings, and they can't restore
those tools. Your own hooks run too, though, and a hook can write files; a
clean run leaves your hooks out.

### `clean`

`true` loads only the repository's settings (`settingSources: ['project']`) and turns on `strictMcpConfig`. Your own settings, hooks,
plugins, skills, MCP servers and `~/.claude/CLAUDE.md` stay out. The
repository's settings and instruction files still apply, and the run keeps
your login.

Its row in the [engines table](/docs/packages/engines#the-engines): runs on your
setup, clean mode available, read-only held in clean mode. On your own
setup the model's tools stay read-only, but your own hooks still run and
can change files. Clean mode also leaves out the repository's own MCP
servers, because the switch that keeps yours out keeps every server out.

### The rest

| Field | Type | Default | Description |
| - | - | - | - |
| `defaultModel` | `string` | none | The model when the request names none. |
| `minToolIntervalMs` | `number` | none | A floor on the time between tool calls. |
| `memory` | `Memory` | none | The adapter Claude reaches as a tool. |
| `effort` | `string` | none | Passed as the SDK's `effort` option. A request's `effort` wins. See [Reasoning effort](/docs/packages/engines#reasoning-effort). |
| `clean` | `boolean` | [See the default](/docs/packages/engines#the-default) | On by default: your own setup stays out. `false` runs on your own setup. [`clean`](#clean). |

## Errors

* **`EngineError`** kinds as the [API](/docs/packages/api#errors) lists them.

## API

* **`AgentSdkEngine`**: the engine class. **`AgentSdkEngineOptions`**: its
  options. [Quickstart](#quickstart).
* **`agentSdkToolOptions`**, **`agentSdkPermissionOptions`**,
  **`agentSdkSystemPrompt`**: how a request becomes SDK options.
* **`agentSdkMemoryAllowedTools`**, **`agentSdkMemoryToolResult`**,
  **`AGENT_SDK_MEMORY_INSTRUCTIONS`**, **`AGENT_SDK_MEMORY_TOOL_DESCRIPTION`**:
  the memory tool. [Give Claude memory](#give-claude-memory).
* **`toolPacer`**: the pacing behind `minToolIntervalMs`.

## Next steps

* [Claude CLI Engine](/docs/packages/engine-claude-cli): the same sign-in through
  the CLI, with the seat helper for `workflow()`.
* [Git Memory](/docs/packages/memory-git): the adapter in the snippet above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.