Claude Agent SDK: Architecture and Capabilities for Production-Grade AI Agents

The article opens by contrasting trivial agent demos with production requirements: context overflow, tool misbehavior, permission violations, and missing domain knowledge. It positions the Claude Agent SDK as the library form of Claude Code, embedding Claude Code's toolset, agent loop, and context management into the developer's own process. Two key advantages are highlighted: the SDK evolves with the Claude product line, and it offers the deepest adaptation to Claude models while supporting other models via compatibility protocols.

Design Philosophy: Giving the Agent a Computer

The core design grants the model terminal access to a computer — file system as context source, Bash as universal execution tool. The agent runs a fixed four-step loop: gather context, take action, verify work, and repeat if necessary. The value lies in the control surfaces exposed around this loop.

Seven Open Capabilities Mapped to Production Problems

① Agent Loop and Execution Control

The SDK organizes a task into an observable message stream: initialization messages (available tools, MCP connection status), alternating assistant messages and tool results (streaming text and tool calls, multi-turn), and a final result message containing subtype, total cost, token usage, turn count, and session_id. Three key parameters govern execution: maxTurns (turn limit), maxBudgetUsd (cost ceiling including subagents), and effort (reasoning intensity tier). Practice advice: treat maxTurns and maxBudgetUsd as standard dual safeguards; use low effort for batch jobs; alert on result subtype, distinguishing over-turn from over-budget.

② Context Management

Long tasks trigger automatic compaction near the window limit. A PreCompact hook can persist critical state before compression. CLAUDE.md content survives compaction, acting as a "what to remember after compression" instruction slot. System Prompt has three origins: minimal default (tool-calling only), claude_code preset (full prompt, supports append, recommended for most cases), and custom string (full control, but safety and environment instructions must be supplied manually). Practice advice: persistent rules in CLAUDE.md, session-level directives via preset + append; full custom only when product shapes differ greatly; write intermediate conclusions to files instead of relying on context retention.

③ Tool System: Built-in, Custom, and MCP

Built-in tools cover file read/write/edit, Glob/Grep, Bash, WebSearch/WebFetch. Custom tools are defined via @tool / tool() with four elements: name, description, schema, handler; they are mounted as in-process MCP servers. External MCP systems connect via local process or HTTP; when tool count grows, ToolSearch loads schemas on demand, and readOnlyHint marks read-only tools for parallel execution. Practice advice: wrap human-facing data endpoints as Bash interfaces — models natively understand Bash semantics, avoiding per-query API specs; return readable errors via isError so the model can self-correct; allow MCP tools with wildcard allowedTools (e.g., mcp__server__*).

④ Permission Governance

Every tool call passes through a fixed evaluation chain, earlier stages intercept first: 1) Hooks (custom intercept, highest priority), 2) deny rules (explicit block), 3) ask rules (human confirmation), 4) permission mode ( default, dontAsk, acceptEdits, plan, auto, bypassPermissions), 5) allow rules (explicit allow), 6) canUseTool callback (final programmatic fallback). Rules support scope syntax: Bash(npm *) restricts command prefix, Edit(//secrets/**) anchors path. A lock-down combination is highlighted: allowedTools: ["Read", "Glob", "Grep"] + permissionMode: "dontAsk". Practice advice: use the lock-down combo for sandboxed exploration; authorize write operations by path, not blanket allow; note allowedTools does not constrain bypassPermissions, which is reserved for trusted environments.

⑤ Hooks: Intercept, Rewrite, Audit

Hooks sit at the front of the permission chain, covering key lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStart/Stop, PreCompact, PermissionRequest. Matchers support regex (e.g., "Write|Edit", "^mcp__"). Callbacks can return four interventions: permissionDecision (allow/deny/ask), updatedInput (rewrite tool arguments before execution), additionalContext (inject extra context to model), updatedToolOutput (rewrite tool output before returning). Practice advice: use hooks for "must-trigger-every-time" controls rather than canUseTool; typical uses: protect .env files, redirect writes to sandbox directories, auto-allow read-only tools, full audit logging; offload side effects like notifications to async output to avoid blocking the main loop.

⑥ Subagents: Context-Isolated Division of Labor

Subagents are defined programmatically via AgentDefinition (recommended) or discovered from .claude/agents/. Each subagent starts with a fresh context, independent toolset, and independent turn limit; only the final result returns to the parent. Default nesting depth is 3, default concurrency 20, all costs counted against the parent's maxBudgetUsd; large-scale orchestration should use Workflows. Practice advice: give each subagent the minimal toolset — research agents get Read/Grep/WebSearch, execution agents get write tools; write clear description fields ("when to use this") for model routing; delegate exploratory tasks to subagents to keep the main context clean.

⑦ Skills and Plugins: Codifying Domain Knowledge

Skills are file artifacts at .claude/skills/<name>/SKILL.md, auto-discovered via settingSources. The model decides when to invoke based on the skill's description, or can be explicitly triggered via /<name>; a whitelist can restrict available skills. Plugins package skills, agents, hooks, and MCP servers for reuse across projects. Practice advice: two knowledge types belong in Skills — private-domain knowledge absent from model training, and domain SOPs ("what to check first, what to query next, which branch to take"); combine with system-prompt injection of hard rules (distinguish speculation from verified conclusions, annotate confidence) to turn the general foundation into a domain expert.

Capability Aggregation: From Individual Features to Comprehensive Agent

The seven capabilities are not a flat list but layered dependencies:

Loop Foundation: ① Loop Control + ② Context Management — makes the agent runnable and sustainable.

Capability Extension: ③ Tool System + ⑦ Skills — makes the agent knowledgeable and connectable.

Safety Guardrails: ④ Permission Governance + ⑤ Hooks — makes the agent safe and auditable.

Division and Orchestration: ⑥ Subagents + Workflow — makes the agent handle large tasks.

Together they yield a comprehensive agent that runs stably in production.

Reference Engineering Layered Architecture

Orchestration Layer : deterministic flows → Workflow; simple tasks → single LLM call; complex reasoning → Agent.

Agent Harness Layer (Claude Agent SDK) : agent loop, context management, sessions, subagents, permissions, hooks.

Capability Layer : built-in tools (file/Bash/search) + custom tools & MCP (enterprise systems) + Skills (knowledge & SOPs).

Data & Infrastructure Layer : wrap data entry points into agent-friendly interfaces; read-only mounts, logging, timeouts.

Governance & Iteration Layer : permission sandbox + hooks audit; evaluation sets and bad-case-driven feedback loops.

Three guiding principles are emphasized: Orchestration does subtraction — avoid Agent when a single LLM call suffices; Context determines the ceiling — the agent cannot invent information, so data infrastructure must shift from "human-optimized" to "agent-optimized"; Feedback determines long-term performance — from day one, measure success rate, latency, cost with eval sets, and iterate Skills and infrastructure driven by bad cases.

The article concludes that the Claude Agent SDK's design is clean: the foundation handles execution, tools and Skills handle specialization, permissions and Hooks handle safety, division and architecture handle scale — and critically, continuous domain knowledge distillation is what makes the system improve over time.

References

Agent SDK Overview: https://code.claude.com/docs/en/agent-sdk/overview

Agent Loop: https://code.claude.com/docs/en/agent-sdk/agent-loop

Permissions: https://code.claude.com/docs/en/agent-sdk/permissions

Hooks: https://code.claude.com/docs/en/agent-sdk/hooks

Subagents: https://code.claude.com/docs/en/agent-sdk/subagents

Anthropic Engineering: Building agents with the Claude Agent SDK: https://claude.com/blog/building-agents-with-the-claude-agent-sdk