DOCSEARCHbyAlgolia
Submit Docs

Claude Agent SDK Documentation

website·Indexed Apr 16, 2026

https://code.claude.com/docs/

Official documentation for the @anthropic-ai/claude-agent-sdk. Guides developers in building autonomous AI agents with features including the agent loop, custom tools via MCP, file checkpointing, hooks, permissions, and subagents. Covers session management, cost tracking, OpenTelemetry observability, structured outputs, and integration with Amazon Bedrock.

Tokens
386.1K
Snippets
1.8K
Records
2.5K
Agent score
50%

What's inside Claude Agent SDK

  1. Overview of Claude Code commands and how to invoke them

    Claude Code commands allow you to control the session directly from the chat interface. They enable quick actions such as switching models, managing permissions, clearing context, and running workflows. To view all available commands, type / in the chat. You can also filter the list by typing / followed by letters. Command availability depends on your platform, plan, and environment; for example, /desktop is only available on macOS and Windows, and /upgrade is restricted to Pro and Max plans. Commands are categorized as either built-in (coded into the CLI) or bundled skills (prompts handed to Claude that can be invoked automatically).

  2. Overview of Claude Code Routines and capabilities

    Routines automate work by running on schedules, API calls, or GitHub events from Anthropic-managed cloud infrastructure. A routine is a saved Claude Code configuration consisting of a prompt, one or more repositories, and a set of MCP connectors. Routines execute autonomously in the cloud, meaning they continue working even when your laptop is closed. They are available on Pro, Max, Team, and Enterprise plans with Claude Code on the web enabled. Routines are currently in research preview, so behavior, limits, and the API surface may change. Each routine belongs to your individual claude.ai account and counts against your account's daily run allowance. Actions taken by the routine (commits, PRs, messages) appear as your user identity.

  3. Intercept and control agent behavior with hooks

    Hooks are callback functions that run your code in response to agent events, allowing you to block dangerous operations, log tool calls, transform inputs/outputs, require human approval, or track session lifecycle. The execution flow is: 1) An event fires (e.g., tool call, session start). 2) The SDK collects registered hooks. 3) Matchers filter which hooks run based on the event target (e.g., tool name). 4) Matching callback functions execute, receiving input details. 5) The callback returns a decision object to allow, block, modify, or inject context.

  4. Push events into Claude Code sessions using Channels

    Channels allow MCP servers to push messages, alerts, and webhooks directly into a running Claude Code session. This enables Claude to react to external events (like CI results, chat messages, or monitoring alerts) while you are away from the terminal. Unlike integrations that spawn new cloud sessions, channels deliver events to your existing open session. Channels are two-way: Claude can read an event and reply back through the same channel. Events only arrive while the session is open, so for always-on setups, run Claude in a background process or persistent terminal.

    Prerequisites:

    • Claude Code v2.1.80 or later.
    • A claude.ai login (Console and API key authentication are not supported).
    • Bun installed (required for channel plugins).
    • For Team/Enterprise organizations, channels must be explicitly enabled by admins.

  5. Understand agent team architecture and storage

    An agent team consists of a Team lead (main session that coordinates), Teammates (separate instances working on tasks), a Task list (shared work items), and a Mailbox (messaging system). Teams and tasks are stored locally in ~/.claude/teams/{team-name}/config.json and ~/.claude/tasks/{team-name}/. The team config holds runtime state (session IDs, tmux pane IDs) and should never be edited by hand. Teammates can read the config to discover other members. There is no project-level equivalent; files like .claude/teams/teams.json in the project directory are treated as ordinary files.

  6. Fix orphaned tool_result errors during streaming

    Version 2.1.7 fixed orphaned tool_result errors when sibling tools fail during streaming execution. Version 2.1.9 also fixed long sessions with parallel tool calls failing with an API error about orphan tool_result blocks.

  7. Understand CLAUDE.md vs Auto Memory for persistent context

    Claude Code uses two complementary memory systems loaded at the start of every session to carry knowledge across sessions. CLAUDE.md files contain instructions you write to guide behavior (coding standards, workflows, architecture). Auto memory contains learnings and patterns Claude writes itself based on your corrections and preferences (build commands, debugging insights). CLAUDE.md is written by you and scoped to project/user/org; Auto memory is written by Claude and scoped to the working tree. Both are treated as context, not enforced configuration.

  8. Understand defense-in-depth with permissions and sandboxing

    Claude Code uses both permissions and sandboxing for defense-in-depth:

    • Permissions: Block Claude from attempting to access restricted resources (e.g., deny: Bash(*)).
    • Sandboxing: OS-level enforcement that restricts Bash commands' filesystem and network access, even if a prompt injection bypasses Claude's decision-making.

    Key interactions:

    • Filesystem restrictions in the sandbox use Read/Edit deny rules, not separate sandbox configuration.
    • Network restrictions combine WebFetch permission rules with the sandbox's allowedDomains list.
    • When sandboxing is enabled with autoAllowBashIfSandboxed: true (default), sandboxed Bash commands run without prompting even if permissions include ask: Bash(*). The sandbox boundary substitutes for the per-command prompt.

    To change sandbox behavior, see sandbox modes documentation.

  9. Compare channels with other Claude Code integration modes

    Channels enable MCP servers to push events (messages, alerts, webhooks) directly into an already-running local Claude Code session. This distinguishes them from other integration modes:

    • Claude Code on the web: Runs tasks in a fresh cloud sandbox cloned from GitHub. Best for delegating self-contained async work to check on later.
    • Claude in Slack: Spawns a web session from an @Claude mention in a Slack channel or thread. Best for starting tasks directly from team conversation context.
    • Standard MCP server: Claude queries the server during a task, but nothing is pushed to the session. Best for giving Claude on-demand access to read or query a system.
    • Remote Control: Allows you to drive your local session from claude.ai or the mobile app. Best for steering an in-progress session while away from your desk.

    Channels fill the gap by pushing events from non-Claude sources (like CI, error trackers, or chat apps) into your local session where Claude already has your files open and context.

  10. Secure cloud deployment architecture for AI agents

    For cloud deployments, combine isolation technologies with network controls: run agents in private subnets with no internet gateway, configure firewalls to block egress except to the proxy, and assign minimal IAM permissions. Use a proxy (e.g., Envoy with credential_injector) to validate requests, enforce allowlists, and inject credentials. Log all traffic at the proxy.

  11. Auto-approve permission prompts with PermissionRequest hooks

    Skip approval dialogs for tool calls you always allow. A PermissionRequest hook fires when Claude Code is about to show a permission dialog. Return {"behavior": "allow"} to answer on your behalf. The matcher scopes the hook to specific tool names like 'ExitPlanMode'. Keep the matcher narrow to avoid auto-approving all prompts.
    {
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

  12. Configure project context with CLAUDE.md

    Add a CLAUDE.md file to your project root to set coding standards, architecture decisions, preferred libraries, and review checklists. Claude Code reads this file at the start of every session. It also builds auto memory to save learnings like build commands and debugging insights across sessions.

    CLAUDE.md

    Project Standards

    • Use TypeScript strict mode
    • Prefer functional programming patterns

    Build Commands

    • dev: npm run dev
    • test: npm run test:coverage