Claude Agent SDK provider

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 (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.

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 and Cursor Agent 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 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: use Claude directly through Cerevisor's own agent loop with full skill injection and per-tool permission prompts.
• Per-agent provider overrides: mix Claude Agent SDK agents with other providers in one workflow.