--- title: "Claude Agent SDK provider" description: "Run agents through Anthropic's official Claude Agent SDK (Claude Code's harness) from inside Cerevisor." slug: guides/providers/claude-agent-sdk section: guides subsection: providers canonical_url: https://cerevisor.com/docs/guides/providers/claude-agent-sdk last_verified: 2026-05-18 last_verified_version: "1.2.0" updated_at: 2026-05-18T15:08:18.053416+00:00 --- ## What this provider is Cerevisor's **Claude Agent SDK** provider hands an entire agent run to Anthropic's official `@anthropic-ai/claude-agent-sdk` runtime in-process. This is the same agent loop that powers Claude Code. Unlike the native [Anthropic provider](./anthropic.md) (where Cerevisor owns the chat loop and you control every tool call), Claude Agent SDK is a **delegated-loop provider**: Cerevisor sets sandbox + approval policy up-front, then the SDK runs the loop on its own. You get Claude Code-style agent behavior (read, write, edit, bash, glob, grep tools out of the box) without leaving Cerevisor. Best fit for users who want Claude Code's agent UX inside a Cerevisor workflow. ## Setup You need an Anthropic API key from [console.anthropic.com](https://console.anthropic.com). 1. **Settings → Providers → + Add provider → Claude Code (Claude Agent SDK).** 2. Paste your API key into the **API key** field. 3. Click **Test connection.** Cerevisor verifies the SDK is installed and the key shape is valid. 4. Click **Save.** The key is stored in a **dedicated OS keychain slot**, distinct from the native Anthropic provider's slot. You can have both providers configured side by side with the same key without conflict. > **The SDK key is injected at runtime via the SDK's `env` option, not `process.env`.** This prevents the key from leaking to any child process Cerevisor spawns. ## Models The default is `claude-sonnet-4-6` (cost-effective production default for SDK runs). You can override it in the Library entry's **default model** field, or per-agent via **Agent Config → Provider override**. The model picker shows only one entry because the SDK chooses model details at query time based on the value you pass. To target a specific model, type its id (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001`, etc.) in the **default model** field or the agent's override. ## Cost Cerevisor records `usage` from the SDK's result message when present. The orchestrator's cost-projector returns 0 for Claude Agent SDK runs because the SDK chooses turn counts dynamically; you cannot pre-estimate cost the way you can for native Anthropic. Costs appear in the audit log after the run completes, billed through your Anthropic account. ## v1.2.0 limitations The Claude Agent SDK provider intentionally trades some Cerevisor features for the SDK's full agent harness. In v1.2.0: - **No mid-run conversation continuation.** Contract-retry and verifier-retry don't fire for SDK runs. - **No subagent spawning.** Agent depth must be 0 (the SDK has its own subagent model, separate from Cerevisor's). - **No skill injection.** The SDK's harness owns its own skill discovery (it reads `.claude/skills/` directly). Cerevisor-assigned skills are not passed in. - **No per-tool PermissionModal.** Permission policy is set up-front via the SDK's `permissionMode`. Cerevisor's PermissionModal cannot interpose mid-run. These limitations mirror the [Codex CLI](./openai-codex-cli.md) and [Cursor Agent](./cursor-agent.md) providers; all three are delegated-loop providers and share the same constraint shape. ## Permission policy mapping Cerevisor's `WorkflowPermissions` policy maps onto the SDK's `permissionMode` as follows: | Cerevisor policy | SDK permissionMode | Behavior | |---|---|---| | Both file creation AND modification allowed | `acceptEdits` | SDK accepts file edits without prompting. | | Neither allowed | `plan` | SDK runs read-only (no writes). | | Mixed (one but not the other) | `default` | SDK prompts for approval, which Cerevisor cannot answer mid-run, so writes are effectively blocked. | If you want full read-write behavior inside an SDK run, set the workflow's permissions to allow both creation AND modification. The mixed setting is a known awkward case; configure permissions consistently per workflow to avoid it. ## Where SDK runs don't work Claude Agent SDK is **not a valid background-feature provider.** Chat builder, run retrospectives, meta-cognition enrichment, and skill summarization all need a direct chat surface, which the SDK doesn't expose. If your library default is Claude Agent SDK, those background features show an "unavailable" toast. Configure a separate provider (native Anthropic or Gemini work well) as the default for background features. See [Provider overview → Background features](./overview.md#what-background-features-use-the-default) for the full split. ## Common errors | Error | What it means | Fix | |---|---|---| | **`@anthropic-ai/claude-agent-sdk` is not installed** | The SDK is missing from this build. | Reinstall Cerevisor, or run `npm install @anthropic-ai/claude-agent-sdk` in your local dev build. | | **`Claude Agent SDK provider does not support direct chat() calls`** | An internal dispatch path missed the provider-type branch. | Report as a bug; this should never reach a user. | | **Tool calls execute but Cerevisor doesn't show them** | Expected. The SDK's harness handles tool calls internally; Cerevisor shows only the final assistant text. | Check the audit log for the full transcript if you need to see the tool sequence. | ## Where to go next - [Anthropic provider](./anthropic.md): use Claude directly through Cerevisor's own agent loop with full skill injection and per-tool permission prompts. - [Per-agent provider overrides](./per-agent-overrides.md): mix Claude Agent SDK agents with other providers in one workflow.