Agent Loop：一个循环统治所有 Agent

所有 AI Agent 框架的核心都是一个循环。Claude Agent SDK 把 Claude Code 内部那个循环完整开放出来了——理解它你就理解了 Agent 的心脏。这是 Claude Agent SDK 深度实践系列的第一篇。我们从最核心的概念切入Agent Loop。如果你用过 Claude Code你已经在享受这个循环的成果了——你说一句帮我修这个 BugClaude 自己读文件、分析代码、改代码、跑测试全程不需要你介入。Agent SDK 做的事情是把这个循环从 CLI 里拆出来变成一个你可以嵌入到任何应用里的库。这篇文章不翻译文档。我会用一个真实的例子走一遍循环的每个阶段然后拆解你在实际开发中最容易踩的坑。循环全景五步走完一个任务Agent Loop 的核心逻辑可以用一句话概括Claude 评估当前状态 → 决定调用什么工具 → 拿到结果 → 再评估 → 直到不需要工具为止。用代码表达就是importanthropic-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 无法执行其他操作ReadEditGlob// 自动批准文件编辑无需人工确认acceptEdits// 通过 message.type 判断消息来源ifassistant// Claude 的响应可能包含文本和/或工具调用请求forofiftextinconsolelogtextelseifresult// 循环结束标志subtype 告诉你为什么结束consolelogDone: ${message.subtype}这段代码启动了一个 Agent它会自动读文件、找 Bug、修代码。你只需要消费消息流。整个循环分五步第一步接收 Prompt。SDK 把你的提示词、系统提示词、工具定义和对话历史打包发给 Claude。同时产出一条SystemMessagesubtype 为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 1Claude 调用Bash运行npm test。SDK 执行命令返回输出三个测试失败。Turn 2Claude 调用Read读取auth.ts和auth.test.ts。SDK 返回文件内容。Turn 3Claude 调用Edit修复auth.ts然后调用Bash重新跑测试。全部通过。最终 TurnClaude 产出纯文本响应告诉你 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_idassistantClaude 的每次响应包含文本和工具调用请求展示进度、记录工具调用user工具执行结果回传给 Claude调试时查看工具输出stream_event启用 partial messages 时的实时流事件构建实时 UIresult循环结束标志。包含最终文本、token 用量、花费、session_id获取最终结果和成本消息类型判别TypeScript SDK 用message.type字符串字段做类型判别内容块在message.message.content而不是直接在message.content——这是第一次写时最容易踩的坑importanthropic-ai/claude-agent-sdkforofpromptSummarize this projectoptionsallowedToolsReadGlobGrepifassistant// ⚠️ 关键坑点content 在 message.message.content// 不是 message.content——多了一层 .message 包装forof// 文本块Claude 的思考和回复iftextinconsolelogtext// 工具调用块有 name 字段表示 Claude 请求调用某个工具elseifnameinconsolelog Tool: ${block.name}elseifresult// result 消息标志循环结束subtype 说明原因ifsuccess// 正常完成Agent 主动结束consolelogelse// 非正常结束error_max_turns | error_max_budget_usdconsolelogStopped: ${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 只能看不能改任何东西// 适合代码审查、项目摘要、依赖分析constReadGlobGrep// 分析 修改——能改文件但不能跑命令// 适合代码重构、格式化、批量替换constReadEditGlob// 全自动化——能读、能改、能跑命令// 适合修 Bug、跑测试、构建部署// ⚠️ 生产环境务必搭配 permissionMode: dontAskconstReadEditBashGlobGrep并行工具执行Claude 可以在一个 Turn 里请求多个工具调用。SDK 会并行执行它们然后把所有结果一起回传。比如 Claude 可能同时请求读取三个文件——SDK 并行读取一次性返回三个文件的内容。这对性能很重要。如果你的自定义工具支持并发Agent 的执行速度会显著提升。权限模式五种模式控制工具的审批策略模式行为适用场景default未被 allow 规则覆盖的工具触发审批回调需要精细控制的场景acceptEdits自动批准文件编辑和常见文件系统命令可信开发环境planClaude 只探索和规划不编辑源文件代码审查、方案设计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 测试fromanthropic-ai/claude-agent-sdk// --- 继续最近的会话 ---// continue: true 会自动找到当前目录最近一次会话并接续// 典型场景进程重启后恢复、多轮对话forawaitconstquerypromptContinue where we left offoptionscontinuetrue/* ... */// --- 恢复指定会话 ---// 通过 session ID 精确恢复某次历史对话// 典型场景多用户应用中恢复特定用户的上下文forawaitconstquerypromptWhat did we discuss?optionsresumesession-id-here/* ... */// --- 查看历史会话列表 ---// 可用于构建会话管理 UI 或审计日志constsessionslistSessionsdir/path/to/projectlimit5forconstsessionconstmessagesgetSessionMessageslimit10log会话持久化的是对话不是文件系统。如果你需要回滚 Agent 对文件的修改要用 File Checkpointing后续文章会讲。完整实战一个能修 Bug 的 Agent把上面所有概念串起来这是一个完整的、可运行的 Bug Fixer Agentimportanthropic-ai/claude-agent-sdkfunctionmainnullnullforof// 任务描述越具体Agent 越高效Find bugs in utils.ts that would cause crashes. Fix them and verify with tests.options// 给足工具读、改、跑命令、搜索ReadEditBashGlobGrep// 自动批准编辑适合可信开发环境acceptEdits// 安全护栏防止 Agent 无限循环15maxBudgetUsd1.00// system prompt 塑造 Agent 的行为风格You are a senior TypeScript developer. Fix bugs defensively. Always run tests after changes.// --- 消息分发根据 type 决定如何处理 ---ifsystem// system 消息会话生命周期事件init / compact_boundaryifsession_idinconsolelog[Session started: ${sessionId}]elseifassistant// assistant 消息Claude 的每次响应forofiftextin// 文本块Claude 的思考过程或最终回复consolelog ${block.text}elseifnamein// 工具调用块Claude 请求执行某个工具consolelog Tool: ${block.name}elseifresult// 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时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】