deanlu.ai

Claude Agent SDK Core Concepts

9 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.

这篇笔记是一张面向 Claude Agent SDK 的 Quartz 运行地图。它把 SDK 解释为智能体运行时，而不是简单的提示词包装器。

  • Core question: How should an SDK agent be bounded, observed, resumed, and validated? 核心问题：SDK 智能体应该如何被限定、观测、恢复和验证？

  • Operational value: It turns autonomous tool use into an auditable enterprise workflow. 运营价值：它把自主工具调用转化为可审计的企业工作流。

  • Best connection: SDK Demo Learning Map, GitHub Projects for Agent SDK, How to Use Claude Cowork Effectively 最适合连接的内容：SDK Demo 学习路线、GitHub 项目参考和 Claude Cowork 使用方法。

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.

Claude Agent SDK 把 Claude Code 背后的自主循环嵌入到自定义应用中。这个循环接收提示词和设置，让 Claude 判断是直接回答还是调用工具，执行被批准的工具，把结果返回给模型，并重复直到产出最终结果。

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. 主要观点：把 SDK 当成智能体运行时。

  • Why now: Enterprise AI is moving from one-shot assistance to tool-using workflows. 为什么现在重要：企业 AI 正从一次性辅助走向会调用工具的工作流。

  • Where it applies: Engineering agents, Feishu workflow agents, GitHub/Vercel assistants, and knowledge automation. 可以应用的场景：工程智能体、飞书工作流智能体、GitHub/Vercel 助手和知识自动化。

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.

这些术语可以作为 SDK 智能体设计的稳定词汇。

  • 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.

会调用工具的智能体可以创造价值，但如果运行边界不清，也可能修改文件、调用 API、消耗预算，或在过期上下文中继续工作。

  • 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.

SDK 提供可控循环：配置选项、流式接收消息、批准或阻断工具、收集结果并保留会话身份。

  • Use minimal allowed tools for each workflow. 每个工作流只开放最小必要工具。

  • Use hooks for audit, policy, and human checkpoints. 用钩子实现审计、策略和人工检查点。

  • Store session IDs and result metadata for recovery. 保存会话 ID 和结果元数据，便于恢复和审计。

3.3 Evidence

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

SDK 文档把执行过程描述为流式消息和结果记录，其中包括状态、token 用量、成本和会话 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. 不要在重要环境中授予过宽的写入或 shell 权限。

  • Do not treat session resume as rollback. 不要把会话恢复当成回滚机制。

4. Concept Map

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

使用双向链接把这篇笔记接入更大的 Quartz 知识网络。

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.

图中的标签保持英文，便于 Quartz 渲染后跨页面复用，也方便技术读者快速识别。

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.

当应用把智能体循环当成生产边界时，SDK 最有价值。运行时应该暴露发生了什么、允许了什么、改变了什么，以及为什么结果可以被信任。

  • 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. 下一步可能行动：先构建只读 SDK 智能体，再开放可写工作流。

  • What still needs verification: SDK version behavior, exact option names, credential scope, and log redaction. 仍需要验证的内容：SDK 版本行为、准确选项名称、凭证范围和日志脱敏。

Reuse Path

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

References

Graph View

Backlinks