Claude Agent SDK provider

Run agents through Anthropic's official Claude Agent SDK (Claude Code's harness) from inside Cerevisor.

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 engine that powers Claude Code.

Unlike the native Anthropic provider (where Cerevisor runs the agent itself and you can approve every tool call as it happens), here Claude Code runs the work in its own engine while Cerevisor supervises: you set the rules up front, then the SDK works on its own from start to finish. 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 can sign in two ways — pick whichever matches how you already pay for Claude. The choice is a toggle at the top of the provider's setup screen (How do you want to sign in?), and you can change it later by editing the provider.

Option A — Anthropic API key (billed per token)

You need an Anthropic API key from console.anthropic.com.

  1. Settings → Providers → + Add provider → Claude Code (Claude Agent SDK).
  2. Leave the sign-in toggle on Anthropic API key.
  3. Paste your API key into the API key field.
  4. Click Test connection. Cerevisor verifies the SDK is installed and the key authenticates.
  5. 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.

Option B — Your Claude Pro/Max subscription (no API key)

If you already pay for Claude Pro or Max, you can power agent runs from that subscription's quota instead of buying API credits — the same way the Codex CLI provider uses a ChatGPT subscription.

  1. Settings → Providers → + Add provider → Claude Code (Claude Agent SDK).
  2. Switch the sign-in toggle to Claude subscription.
  3. Get a token: in a terminal, run claude setup-token (requires Claude Code installed and a Pro/Max plan). Paste the token into the Setup token field. - Already signed in to Claude Code on this machine? Leave the token field blank — Cerevisor will reuse that existing claude login. The setup screen tells you when it detects one.
  4. Click Test connection. Cerevisor runs a one-turn smoke test through the SDK to confirm the subscription works.
  5. Click Save.

Heads-up: subscriptions have usage limits. Pro/Max plans cap usage over rolling windows. Because a Cerevisor workflow can fan out many agents per run, a heavy run can hit that cap and throttle — where an API key would simply keep going (and keep billing). Use the subscription for everyday runs; reach for an API key (Option A, or the native Anthropic provider) when you need to run large workflows without interruption.

Your credential is injected at runtime via the SDK's env option, not process.env. In subscription mode Cerevisor also strips any ANTHROPIC_API_KEY from that env so a stray key can't silently override your subscription and bill API credits instead.

Models

The default is claude-sonnet-5 (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.

In API-key mode the model dropdown is pulled live from your account. In subscription mode there's no key to list the catalog with, so Cerevisor offers a short curated list (claude-sonnet-5, claude-opus-5, claude-fable-5, claude-opus-4-8, claude-haiku-4-5) — you can also just type any model id. To target a specific model, type its id in the default model field or the agent's override.

Cost

In API-key mode, Cerevisor records usage from the SDK's result message and the run's cost is billed through your Anthropic account; the cost-projector still returns 0 up front because the SDK chooses turn counts dynamically.

In subscription mode, runs are quota-billed against your Pro/Max plan, so Cerevisor reports the cost as $0 and analytics tags the session as Subscription (the same treatment as Codex CLI). The SDK may report a list-price figure internally, but it isn't real per-token spend, so Cerevisor deliberately doesn't surface it.

Current limitations

The Claude Agent SDK provider intentionally trades some Cerevisor features for the SDK's full agent engine:

  • 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 engine owns its own skill discovery (it reads .claude/skills/ directly). Cerevisor-assigned skills are not passed in.
  • No interactive permission prompts. Every tool call is still checked against your workflow permissions (see below), but there is no mid-run "Allow this?" dialog: a tool your policy blocks is denied outright.

These limitations mirror the Codex CLI and Cursor Agent providers, which share the same shape: the external tool runs the work while Cerevisor supervises.

How your workflow permissions apply

Cerevisor gates each tool call the SDK makes, live, against the same workflow permissions the native providers enforce — with no interactive prompt:

Tool the SDK wants What Cerevisor checks
Bash The actual command is evaluated: shell execution must be allowed, and the command must pass the same git / package-install / destructive-command rules as native runs.
Write (new files) Allow file creation.
Edit / MultiEdit / NotebookEdit Allow file modification.
WebFetch / WebSearch Allow web access.
Read / Glob / Grep and other read-only tools Always allowed.

A blocked call is denied with a message explaining which permission blocked it, and the agent continues with that knowledge. Runs are also capped at 50 turns so a stuck agent can't burn your quota unattended.

Chatting with a finished agent

Workflow runs persist their SDK session, so after a run completes you can chat with the agent to revise its output — the conversation resumes with full context of what it did. (Claude Code keeps this session history on your disk, outside Cerevisor; the provider card notes this too.)

Background features on this provider

Claude Agent SDK has no plain streaming chat, but background features (run retrospectives, meta-cognition enrichment, skill summarization, memory crystallization) still work when it's your default: each call runs as one small agent task on your Claude credential. If a call fails at runtime (not signed in, quota exhausted), Cerevisor automatically retries it on another chat-capable credential in your library, and any fallback spend shows in Analytics → Models.

See Provider overview → Background features for the full split.

Chat builder on a subscription

The chat builder is a special case. By default it also needs a chat-capable provider, and when your provider can't chat it offers an inline panel to point the builder at a separate chat-capable credential (the most reliable path).

But you can run the chat builder directly on Claude Code (including subscription auth), Codex, or Cursor: turn on Settings → Chat Builder → "Build with a subscription provider." With it on, each builder message runs as a single agent task that inspects your project (read-only) and emits the workflow changes, which Cerevisor applies exactly as a normal build. Trade-offs:

  • Slower and less precise. There's no forced tool schema — the model is asked to emit structured changes, so complex multi-step builds occasionally need a follow-up message. A chat-capable provider is still the smoother experience.
  • Uses your subscription quota. Every builder message is a full agent run.
  • Read-only. The builder can read your project for context but never modifies files while building.

Off by default — when off, you get the inline "pick a builder provider" panel instead.

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.
Subscription test fails / "Claude subscription test failed" No valid Pro/Max credential was found. On a Pro/Max plan, run claude setup-token and paste the token, or run claude login first and leave the token field blank. A free Claude account has no agent quota and won't work.
Runs work but show a cost in API-key mode you didn't expect You're in API-key mode (the default), billing per token. Edit the provider and switch the sign-in toggle to Claude subscription to bill against your Pro/Max plan instead.
A tool call fails with "Blocked by Cerevisor workflow permissions" Expected. Your workflow's permissions block that tool (see "How your workflow permissions apply" above). Loosen the relevant permission on the workflow if the agent genuinely needs it.

Where to go next

Back to docs