Claude Agent SDK Core Concepts

Source Snapshot

Origin: Claude Code Agent SDK documentation Author / org: Anthropic Why this matters: The Agent SDK turns Claude Code’s autonomous loop into an embeddable platform primitive for enterprise agent systems, with explicit controls for tools, permissions, sessions, budgets, and observability.

One-line takeaway: A production Claude Agent SDK application is not just a prompt wrapper; it is a controlled loop that repeatedly reasons, calls tools, handles results, preserves session state, and enforces operating boundaries.

---

1. Executive Summary

Reading Position

This note explains Claude Agent SDK core concepts for building reliable agentic AI systems. It should help me decide how to design agents that are useful, auditable, resumable, and safe enough for enterprise workflows.

Core Message

The Claude Agent SDK embeds the same autonomous loop that powers Claude Code into custom applications. The loop receives a prompt plus settings, lets Claude decide whether to answer or call tools, executes approved tools, feeds results back, and repeats until a final result is produced. The important design work is therefore not only model selection; it is how we control tools, permissions, context, sessions, and cost.

• Main idea: Treat the SDK as an agent runtime, not a simple chat API.
• Why now: Enterprise AI work is moving from one-off assistance toward agents that operate across files, codebases, systems, and business workflows.
• What changed my thinking: Sessions and settings are first-class architecture concerns; they shape continuity, governance, and data integrity.
• Where I can apply it: Internal engineering agents, Lark/Feishu workflow agents, GitHub/Vercel publishing assistants, and controlled personal knowledge workflows.

Decision Signal

If I only remember one thing from this note, it should be:

Design every SDK agent around the loop boundary: what context enters, what tools can run, what state persists, and how the final result is validated.

---

2. Key Ideas

2.1 The Agent Loop Is The Runtime Contract

Concept

The SDK agent loop is a repeated cycle: receive prompt and settings, evaluate current state, request tool calls when useful, execute the tools, return results to Claude, and continue until Claude produces a final answer without tool calls.

Evidence from source

• A session starts with metadata and then yields assistant, user/tool-result, streaming, and result messages as the loop progresses.
• A turn is one round trip where Claude requests tool use, the SDK executes it, and the results feed back into the next decision.
• The final result includes status, token usage, cost, and session ID.

My interpretation

For enterprise work, the loop is the unit of control. The value is not only that Claude can call tools; it is that the application can observe, limit, interrupt, resume, and audit that tool-using behavior.

2.2 Tools Turn Reasoning Into Action

Example

A coding agent can inspect files, search a repository, edit source code, run tests, and report the result. A business workflow agent can search a knowledge base, call approved MCP tools, draft a document, and ask for approval before sending or publishing.

Evidence from source

• Built-in tool groups include file operations, search, command execution, web access, discovery, and orchestration.
• MCP servers and custom tools extend the agent into external systems.
• Read-only tools can run concurrently, while state-changing tools run sequentially to avoid conflicts.

My interpretation

Tool design is where operational leverage appears. The right tool boundary can convert a manual process into a repeatable workflow, but loose tool access can also damage data integrity. Each tool should have clear permission, audit, and failure behavior.

2.3 Permissions Are Governance, Not Friction

Limitation

Autonomous agents become risky when tool permissions are too broad, when destructive tools are allowed without review, or when production and development environments share the same operating boundary.

Evidence from source

• allowed_tools / allowedTools can auto-approve specific tools.
• disallowed_tools / disallowedTools blocks tools regardless of other settings.
• permission_mode controls approval behavior for tools that are not explicitly allowed or blocked.
• The docs reserve broad bypass behavior for isolated environments.

My interpretation

In manufacturing or enterprise IT, permission rules should be treated like change-control policy. A read-only diagnostic agent and a write-capable deployment agent should be different operating modes, not the same agent with a vague prompt instruction.

2.4 Context Is A Budget And A Risk Surface

Concept

The context window accumulates system prompts, tool schemas, conversation history, tool inputs, tool outputs, settings, and skills across a session.

Evidence from source

• Large tool outputs can consume significant context in one turn.
• Tool definitions are loaded repeatedly, while tool search can defer MCP schemas.
• Automatic compaction summarizes older history near the context limit.
• Persistent rules belong in files such as CLAUDE.md because early prompt details may be summarized away.

My interpretation

Context should be managed like working memory in an operating process. Keep routine instructions in project files, keep tools scoped, avoid huge logs by default, and use subagents for isolated work so the main session does not become bloated or confused.

2.5 Sessions Create Continuity, Not File Snapshots

Key Principle

Sessions preserve agent conversation history. They do not preserve or revert the filesystem.

Evidence from source

• Sessions contain prompts, tool calls, tool results, and responses.
• Resume restores prior analysis and decisions when the session file and cwd match.
• Fork creates a new conversation history branch, but file edits remain real in the shared directory.
• Cross-host resume requires session files to be available in the expected location or a shared session store.

My interpretation

For agent platforms, session state and work-state are separate. Session resume helps continuity, but production workflows still need file checkpointing, commits, database transactions, or explicit workflow state to protect real assets.

---

3. Structure Map

flowchart TD
  A["Prompt + settings + history"] --> B["Claude evaluates state"]
  B --> C{"Need action?"}
  C -->|No| D["Final AssistantMessage"]
  D --> E["ResultMessage: status, cost, usage, session_id"]
  C -->|Yes| F["Tool call request"]
  F --> G["Permission and hook checks"]
  G --> H["Execute approved tools"]
  H --> I["Tool result returns as UserMessage"]
  I --> B
  B --> J["Context grows across turns"]
  J --> K["Compaction or subagents control context pressure"]
  E --> L["Continue, resume, or fork session"]

Structure Insight

The source material is organized around the agent as a runtime system: loop mechanics, feature loading, and session continuity. This matters because enterprise agents need predictable lifecycle controls, not only better prompts.

---

4. Comparison Table

Dimension	One-Shot Chat / API Call	Claude Agent SDK Session	My Take
Purpose	Generate one response	Complete work through repeated reasoning and tool use	Use SDK when the task has multiple steps or needs system access.
State	Prompt-bound	Conversation, tool calls, results, and decisions accumulate	Useful for continuity, but must be governed.
Tools	Usually external orchestration	Built-in and custom tool execution inside the loop	Tool permissions become a core architecture layer.
Control	App decides each step	Claude decides steps within configured boundaries	Better leverage, higher need for observability.
Recovery	Re-run prompt	Continue, resume, or fork	Good for long work, but filesystem state needs separate protection.
Enterprise relevance	Lightweight assistance	Workflow automation and operational agents	SDK is stronger for repeatable internal agent platforms.

Table Use

The main design choice is whether a task needs a controlled action loop. If yes, use SDK patterns; if no, a normal prompt or API call is simpler and cheaper.

---

5. Chart / Quantitative View

xychart-beta
  title "Relative design importance for enterprise SDK agents"
  x-axis ["Loop", "Tools", "Permissions", "Context", "Sessions", "Hooks"]
  y-axis "Importance" 0 --> 10
  bar [10, 9, 10, 8, 8, 7]

Chart interpretation: The top risks and opportunities sit around the loop boundary, tool access, and permissions. These areas determine whether an agent is operationally useful or merely impressive in a demo.

---

6. Code / Technical Pattern

import asyncio
from typing import Optional
 
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
 
 
async def run_controlled_agent(prompt: str) -> str:
    """Run one controlled SDK task and return only a successful final result."""
    session_id: Optional[str] = None
 
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            disallowed_tools=["Bash"],
            max_turns=12,
            max_budget_usd=1.0,
            effort="medium",
            setting_sources=["project"],
        ),
    ):
        if isinstance(message, ResultMessage):
            session_id = message.session_id
            if message.subtype == "success" and message.result is not None:
                return message.result
 
            raise RuntimeError(
                f"Agent stopped with subtype={message.subtype}, "
                f"session_id={session_id}"
            )
 
    raise RuntimeError("Agent stream ended without a ResultMessage")
 
 
asyncio.run(run_controlled_agent("Summarize this project architecture."))

What it demonstrates: The SDK call is framed as a controlled operation: tools are scoped, shell execution is blocked, turn and cost limits are set, and the final result subtype is checked before trusting the output.

Production note: For industrial workflows, wrap this pattern with structured logging, session ID storage, permission policy, retry rules, and human approval for state-changing actions. This protects operational efficiency and data integrity because every run can be traced and bounded.

Implementation Risk

Before using this pattern in production, validate SDK version behavior, exact model IDs, credential isolation, approval callbacks, logging redaction, and whether sessions are stored in a location appropriate for the deployment environment.

---

7. Highlight Blocks

Source Phrase

“Session” is the key continuity concept across the docs: it carries prior prompts, tool calls, tool results, and decisions.

Key Principle

Separate agent memory from system state. Session history helps the model continue work; commits, checkpoints, transactions, and audit logs protect the real environment.

Open Question

For my own agent platform, should each business workflow get its own dedicated session store, or should sessions be short-lived with durable workflow state stored separately?

Do Not Forget

Do not use broad permission bypass in environments connected to valuable files, production APIs, source repositories, or enterprise systems unless the environment is isolated and disposable.

---

8. Personal Synthesis

Practical Application

1. Build read-only diagnostic agents first, then add write permissions only after the observation and logging paths are reliable.
2. Store session IDs and final result metadata for long-running workflows so failures can be resumed or audited.
3. Use project instructions and skills for durable operating rules instead of repeating critical instructions in prompts.
4. Keep context efficient by scoping tools, limiting verbose outputs, and delegating isolated work to subagents when needed.

Reusable Design Rule

When building a Claude Agent SDK workflow,
choose the smallest useful tool set,
set explicit turn/cost/permission boundaries,
persist the session and operational result metadata,
and verify state-changing outputs outside the model loop.

---

9. References

• How the agent loop works
• Use Claude Code features in the SDK
• Work with sessions