Claude Agent SDK：让 AI 自主搜索、阅读、综合

假设你是一家科技公司的分析师，老板突然让你出一份竞品报告。你打开浏览器，搜索"AI 编程助手市场 2025"，点开十几个链接，看了三篇研报、五篇新闻、两个产品文档。两小时过去了，你还在纠结：这家公司的融资轮次到底是 B 轮还是 C 轮？那篇报道说的是 2024 年数据还是 2025 年预测？

这不是个例。PwC 2025 年的调查显示，知识工作者平均每周花 8.2 小时在信息搜集和验证上。市场分析师追踪竞品动态，法务团队监控法规更新，工程师排查 Bug 要跨文档、跨系统、跨时间线。这些任务的共同点：输入问题本身不包含答案，你得不断"看一眼再决定下一步搜什么"。

这正是 AI Agent 的理想场景。

传统自动化遵循固定流程：第一步做什么、第二步做什么，全部预设好。但研究任务不一样——你不知道该搜财报还是监管文件，直到你看完企业介绍才知道；你不知道该追踪哪个技术栈，直到你分析完产品架构才清楚。最优路径在探索中涌现，而非预先规划。

Claude Agent SDK 就是为这种场景设计的。它让代理能自主调用工具、根据发现调整策略、判断何时信息足够。几行代码，一个能搜索网络、阅读文档、综合结论的研究代理就跑起来了。

研究代理：Agent 的理想场景

两个特征让研究成为代理模式的理想用例：

信息不自包含：输入问题本身不包含答案，代理必须与外部系统（搜索引擎、数据库、API）交互。

路径动态涌现：你无法预设工作流。代理该搜财报还是监管文件，取决于对企业模式的发现。最优策略在调查中揭示。

最简实现

Claude Agent SDK 的核心是 query() 函数。几行代码创建能自主搜索网络并综合结果的研究代理：

from claude_agent_sdk import ClaudeAgentOptions, query

messages = []

async for msg in query(

prompt="研究 AI Agent 的最新趋势，给我一个简要总结和相关引用链接。",

options=ClaudeAgentOptions(

model="claude-opus-4-6",

allowed_tools=["WebSearch"]

),

):

messages.append(msg)

执行过程：

🤖 Using: WebSearch("AI agents trends 2025 latest...")

🤖 Using: WebSearch("autonomous AI agents enterprise...")

🤖 Using: WebSearch("multi-agent AI systems trends...")

🤖 Thinking...

代理自主决定搜索时机、查询内容、结果综合方式。你只需提问，它规划执行路径。

工具权限机制

allowed_tools 参数控制自主运行边界：

无状态 vs 有状态

无状态 query() 适用于： - 独立研究问题 - 并行处理多任务 - 每次查询需要全新上下文

有状态 ClaudeSDKClient 适用于： - 多轮迭代调查 - 基于先前发现深入分析 - 需要持续上下文

进阶：三步打造生产级代理

基础代理能工作，但单次查询无记忆，无法处理"找到 X，然后分析 Y"这类迭代研究。三个改进方向。

1. 添加对话记忆

from claude_agent_sdk import ClaudeSDKClient

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

model="claude-opus-4-6",

allowed_tools=["WebSearch", "Read"],

)

) as research_agent:

await research_agent.query("分析这张图表")

async for msg in research_agent.receive_response():

messages.append(msg)

await research_agent.query("基于刚才的分析，搜索验证数据")

async for msg in research_agent.receive_response():

messages.append(msg)

ClaudeSDKClient 作为上下文管理器维护对话状态，后续查询能记住前面发现。

2. 系统提示词专业化

不同研究领域有不同标准。金融分析与技术新闻摘要的严谨性不同。通过系统提示词编码研究标准：

RESEARCH_SYSTEM_PROMPT = """你是一个专注于 AI 领域的研究代理。

提供研究发现时：

- 始终包含来源 URL 作为引用

- 将引用格式化为 markdown 链接：[来源标题](URL)

- 在回复末尾汇总"来源"部分"""

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

model="claude-opus-4-6",

system_prompt=RESEARCH_SYSTEM_PROMPT,

allowed_tools=["WebSearch", "Read"],

)

) as research_agent:

...

3. 多模态研究能力

真实研究不只有文本：市场报告有图表，技术文档有图示，竞品分析需要截图对比。启用 Read 工具让 Claude 分析图像、PDF 和其他视觉内容：

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

model="claude-opus-4-6",

allowed_tools=["WebSearch", "Read"],

max_buffer_size=10 * 1024 * 1024, # 图像处理需要更大缓冲区

)

) as research_agent:

await research_agent.query("分析 research_agent/projects_claude.png")

...

图像在消息中会 base64 编码，体积显著增加。Claude Agent SDK 默认缓冲区为 1MB，处理图像时建议设为 10MB。

实战案例：图表分析 + 网络验证

完整的多模态研究流程——先分析图表，再搜索验证发现：

RESEARCH_SYSTEM_PROMPT = """你是研究代理。提供发现时：

- 始终包含来源 URL 作为引用

- 将引用格式化为 markdown 链接

- 在回复末尾汇总来源"""

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

model="claude-opus-4-6",

cwd="research_agent",

system_prompt=RESEARCH_SYSTEM_PROMPT,

allowed_tools=["WebSearch", "Read"],

max_buffer_size=10 * 1024 * 1024,

)

) as research_agent:

await research_agent.query("分析 research_agent/projects_claude.png")

async for msg in research_agent.receive_response():

print_activity(msg)

await research_agent.query("基于图表分析，搜索最新数据验证")

async for msg in research_agent.receive_response():

print_activity(msg)

代理执行流程： 1. 读取图像并分析图表 2. 识别图表类型、数据模式、关键发现 3. 搜索相关数据源验证 4. 对比发现与外部数据，生成带引用报告

打包为可复用模块

生产系统需要可复用模块。封装为独立函数：

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

RESEARCH_SYSTEM_PROMPT = """你是研究代理。

提供发现时始终包含来源 URL，格式化为 markdown 链接。"""

async def send_query(prompt: str, continue_conversation: bool = False) -> str:

"""发送研究查询，返回结果文本。"""

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

model="claude-opus-4-6",

system_prompt=RESEARCH_SYSTEM_PROMPT,

allowed_tools=["WebSearch", "Read"],

max_buffer_size=10 * 1024 * 1024,

)

) as agent:

await agent.query(prompt)

result = ""

async for msg in agent.receive_response():

if hasattr(msg, 'content'):

result += msg.content

return result

使用：

from research_agent.agent import send_query

result = await send_query("Claude Code SDK 是什么？")

result1 = await send_query("Anthropic 是什么公司？")

result2 = await send_query(

"他们有哪些产品？",

continue_conversation=True

)

架构对比

运行效果示例

研究"AI Agent 最新趋势"时的实际输出：

市场增长 - AI Agent 市场从 2023 年 37 亿增至 2025 年 73.8 亿 - 预计 2032 年达

关键趋势 1. 多代理系统崛起 - CrewAI、AutoGen、LangGraph 等框架 2. 从助手到自主决策者 - 2029 年 80% 客服问题将由自主代理解决 3. Model Context Protocol (MCP) - Anthropic 的 AI 连接标准 4. 企业分化 - 高度自动化企业领跑

来源 - McKinsey: The State of AI in 2025 (https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai) - IBM: AI Agents Expectations vs Reality (https://www.ibm.com/think/insights/ai-agents-2025-expectations-vs-reality) - PwC AI Agent Survey (https://www.pwc.com/us/en/tech-effect/ai-analytics/ai-agent-survey.html) - Gartner Hype Cycle 2025 (https://www.gartner.com/en/newsroom/press-releases/2025-08-05-gartner-hype-cycle-identifies-top-ai-innovations-in-2025)

核心要点

研究代理本质： 信息不自包含 + 路径动态涌现 = Agent 理想场景

三个关键组件：

控制能力边界

生产检查清单： - [ ] 设置 max_buffer_size 处理多模态内容 - [ ] 系统提示词强制引用格式 - [ ] 封装为可复用模块 - [ ] 添加错误处理和重试逻辑

下一步

这个基础研究代理为构建企业级多代理系统打下基础。Claude Cookbooks 仓库的后续 notebook 展示了更高级的模式：

• 幕僚长代理（01_The_chief_of_staff_agent.ipynb）- 协调多个专门代理

• 可观测性代理（02_The_observability_agent.ipynb）- 监控系统运行状态

• 站点可靠性代理（03_The_site_reliability_agent.ipynb）- 自动化运维响应

研究代理的能力——自主探索、动态规划、综合输出——是所有高级代理系统的基石。

代码来自 Anthropic Claude Cookbooks（https://github.com/anthropics/claude-cookbooks）的 claude_agent_sdk/00_The_one_liner_research_agent.ipynb。