核心概念
How the agent loop works
How the agent loop works 这一页讲的，就是 How the agent loop works 这件事在 Claude Code 里到底怎么用。
页面信息
这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。
如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。
这一页先讲明白
这页主要讲 How the agent loop works：Understand the message lifecycle, tool execution, context window, and architecture that power your SDK agents.
你可以把它当成"Core concepts"这块里专门管这一摊事的说明书。
你可以把"How the agent loop works"理解成 Core concepts 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。
原文这页大多会按 The loop at a glance、Turns and messages、Message types、Handle messages 这些环节往下讲。
翻成人话，大概就是：The loop at a glance
第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。
第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。
第三，照着原文这几个环节挨个过：The loop at a glance -> Turns and messages -> Message types -> Handle messages。像下地先看水路、再试机器、再正式开干，一步一步最稳。
原页关键片段：Handle messages
这一段要真抓重点，通常就抓下面这块原文。
from claude_agent_sdk import query, AssistantMessage, ResultMessage
async for message in query(prompt="Summarize this project"):
if isinstance(message, AssistantMessage):
print(f"Turn completed: {len(message.content)} content blocks")
if isinstance(message, ResultMessage):
if message.subtype == "success":
print(message.result)
else:
print(f"Stopped: {message.subtype}")原页关键片段：Automatic compaction
这一段要真抓重点，通常就抓下面这块原文。
# Summary instructions
When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them原页关键片段：Put it all together
"Put it all together"这一段里最要紧的原始写法在下面，先看它怎么落地。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def run_agent():
session_id = None
async for message in query(
prompt="Find and fix the bug causing test failures in the auth module",
options=ClaudeAgentOptions(
allowed_tools=[
"Read",
"Edit",
"Bash",
"Glob",
"Grep",
], # Listing tools here auto-approves them (no prompting)
setting_sources=[
"project"
], # Load CLAUDE.md, skills, hooks from current directory
max_turns=30, # Prevent runaway sessions
effort="high", # Thorough reasoning for complex debugging
),
):
# Handle the final result
if isinstance(message, ResultMessage):
session_id = message.session_id # Save for potential resumption
if message.subtype == "success":
print(f"Done: {message.result}")
elif message.subtype == "error_max_turns":
# Agent ran out of turns. Resume with a higher limit.
print(f"Hit turn limit. Resume session {session_id} to continue.")
elif message.subtype == "error_max_budget_usd":
print("Hit budget limit.")
else:
print(f"Stopped: {message.subtype}")
if message.total_cost_usd is not None:
print(f"Cost: ${message.total_cost_usd:.4f}")
asyncio.run(run_agent())Documentation Index
这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
The loop at a glance
看到这里，就把"The loop at a glance"当成一件真要上手的活来看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Turns and messages
看到这里，就把"Turns and messages"当成一件真要上手的活来看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Message types
这里不是让你背"Message types"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Handle messages
这一段主要是在把"Handle messages"讲实，不是只摆个标题给你看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Handle messages
这一段要真抓重点，通常就抓下面这块原文。
from claude_agent_sdk import query, AssistantMessage, ResultMessage
async for message in query(prompt="Summarize this project"):
if isinstance(message, AssistantMessage):
print(f"Turn completed: {len(message.content)} content blocks")
if isinstance(message, ResultMessage):
if message.subtype == "success":
print(message.result)
else:
print(f"Stopped: {message.subtype}")Tool execution
这里不是让你背"Tool execution"这个词，而是让你看它真干活时怎么使。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Built-in tools
这一段不只是挂个标题，它是在说明"Built-in tools"这一块到底负责什么。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Tool permissions
这里不是让你背"Tool permissions"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Parallel tool execution
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Control how the loop runs
看到这类标题，就把它当成日常管摊子的规矩。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Turns and budget
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
Effort level
这里主要是在交代"Effort level"这一块会碰到哪些事。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Permission mode
这里主要是在交代"Permission mode"这一块会碰到哪些事。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Model
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
The context window
这里主要是在交代"The context window"这一块会碰到哪些事。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
What consumes context
这里不是让你背"What consumes context"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Automatic compaction
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Automatic compaction
这一段要真抓重点，通常就抓下面这块原文。
# Summary instructions
When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind themKeep context efficient
看到这里，就把"Keep context efficient"当成一件真要上手的活来看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Sessions and continuity
这一段主要是在把"Sessions and continuity"讲实，不是只摆个标题给你看。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Handle the result
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Hooks
这一段主要是在把"Hooks"讲实，不是只摆个标题给你看。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Put it all together
这一段不只是挂个标题，它是在说明"Put it all together"这一块到底负责什么。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Put it all together
"Put it all together"这一段里最要紧的原始写法在下面，先看它怎么落地。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def run_agent():
session_id = None
async for message in query(
prompt="Find and fix the bug causing test failures in the auth module",
options=ClaudeAgentOptions(
allowed_tools=[
"Read",
"Edit",
"Bash",
"Glob",
"Grep",
], # Listing tools here auto-approves them (no prompting)
setting_sources=[
"project"
], # Load CLAUDE.md, skills, hooks from current directory
max_turns=30, # Prevent runaway sessions
effort="high", # Thorough reasoning for complex debugging
),
):
# Handle the final result
if isinstance(message, ResultMessage):
session_id = message.session_id # Save for potential resumption
if message.subtype == "success":
print(f"Done: {message.result}")
elif message.subtype == "error_max_turns":
# Agent ran out of turns. Resume with a higher limit.
print(f"Hit turn limit. Resume session {session_id} to continue.")
elif message.subtype == "error_max_budget_usd":
print("Hit budget limit.")
else:
print(f"Stopped: {message.subtype}")
if message.total_cost_usd is not None:
print(f"Cost: ${message.total_cost_usd:.4f}")
asyncio.run(run_agent())Next steps
这里不是让你背"Next steps"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
照着做一遍
如果你不想来回翻，就先照这几步顺着做。
每做完一步就看一下结果，再决定要不要继续往下。
第 1 步：Handle messages
这一段要真抓重点，通常就抓下面这块原文。
from claude_agent_sdk import query, AssistantMessage, ResultMessage
async for message in query(prompt="Summarize this project"):
if isinstance(message, AssistantMessage):
print(f"Turn completed: {len(message.content)} content blocks")
if isinstance(message, ResultMessage):
if message.subtype == "success":
print(message.result)
else:
print(f"Stopped: {message.subtype}")第 2 步：Automatic compaction
这一段要真抓重点，通常就抓下面这块原文。
# Summary instructions
When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them第 3 步：Put it all together
"Put it all together"这一段里最要紧的原始写法在下面，先看它怎么落地。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def run_agent():
session_id = None
async for message in query(
prompt="Find and fix the bug causing test failures in the auth module",
options=ClaudeAgentOptions(
allowed_tools=[
"Read",
"Edit",
"Bash",
"Glob",
"Grep",
], # Listing tools here auto-approves them (no prompting)
setting_sources=[
"project"
], # Load CLAUDE.md, skills, hooks from current directory
max_turns=30, # Prevent runaway sessions
effort="high", # Thorough reasoning for complex debugging
),
):
# Handle the final result
if isinstance(message, ResultMessage):
session_id = message.session_id # Save for potential resumption
if message.subtype == "success":
print(f"Done: {message.result}")
elif message.subtype == "error_max_turns":
# Agent ran out of turns. Resume with a higher limit.
print(f"Hit turn limit. Resume session {session_id} to continue.")
elif message.subtype == "error_max_budget_usd":
print("Hit budget limit.")
else:
print(f"Stopped: {message.subtype}")
if message.total_cost_usd is not None:
print(f"Cost: ${message.total_cost_usd:.4f}")
asyncio.run(run_agent())一眼看懂这一页
先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。
How the agent loop works
|
v
这是 Core concepts 里的一摊要紧活
|
v
先弄懂，再下手文末提醒
这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。
人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。