Claude Agent SDK Core Concepts

4 min read

Source Snapshot

  • Origin: Claude Code Agent SDK documentation
  • Type: Documentation synthesis
  • Author / org: Anthropic
  • One-line takeaway: A production Claude Agent SDK application is a controlled loop with tools, permissions, sessions, budgets, and observable results.

Garden Card

This note is a Quartz-ready operating map for the Claude Agent SDK. It explains the SDK as an agent runtime rather than a simple prompt wrapper.

1. Executive Summary

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 not only model selection. It is how the application controls tools, permissions, context, sessions, budgets, and validation.

  • Main idea: Treat the SDK as an agent runtime.

  • Why now: Enterprise AI is moving from one-shot assistance to tool-using workflows.

  • Where it applies: Engineering agents, Feishu workflow agents, GitHub/Vercel assistants, and knowledge automation.

Decision Signal

Design every SDK agent around the loop boundary: context in, tools allowed, state persisted, and output validated.

2. Key Technical Terms

Use these terms as the stable vocabulary for SDK-based agent design.

  • Agent loop: Repeated reasoning and tool-use cycle that continues until a final result is produced.

  • Tool permission: Policy that defines which tools can run automatically, require approval, or are blocked.

  • Session: Conversation history containing prompts, tool calls, results, and decisions.

  • Hook: Interception point for logging, blocking, approval, or workflow policy.

  • Context budget: The limited working memory consumed by prompts, files, tool schemas, and outputs.

3. Core Notes

3.1 Problem

A tool-using agent can create value, but it can also mutate files, call APIs, consume budget, or continue work from stale context if the runtime boundary is unclear.

  • Loose tools create data-integrity risk.

  • Long sessions create context drift.

  • Unvalidated results create operational risk.

3.2 Mechanism

The SDK provides a controllable loop: configure options, stream messages, approve or block tools, collect results, and preserve session identity.

  • Use minimal allowed tools for each workflow.

  • Use hooks for audit, policy, and human checkpoints.

  • Store session IDs and result metadata for recovery.

3.3 Evidence

The SDK documentation frames execution as streamed messages and result records, including status, token usage, cost, and session ID.

  • Tools convert reasoning into action.

  • Permissions convert action into governed operation.

  • Sessions convert one-off work into resumable continuity.

3.4 Boundary

Session history is not the same as system state. File checkpoints, commits, transactions, and logs still need their own durable controls.

  • Do not rely on prompt instructions alone for safety.

  • Do not grant broad write or shell access in valuable environments.

  • Do not treat session resume as rollback.

4. Concept Map

Use wikilinks to connect this note into the broader Quartz graph.

flowchart LR
  A["Prompt and Settings"] --> B["Agent Loop"]
  B --> C{"Needs Tool?"}
  C -- "No" --> D["Final Result"]
  C -- "Yes" --> E["Permission Check"]
  E --> F["Tool Execution"]
  F --> G["Tool Result"]
  G --> B
  D --> H["Session Metadata"]
  D --> I["Validation"]

Diagram labels stay in English for rendering consistency and easier reuse across published pages.

5. My Take

The SDK is most valuable when the application treats the agent loop as a production boundary. The runtime should expose what happened, what was allowed, what changed, and why the result can be trusted.

  • What changed my thinking: Sessions and settings are architecture concerns.

  • What I may do next: Build read-only SDK agents before enabling write-capable workflows.

  • What still needs verification: SDK version behavior, exact option names, credential scope, and log redaction.

Reuse Path

Convert this note into an SDK agent design checklist before building production workflows.

References

Graph View

Backlinks