所有 AI Agent 框架的核心都是一个循环。Claude Agent SDK 把 Claude Code 内部那个循环完整开放出来了——理解它，你就理解了 Agent 的心脏。
这是 Claude Agent SDK 深度实践系列的第一篇。我们从最核心的概念切入：Agent Loop。
如果你用过 Claude Code，你已经在享受这个循环的成果了——你说一句帮我修这个 Bug，Claude 自己读文件、分析代码、改代码、跑测试，全程不需要你介入。Agent SDK 做的事情是把这个循环从 CLI 里拆出来，变成一个你可以嵌入到任何应用里的库。
这篇文章不翻译文档。我会用一个真实的例子走一遍循环的每个阶段，然后拆解你在实际开发中最容易踩的坑。
循环全景：五步走完一个任务
Agent Loop 的核心逻辑可以用一句话概括：Claude 评估当前状态 → 决定调用什么工具 → 拿到结果 → 再评估 → 直到不需要工具为止。
用代码表达就是：
import"@anthropic-ai/claude-agent-sdk"// query() 返回一个 AsyncIterable，每次迭代产出一条消息// 整个循环会持续到 Agent 完成任务或命中限制forof// prompt 是 Agent 的任务指令——它会自主决定如何完成"Review utils.ts for bugs that would cause crashes. Fix any issues you find."options// 只开放这三个工具，Agent 无法执行其他操作"Read""Edit""Glob"// 自动批准文件编辑，无需人工确认"acceptEdits"// 通过 message.type 判断消息来源if"assistant"// Claude 的响应：可能包含文本和/或工具调用请求forofif"text"inconsolelogtextelseif"result"// 循环结束标志：subtype 告诉你为什么结束consolelog`Done: ${message.subtype}`这段代码启动了一个 Agent，它会自动读文件、找 Bug、修代码。你只需要消费消息流。
整个循环分五步：
第一步：接收 Prompt。SDK 把你的提示词、系统提示词、工具定义和对话历史打包发给 Claude。同时产出一条SystemMessage（subtype 为init），包含会话元数据。
第二步：评估并响应。Claude 分析当前状态，决定下一步。它可能回复文本、请求工具调用、或者两者兼有。SDK 产出一条AssistantMessage。
第三步：执行工具。SDK 运行 Claude 请求的每个工具，收集结果。你可以用 Hooks 在工具执行前拦截、修改或阻止。
第四步：循环。第二步和第三步反复执行。每一轮叫一个 Turn。
第五步：返回结果。当 Claude 产出一条不包含工具调用的响应时，循环结束。SDK 产出最终的AssistantMessage和一条ResultMessage（包含最终文本、token 用量、花费和 session ID）。
Turn：循环的计量单位
Turn 是 Agent Loop 的基本计量单位。一个 Turn = Claude 产出输出（含工具调用）+ SDK 执行工具 + 结果回传给 Claude。
用一个真实场景来理解。假设你的 prompt 是让 Agent 修复 auth.ts 中失败的测试：
Turn 1：Claude 调用Bash运行npm test。SDK 执行命令，返回输出（三个测试失败）。
Turn 2：Claude 调用Read读取auth.ts和auth.test.ts。SDK 返回文件内容。
Turn 3：Claude 调用Edit修复auth.ts，然后调用Bash重新跑测试。全部通过。
最终 Turn：Claude 产出纯文本响应，告诉你 auth 的 Bug 已修复、三个测试全部通过。没有工具调用，循环结束。
三个有工具调用的 Turn + 一个纯文本 Turn = 整个任务完成。
控制循环的两个旋钮
你有两种方式限制循环的长度：
options={ maxTurns:10// 最多 10 个包含工具调用的 Turn（纯文本响应不计入） maxBudgetUsd:0.50// 花费硬上限，命中后循环立即终止并返回 error_max_budget_usd};maxTurns只计算包含工具调用的 Turn。上面那个例子如果设maxTurns: 2，循环会在 Edit 步骤之前停下来。
maxBudgetUsd是花费上限。对于生产环境的 Agent，设预算是默认操作。开放式 prompt（比如让 Agent 自由优化整个代码库）不设上限可能跑很久。
五种消息类型：循环的语言
Agent Loop 运行时产出一条消息流。每条消息有一个类型，告诉你它来自循环的哪个阶段：
| 类型 | 含义 | 你通常怎么用 |
|---|---|---|
system | 会话生命周期事件。init是第一条（会话元数据），compact_boundary在上下文压缩后触发 | 获取 session_id |
assistant | Claude 的每次响应，包含文本和工具调用请求 | 展示进度、记录工具调用 |
user | 工具执行结果回传给 Claude | 调试时查看工具输出 |
stream_event | 启用 partial messages 时的实时流事件 | 构建实时 UI |
result | 循环结束标志。包含最终文本、token 用量、花费、session_id | 获取最终结果和成本 |
消息类型判别
TypeScript SDK 用message.type字符串字段做类型判别，内容块在message.message.content而不是直接在message.content——这是第一次写时最容易踩的坑：
import"@anthropic-ai/claude-agent-sdk"forofprompt"Summarize this project"optionsallowedTools"Read""Glob""Grep"if"assistant"// ⚠️ 关键坑点：content 在 message.message.content// 不是 message.content——多了一层 .message 包装forof// 文本块：Claude 的思考和回复if"text"inconsolelogtext// 工具调用块：有 name 字段表示 Claude 请求调用某个工具elseif"name"inconsolelog`🔧 Tool: ${block.name}`elseif"result"// result 消息标志循环结束，subtype 说明原因if"success"// 正常完成：Agent 主动结束consolelogelse// 非正常结束：error_max_turns | error_max_budget_usdconsolelog`Stopped: ${message.subtype}`ResultMessage.subtype的取值告诉你循环为什么结束：success表示正常完成，error_max_turns表示命中轮次上限，error_max_budget_usd表示命中预算上限。
工具执行：Agent 的手和脚
没有工具，Claude 只能回复文本。有了工具，它能读文件、跑命令、搜代码、调外部服务。
内置工具一览
SDK 自带的工具和 Claude Code 完全一致：
| 类别 | 工具 | 能力 |
|---|---|---|
| 文件操作 | Read,Edit,Write | 读、改、创建文件 |
| 搜索 | Glob,Grep | 按模式找文件、正则搜内容 |
| 执行 | Bash | 跑终端命令 |
| 网络 | WebSearch,WebFetch | 搜索和抓取网页 |
| 交互 | AskUserQuestion | 向用户提问 |
| 监控 | Monitor | 监听后台脚本输出 |
工具的组合决定了 Agent 的能力边界：
// 只读分析——Agent 只能看，不能改任何东西// 适合：代码审查、项目摘要、依赖分析const"Read""Glob""Grep"// 分析 + 修改——能改文件但不能跑命令// 适合：代码重构、格式化、批量替换const"Read""Edit""Glob"// 全自动化——能读、能改、能跑命令// 适合：修 Bug、跑测试、构建部署// ⚠️ 生产环境务必搭配 permissionMode: "dontAsk"const"Read""Edit""Bash""Glob""Grep"并行工具执行
Claude 可以在一个 Turn 里请求多个工具调用。SDK 会并行执行它们，然后把所有结果一起回传。比如 Claude 可能同时请求读取三个文件——SDK 并行读取，一次性返回三个文件的内容。
这对性能很重要。如果你的自定义工具支持并发，Agent 的执行速度会显著提升。
权限模式
五种模式控制工具的审批策略：
| 模式 | 行为 | 适用场景 |
|---|---|---|
default | 未被 allow 规则覆盖的工具触发审批回调 | 需要精细控制的场景 |
acceptEdits | 自动批准文件编辑和常见文件系统命令 | 可信开发环境 |
plan | Claude 只探索和规划，不编辑源文件 | 代码审查、方案设计 |
dontAsk | 拒绝所有不在allowedTools里的操作 | CI/CD、后台任务 |
bypassPermissions | 批准所有操作，不询问 | 完全受控的沙箱环境 |
生产环境的建议：用dontAsk+ 精确的allowedTools列表。宁可少给权限，也不要让 Agent 在生产环境里跑rm -rf。
上下文窗口：Agent 的工作记忆
上下文窗口是 Agent 的短期记忆。所有东西都在里面：系统提示词、对话历史、工具定义、工具结果。它有容量上限。
什么消耗上下文？
按消耗量从大到小：
工具结果——读一个大文件、跑一个输出很长的命令，都会大量消耗上下文
对话历史——每个 Turn 的输入输出都累积
工具定义——每个工具的 schema 占一些空间
系统提示词——通常是固定开销
自动压缩（Compaction）
当上下文接近容量上限时，SDK 会自动触发压缩。它把之前的对话历史浓缩成一个摘要，释放空间给新的 Turn。压缩后会产出一条独立的CompactBoundaryMessage。
压缩是有损的。被压缩掉的细节 Claude 就不记得了。这意味着：
• 长任务中，早期的工具结果可能被压缩掉
• 如果 Agent 需要反复引用某个信息，最好把它写入文件而不是只放在对话里
• 系统提示词不会被压缩，所以关键指令放在 system prompt 里最安全
保持上下文高效的实践建议
精确读取：用
Grep定位再Read特定行，而不是读整个大文件限制 Bash 输出：长命令加
| head -50或重定向到文件工具定义精简：只给 Agent 它需要的工具，不要全部开放
利用文件系统：让 Agent 把中间结果写入文件，而不是全部保持在对话里
会话与连续性
每次query()调用会创建或延续一个会话（Session）。会话是 Agent 的完整对话历史，持久化到磁盘。
三种会话操作
| 操作 | 含义 | 用法 |
|---|---|---|
| Continue | 继续当前目录最近的会话 | 多轮对话、进程重启后恢复 |
| Resume | 通过 ID 恢复指定会话 | 多用户应用、恢复特定历史 |
| Fork | 复制一个会话的历史创建新会话 | 尝试不同方案、A/B 测试 |
from"@anthropic-ai/claude-agent-sdk"// --- 继续最近的会话 ---// continue: true 会自动找到当前目录最近一次会话并接续// 典型场景：进程重启后恢复、多轮对话forawaitconstqueryprompt"Continue where we left off"optionscontinuetrue/* ... */// --- 恢复指定会话 ---// 通过 session ID 精确恢复某次历史对话// 典型场景：多用户应用中恢复特定用户的上下文forawaitconstqueryprompt"What did we discuss?"optionsresume"session-id-here"/* ... */// --- 查看历史会话列表 ---// 可用于构建会话管理 UI 或审计日志constsessionslistSessionsdir"/path/to/project"limit5forconstsessionconstmessagesgetSessionMessageslimit10log会话持久化的是对话，不是文件系统。如果你需要回滚 Agent 对文件的修改，要用 File Checkpointing（后续文章会讲）。
完整实战：一个能修 Bug 的 Agent
把上面所有概念串起来，这是一个完整的、可运行的 Bug Fixer Agent：
import"@anthropic-ai/claude-agent-sdk"functionmainnullnullforof// 任务描述：越具体，Agent 越高效"Find bugs in utils.ts that would cause crashes. Fix them and verify with tests."options// 给足工具：读、改、跑命令、搜索"Read""Edit""Bash""Glob""Grep"// 自动批准编辑，适合可信开发环境"acceptEdits"// 安全护栏：防止 Agent 无限循环15maxBudgetUsd1.00// system prompt 塑造 Agent 的行为风格"You are a senior TypeScript developer. Fix bugs defensively. Always run tests after changes."// --- 消息分发：根据 type 决定如何处理 ---if"system"// system 消息：会话生命周期事件（init / compact_boundary）if"session_id"inconsolelog`[Session started: ${sessionId}]`elseif"assistant"// assistant 消息：Claude 的每次响应forofif"text"in// 文本块：Claude 的思考过程或最终回复consolelog`💭 ${block.text}`elseif"name"in// 工具调用块：Claude 请求执行某个工具consolelog`🔧 Tool: ${block.name}`elseif"result"// result 消息：循环结束，包含汇总信息consolelog`\n✅ Done: ${message.subtype}`consolelog`💰 Cost: $${message.total_cost_usd.toFixed(4)}`consolelog`📊 Turns: ${message.num_turns}`return这个 Agent 会：
用
Glob找到utils.ts用
Read读取内容分析潜在的崩溃点（undefined 访问、类型断言错误、空数组操作等）
用
Edit添加防御性代码用
Bash跑测试验证修复如果测试失败，继续修复直到通过
整个过程你只需要消费消息流，看着它工作。
设计决策：为什么是这样？
理解 Agent Loop 的设计决策，能帮你更好地使用它：
为什么工具执行在 SDK 侧而不是 Claude 侧？安全。工具在你的环境里执行，你可以用 Hooks 拦截、用权限控制、用沙箱隔离。Claude 只负责决策，不负责执行。
为什么用流式消息而不是一次性返回？长任务可能跑几分钟。流式让你能实时展示进度、在中途干预、或者在出问题时提前终止。
为什么 Turn 计数不包含最终的纯文本响应？因为maxTurns的目的是限制 Agent 的"行动次数"。最终响应是总结，不是行动。
为什么会话默认持久化到磁盘？因为 Agent 任务经常被中断——网络断了、进程被杀了、用户关了终端。持久化让你能无缝恢复，不用从头开始。
学AI大模型的正确顺序，千万不要搞错了
🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！
有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！
就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋
📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇
学习路线:
✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经
以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！
我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～