Claude Agent SDK & Headless Agents

TL;DR: The Claude Agent SDK (renamed from Claude Code SDK) gives you Claude’s full agentic loop—built-in tools, subagents, hooks, MCP, sessions—as a Python or TypeScript library running in your own process [1]. Use claude -p for one-shot CLI tasks; use query() for programmatic control with structured output. Starting June 15, 2026, all headless/SDK usage draws from a separate monthly credit ($20–$200 by plan), separate from interactive limits [13].

What it is

Renamed from “Claude Code SDK” in late 2025, the Agent SDK packages the same engine as Claude Code ⭐ 130k (Jun 2026) as an embeddable library [15]. The fundamental design principle: Gather Context → Take Action → Verify Work → Repeat — the same loop an expert programmer follows, delegated to Claude [2].

The key distinction from the Anthropic Client SDK: the Client SDK hands you raw message objects and requires you to implement the tool loop; the Agent SDK handles that loop autonomously [1].

# Client SDK: you implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

Installation

pip install claude-agent-sdk          # Python 3.10+
npm install @anthropic-ai/claude-agent-sdk   # bundles native binary; no separate Claude Code install

Set ANTHROPIC_API_KEY (or configure Bedrock/Vertex/Foundry env vars). Third-party cloud provider support: set CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1, or CLAUDE_CODE_USE_FOUNDRY=1 with the respective provider credentials [1].

• anthropics/claude-agent-sdk-python ⭐ 7.2k [3]
• anthropics/claude-agent-sdk-typescript ⭐ 1.5k [4]

Headless CLI: claude -p

The -p / --print flag makes Claude Code non-interactive — one turn, stdout output, exits [5].

# Basic question
claude -p "What does the auth module do?"

# Pipe data in, redirect out (stdin capped at 10MB as of v2.1.128)
cat build-error.txt | claude -p 'explain the root cause concisely' > output.txt

# Structured JSON output with schema enforcement
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

# CI-safe: bare mode, no config discovery, no permission prompts
claude --bare -p "Run tests and summarize failures" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

# Stream tokens in real time (NDJSON)
claude -p "Write a migration plan" --output-format stream-json \
  --verbose --include-partial-messages \
  | jq -rj 'select(.type=="stream_event" and .event.delta.type?=="text_delta") | .event.delta.text'

Key flags [5]:

⚠ --bare will become the default for -p in a future release. Without it, a hook in any contributor’s ~/.claude or an MCP server in .mcp.json will silently execute in your CI [5].

Programmatic: query()

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  if ("result" in message) console.log(message.result);
}

query() yields typed message objects. The final ResultMessage carries result, session_id, total_cost_usd, and subtype (success / error_max_turns / error_max_budget_usd). For multi-turn conversations, use Python’s ClaudeSDKClient (tracks session state automatically across client.query() calls) or TypeScript’s continue: true option [12].

Built-in tools

No tool execution code required — these ship with the SDK [1]:

Subagents

Subagents run in fresh context windows, isolating intermediate work from the parent and enabling parallelism [6]:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="Use for quality, security, and maintainability reviews.",
            prompt="You are a code review specialist. Find security vulnerabilities and quality issues.",
            tools=["Read", "Grep", "Glob"],  # read-only restriction
            model="opus",                    # per-agent model override
        ),
        "test-runner": AgentDefinition(
            description="Use for test execution and coverage analysis.",
            prompt="Run tests and summarize failures concisely.",
            tools=["Bash", "Read", "Grep"],
            background=True,                 # non-blocking: parent continues immediately
        ),
    },
)

The description field drives automatic invocation — Claude selects subagents based on it. Mention a subagent by name in the prompt to force invocation. Critical constraint: subagents cannot spawn their own subagents — don’t include Agent in a subagent’s tools list [6].

AgentDefinition fields of note:

Common tool combinations [6]:

Reference implementations in anthropics/claude-agent-sdk-demos ⭐ 2.5k: multi-agent research system, branding assistant, spreadsheet agent, resume generator [7].

Dynamic Workflows

For jobs coordinating dozens to hundreds of agents (codebase audits, large migrations, cross-checked research), the Workflow tool moves orchestration into a JavaScript script the runtime executes outside the conversation context [8]:

export const meta = {
  name: "api-auth-audit",
  description: "Audit every API endpoint for missing auth checks",
  phases: [{ title: "Scan" }, { title: "Verify" }],
};

const FINDING = { type: "object", properties: {
  endpoint: { type: "string" },
  missing_auth: { type: "boolean" },
  details: { type: "string" }
}, required: ["endpoint", "missing_auth"] };

phase("Scan");
const findings = await pipeline(
  endpoints,   // list discovered earlier
  e => agent(`Check ${e} for missing authentication`, { phase: "Scan", schema: FINDING }),
  f => f?.missing_auth
    ? agent(`Adversarially verify: is ${f.endpoint} really unprotected?`, {
        phase: "Verify", label: `verify:${f.endpoint}`
      })
    : null
);
return findings.filter(Boolean);

Script primitives [8]:

Runtime constraints: up to 16 concurrent agents (fewer on limited-CPU machines), 1,000 agents total per run, runs are resumable within the same session [8].

Trigger methods: include ultracode keyword in your prompt, say “use a workflow” / “run a workflow” in your own words, or set /effort ultracode for automatic workflow planning across the session [18]. Workflow is available in TypeScript Agent SDK v0.3.149+; include it in allowedTools to auto-approve.

Hooks

Hooks are callback functions registered on agent events — block, modify, audit, or react without changing application logic [9]:

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.endswith(".env"):
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Cannot modify .env files",
        }}
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Available hooks [9]:

Multiple PreToolUse hooks run in parallel; deny wins over all other decisions [9]. Return {} to allow without change. Return {async_: True, asyncTimeout: 30000} (Python) / {async: true} (TypeScript) for fire-and-forget side effects (logging, webhooks) where the hook must not block the agent.

Matchers: exact tool name ("Write"), pipe-separated list ("Write|Edit"), regex ("^mcp__" matches all MCP tools), or omitted (matches all events of that type).

Sessions

Sessions persist to ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Three continuation modes [12]:

Sessions store conversation history only — not filesystem state. For filesystem snapshots, use file checkpointing. To resume across machines (CI workers, containers), either ship the JSONL file to the same cwd-encoded path or extract the relevant results into the next prompt explicitly [12].

TypeScript-only: persistSession: false keeps the session in memory only — useful for stateless single-turn tasks that should leave no disk artifacts.

MCP Integration

Connect to external systems without custom auth or API management [1]:

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]},
        "github":     {"command": "npx", "args": ["@modelcontextprotocol/server-github"]},
    }
)

The MCP servers registry ⭐ 87k covers databases, browsers, Slack, GitHub, Asana, and hundreds more [16]. MCP tools are named mcp__<server>__<action> and can be targeted in hooks with the ^mcp__ regex matcher. Subagents can receive per-agent MCP server subsets via AgentDefinition.mcpServers.

GitHub Actions

anthropics/claude-code-action ⭐ 7.8k powers @claude mentions in PR/issue comments and scheduled automation [11] [14]:

# .github/workflows/claude.yml
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: $
    prompt: "Review for security vulnerabilities"
    claude_args: "--max-turns 10 --model claude-opus-4-8"

All CLI flags pass via claude_args. Enterprise cloud: set use_bedrock: "true" + AWS OIDC, or use_vertex: "true" + GCP Workload Identity Federation for data-residency compliance [11]. GitHub Actions usage counts against the Agent SDK monthly credit (see Billing below).

Quick setup: run /install-github-app in Claude Code to configure the GitHub App and repository secrets automatically.

SDK vs CLI vs Managed Agents

The typical progression: prototype with query() locally → automate via claude -p in CI → move long-running async sessions to Managed Agents when you don’t want to operate sandbox infrastructure [10].

Billing — June 15, 2026

Starting June 15, 2026, headless/SDK usage separates from interactive usage into a dedicated monthly credit [13]:

Counts against credit: query() API, claude -p, GitHub Actions integration, third-party apps authenticating via Agent SDK.

Does not count: Interactive Claude Code (TUI/IDE extensions), web/desktop/mobile chat.

Credits are per-user, refresh monthly, don’t carry over. When exhausted, usage flows to API-rate usage credits at standard token rates. Interactive usage limits are unchanged.