Skip to content
Claude Code Docs Claude Code Docs

Agent SDK Overview

Claude Code Agent SDK

Section titled “Claude Code Agent SDK”

Reference for embedding Claude Code as a library via the Python or TypeScript Agent SDK. Covers the message protocol, control plane, session lifecycle, tool/hook/MCP bridging, and how the SDK diverges from the CLI.

Table of Contents

Section titled “Table of Contents”
  1. How the Agent SDK works
  2. Session lifecycle
  3. Message protocol
  4. Content block types
  5. Tool bridging
  6. Hook integration
  7. MCP integration
  8. Configuration
  9. Language bindings
  10. Streaming & events
  11. Permissions in SDK
  12. Session management functions
  13. Additional SDK subsystems (by file name, unverified without inspection)
  14. Discrepancies & notes

Overview

Section titled “Overview”

14 sections, 42 entries across message types, control messages, and subsystems.

#SectionDescriptionEntries
1How the Agent SDK worksTwo language bindings, entrypoint envs, data vs control plane, session identity, streaming, tool/hook/MCP bridging, permission callbacks.narrative
2Session lifecycleCreate, resume, abort, interrupt, set-mode — programmatic session control via the control-plane schema.6 entries
3Message protocolUser / assistant / result / system / status / partial / rate_limit / streamlined_text message types and their shapes.4 entries
4Content block typestext, thinking, tool_use, tool_result, image, document, redaction — the 7 content block kinds.narrative
5Tool bridgingBuilt-in tool inheritance, SDK-registered custom tools, in-process MCP servers, and the canUseTool callback.3 entries
6Hook integrationHow SDK-registered hooks reuse the same 26 event types as CLI hooks; callback shape.3 entries
7MCP integrationSdkControlTransport for in-process MCP servers, per-session config, CLAUDE_AGENT_SDK_MCP_NO_PREFIX.4 entries
8ConfigurationConstructor options, env vars (CLAUDE_AGENT_SDK_*, CLAUDE_CODE_ENTRYPOINT), and inherited settings.json keys.4 entries
9Language bindingsTypeScript (@anthropic-ai/claude-code) and Python (claude-code) — installation, minimal usage, key exports.2 entries
10Streaming & eventsEvent protocol surface — message chunks, tool use start/stop, thinking, compaction, task events.3 entries
11Permissions in SDKcanUseTool callback as the SDK’s rule-system replacement; mid-session mode changes via control message.3 entries
12Session management functionsProgrammatic entry points for session creation, resumption, abort, interrupt, and state queries.10 entries
13Additional SDK subsystems (by file name, unverified without inspection)Hedged references to internal files not inspected — sdkEventQueue, sdkProgress, sdkMessageAdapter, SdkControlTransport.narrative
14Discrepancies & notesType/schema mismatches, SDK-only features (rewind, mcp_set_servers), CLI-only features absent from SDK.narrative

Quick reference — SDK types

Section titled “Quick reference — SDK types”
TypeConcernShapeSource
SDKUserMessageUser inputtype: 'user', message (Anthropic SDK), content, parent_tool_use_id, session_idcoreSchemas.ts
SDKAssistantMessageAgent responsetype: 'assistant', message (Anthropic SDK), parent_tool_use_id, uuid, session_idcoreSchemas.ts
SDKResultMessage (success/error)Final outcometype: 'result', subtype, result or error, usage, uuid, session_idcoreSchemas.ts
SDKSystemMessageSession metadatatype: 'system', subtype: ‘init’, agents, api_key_source, mcp_serverscoreSchemas.ts
SDKStatusMessageProgress eventtype: 'status', status, uuid, session_idcoreSchemas.ts
SDKPartialAssistantMessageStreaming chunktype: 'partial_assistant', delta, uuid, session_idcoreSchemas.ts (when includePartialMessages: true)
SDKRateLimitEventRate limit changetype: 'rate_limit_event', rate_limit_info, uuid, session_idcoreSchemas.ts
SDKStreamlinedTextMessageCompacted texttype: 'streamlined_text', text summary, uuid, session_idcoreSchemas.ts
QueryAsync streamAsyncIterable, methods: interrupt(), rewindFiles(), setPermissionMode(), setModel(), supportedModels(), supportedAgents(), mcpServerStatus(), accountInfo()agentSdkTypes.ts
ClaudeSDKClientSession clientPersistent handle; methods: query(), receive_response(), interrupt(), setPermissionMode(), close()Python SDK
OptionsQuery configPartial type: model, tools, allowed_tools, disallowed_tools, permission_mode, hooks, agents, mcp_servers, thinking, max_turns, setting_sources, cwd, system_prompt, thinking, max_budget_usd, enable_file_checkpointingagentSdkTypes.ts
ClaudeAgentOptionsAgent configPython variant of Options; same fields, snake_case namingagentSdkTypes.ts
ThinkingConfigReasoning controltype: 'adaptive' | 'enabled' | 'disabled', optional budgetTokenscoreSchemas.ts
PermissionModeTool access'default' | 'dontAsk' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'auto'coreSchemas.ts
HookMatcherHook filtermatcher?: string, hooks: HookCallback[], timeout?: numbercontrolSchemas.ts
HookCallbackHook function(input: HookInput, toolUseID?: string, context?: { signal: AbortSignal }) => Promise<HookOutput>agentSdkTypes.ts

See Also

Section titled “See Also”