Agent SDK
Claude Code 是个啥
Claude Code 是个啥 这一页讲的，就是 Claude Code 是个啥 这件事在 Claude Code 里到底怎么用。
页面信息
这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。
如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。
这一页先讲明白
这页主要讲 Overview：Build production AI agents with Claude Code as a library
你可以把它当成"Agent SDK"这块里专门管这一摊事的说明书。
你可以把"Overview"理解成 Agent SDK 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。
原文这页大多会按 Get started、Capabilities、Claude Code features、Compare the Agent SDK to other Claude tools 这些环节往下讲。
翻成人话，大概就是：Claude Code features
第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。
第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。
第三，照着原文这几个环节挨个过：Get started -> Capabilities -> Claude Code features -> Compare the Agent SDK to other Claude tools。像下地先看水路、再试机器、再正式开干，一步一步最稳。
原页关键片段：Documentation Index
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude reads the file, finds the bug, edits it
asyncio.run(main())原页关键片段：Get started 1
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
npm install @anthropic-ai/claude-agent-sdk原页关键片段：Get started 2
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
pip install claude-agent-sdk原页关键片段：Get started 3
先看下面这块原始片段，等会儿再回头看解释会顺得多。
export ANTHROPIC_API_KEY=your-api-key原页关键片段：Capabilities 1
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find all TODO comments and create a summary",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())原页关键片段：Capabilities 2
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def log_file_change(input_data, tool_use_id, context):
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
with open("./audit.log", "a") as f:
f.write(f"{datetime.now()}: modified {file_path}\n")
return {}
async def main():
async for message in query(
prompt="Refactor utils.py to improve readability",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())原页关键片段：Capabilities 3
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer for quality and security reviews.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())原页关键片段：Compare the Agent SDK to other Claude tools
"Compare the Agent SDK to other Claude tools"这一段里最要紧的原始写法在下面，先看它怎么落地。
# Client SDK: You implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
result = your_tool_executor(response.tool_use)
response = client.messages.create(tool_result=result, **params)
# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
print(message)Documentation Index
这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Documentation Index
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude reads the file, finds the bug, edits it
asyncio.run(main())Quickstart
看到这里，就把"Quickstart"当成一件真要上手的活来看。
Example agents
这里是样板段。重点不是全文照抄，而是学它怎么把职责、步骤和边界写清楚。
Get started
这一段就是安装 the SDK。这种地方最怕跳步骤，最好老老实实按顺序来。
如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。
Get started 1
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
npm install @anthropic-ai/claude-agent-sdkGet started 2
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
pip install claude-agent-sdkGet started 3
先看下面这块原始片段，等会儿再回头看解释会顺得多。
export ANTHROPIC_API_KEY=your-api-keyGet started 4
先看下面这块原始片段，等会儿再回头看解释会顺得多。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="What files are in this directory?",
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Capabilities
这里不是让你背"Capabilities"这个词，而是让你看它真干活时怎么使。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Capabilities 1
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find all TODO comments and create a summary",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Capabilities 2
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def log_file_change(input_data, tool_use_id, context):
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
with open("./audit.log", "a") as f:
f.write(f"{datetime.now()}: modified {file_path}\n")
return {}
async def main():
async for message in query(
prompt="Refactor utils.py to improve readability",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Capabilities 3
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer for quality and security reviews.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Capabilities 4
真到动手的时候了，下面这条直接敲一遍，看它回什么。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Open example.com and describe what you see",
options=ClaudeAgentOptions(
mcp_servers={
"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
}
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())Claude Code features
这段看着像个标题，其实是在说"Claude Code features"管到哪儿。
Compare the Agent SDK to other Claude tools
像 Compare the Agent SDK to other Claude tools 这种标题，通常就是怕你把两个看着差不多的东西混着用。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
Compare the Agent SDK to other Claude tools
"Compare the Agent SDK to other Claude tools"这一段里最要紧的原始写法在下面，先看它怎么落地。
# Client SDK: You implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
result = your_tool_executor(response.tool_use)
response = client.messages.create(tool_result=result, **params)
# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
print(message)Changelog
这一段是在说怎么看 the full changelog for SDK updates, bug fixes, and new features:。将来真出问题时，你就知道该去哪儿翻、翻到什么算正常。
Reporting bugs
这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。
Branding guidelines
这里不是让你背"Branding guidelines"这个词，而是让你看它真干活时怎么使。
看这段时要特别盯工具和权限边界，别为了省事一把全开。
License and terms
这一段是在说怎么用 of the Claude Agent SDK is governed by Anthropic’s Commercial Terms of Service, including when you use it to power products and services that you make available to your own customers and end users, except 去做 the extent a specific component or dependency is covered by a different license as indicated in that component’s LICENSE file.。看这种内容，光知道名字没用，还是得落到手上。
这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。
Next steps
这里不是让你背"Next steps"这个词，而是让你看它真干活时怎么使。
Quickstart
看到这里，就把"Quickstart"当成一件真要上手的活来看。
Example agents
这里是样板段。重点不是全文照抄，而是学它怎么把职责、步骤和边界写清楚。
TypeScript SDK
这一块主要是在说"TypeScript SDK"真到手上该怎么用，哪里最容易踩坑。
Python SDK
这一段主要是在把"Python SDK"讲实，不是只摆个标题给你看。
照着做一遍
如果你不想来回翻，就先照这几步顺着做。
每做完一步就看一下结果，再决定要不要继续往下。
第 1 步：Documentation Index
下面这块是这一段最值钱的原文样板，先对着看一眼。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude reads the file, finds the bug, edits it
asyncio.run(main())第 2 步：Get started 1
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
npm install @anthropic-ai/claude-agent-sdk第 3 步：Get started 2
这一段不是只让你理解意思，下面这条命令就是现在要跑的。
pip install claude-agent-sdk第 4 步：Get started 3
先看下面这块原始片段，等会儿再回头看解释会顺得多。
export ANTHROPIC_API_KEY=your-api-key一眼看懂这一页
先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。
Overview
|
v
这是 Agent SDK 里的一摊要紧活
|
v
先弄懂，再下手文末提醒
这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。
人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。