入门篇：两小时，一行代码，搞定老板的AI汇报

这是「从 Demo 到生产：老张的 Agent 进阶之路」系列的第一篇。如果你也是 AI 新手但需要快速产出，这篇文章适合你。

周五下午四点，老张正准备收拾东西，王总突然出现在门口。

「老张啊，下周一例会给我讲讲 AI 能帮公司做什么。不用太复杂，能演示就行。」

老张心里咯噔一下。他对 AI 的了解仅限于「好像有个 ChatGPT」，要周一交出像样的演示？

他打开电脑，搜索「Claude Agent」，跳出来一堆文档：API 文档、SDK 参考、Cookbook 示例……四十分钟后，他找到了一个叫「One-Liner Research Agent」的东西。

两小时后，他做了一个竞品研究 Agent——能自动搜索行业信息，整理成报告。

周一早上，演示成功。王总问：「能做得更智能吗？能记住我们公司的偏好吗？」

这篇文章，就是老张那两小时学到的全部。

老张的挑战：用最小成本做个能演示的 Agent

老张的需求很明确：

核心任务：做一个竞品研究 Agent，自动搜集公司所在行业的竞品信息

约束条件： - 时间：周末两天（实际只用了两小时） - 预算：零（先用免费额度试水） - 技术基础：会 Python，但没用过 Claude API

成功标准：周一早会能演示，王总看到实际效果

老张的直觉是：先跑起来，再想优化。这种务实态度恰恰是 Agent 开发的正确姿势——从最小可行版本开始，逐步迭代。

第一行代码：query() 启动 Agent

老张找到的「One-Liner Research Agent」来自 Anthropic 官方 Cookbook。核心代码只有几行：

from claude_agent_sdk import ClaudeAgentOptions, query

async for msg in query(

prompt="研究智能制造行业的竞争格局",

options=ClaudeAgentOptions(

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

allowed_tools=["WebSearch"]

),

):

print(msg)

这行代码做了什么？

┌─────────────┐ ┌─────────────┐ ┌─────────────┐

│ 你提问 │────▶│ Claude API │────▶│ WebSearch │

└─────────────┘ └─────────────┘ └─────────────┘

│

▼

┌─────────────┐

│ 返回结果 │

└─────────────┘

Claude Agent SDK 的核心概念：

一次性执行，无状态

老张惊讶于它的简单——没有复杂的状态管理，没有工具注册，甚至不需要写「如果搜到 A 就做 B」的逻辑。Claude 自己决定搜什么、怎么综合。

这就是 Agent 和普通 API 调用的本质区别：你只给目标，AI 自己规划执行路径。

WebSearch：Agent 的眼睛

老张运行代码，看到终端输出：

🤖 Using: WebSearch("智能制造 竞争格局 2025")

🤖 Using: WebSearch("industrial automation market leaders China")

🤖 Thinking...

🤖 Found 3 major competitors...

WebSearch 工具的工作方式：

1. Claude 决定搜索时机和关键词

2. 自动执行搜索

3. 阅读搜索结果

4. 判断是否需要更多信息

5. 循环直到满意为止

老张注意到一个细节：他只给了中文 prompt，但 Claude 自己判断需要补充英文搜索。这种「自主决策」正是 Agent 的核心价值。

工具权限的边界：

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

allowed_tools 是安全边界。白名单里的工具 Claude 可以自由使用，其他工具要么需要人工批准，要么直接不可用。

异步迭代：处理响应流

老张的第一版代码直接打印消息，输出很乱。他改进了一下：

async for msg in query(...):

print(msg)

响应流中包含多种消息类型：文本输出、工具调用、工具结果。异步迭代的好处是实时看到 Agent 的思考过程——老张能观察 Claude 先搜什么、怎么判断、是否需要补充搜索。这对调试和理解 Agent 行为至关重要。

System Prompt：定制 Agent 角色

老张发现，通用搜索结果不够聚焦。他想让 Agent 更了解公司背景：

options=ClaudeAgentOptions(

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

allowed_tools=["WebSearch"],

system_prompt="""

你是一家中型制造企业的市场研究助手。

公司主要产品是工业自动化设备，客户集中在华东地区。

研究时请特别关注：

1. 国内竞争对手的产品定位

2. 价格区间和技术路线

3. 最近的融资或并购动态

"""

)

System Prompt 的作用：

┌─────────────────────────────────────────┐

│ System Prompt │

│ (Agent 的角色、背景、偏好) │

└─────────────────┬───────────────────────┘

│

▼

┌─────────────────────────────────────────┐

│ User Prompt │

│ (用户的具体任务) │

└─────────────────────────────────────────┘

老张意识到，这就是 Agent 的「人设」。好的 System Prompt 能让 Agent 更聚焦、更专业，避免泛泛而谈。

一次查询 vs 多轮对话

老张的 Demo 需要一个改进：支持追问。

「王总看完报告，想深入了解某个竞品，Agent 得能记住上下文。」

这时 query() 不够用了——它是无状态的，每次查询都是全新开始。老张换成了 ClaudeSDKClient：

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

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

allowed_tools=["WebSearch"]

)

) as agent:

await agent.query("分析智能制造行业竞争格局")

async for msg in agent.receive_response():

pass

await agent.query("重点关注华南地区的竞争对手")

async for msg in agent.receive_response():

pass

有状态 vs 无状态的对比：

老张最终选了 ClaudeSDKClient——Demo 需要演示追问场景。

周一演示：效果超出预期

老张的 Demo 很简单：

1. 输入：「研究我们行业的主要竞争对手」

2. Agent 自动搜索、整理、生成报告

3. 追问：「某公司的技术路线有什么特点？」

4. Agent 基于上下文深入分析

王总看完，问：「这个 Agent 能记住我们公司的行业特点吗？」

老张答：「目前每次重启就忘了，但我可以让它记住。」

王总：「好，下周演示升级版。」

老张学到了什么

Agent 开发的正确姿势：

1. 从 query() 开始：一行代码跑起来，验证可行性

2. 用好 allowed_tools：只给 Agent 真正需要的工具权限

3. 异步迭代观察：实时看 Agent 的决策过程，方便调试

4. System Prompt 定角色：让 Agent 更专业、更聚焦

5. 按需选择状态管理：单次查询用 query()，多轮对话用 Client

下一步的问题：

• 每次重启都丢记忆，怎么解决？

• 高管要用，怎么加审计日志？

• 多人协作，怎么协调多个 Agent？

这些问题，进阶篇会解答。

附：完整 Demo 代码

import asyncio

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def demo():

async with ClaudeSDKClient(

options=ClaudeAgentOptions(

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

allowed_tools=["WebSearch"],

system_prompt="""

你是一家中型制造企业的市场研究助手。

公司主营工业自动化设备，客户集中在华东地区。

"""

)

) as agent:

await agent.query("分析智能制造行业的竞争格局")

async for msg in agent.receive_response():

print(msg)

print("\n--- 深入分析 ---\n")

await agent.query("重点关注注册资本 5000 万以上的企业")

async for msg in agent.receive_response():

print(msg)

if __name__ == "__main__":

asyncio.run(demo())

运行前需要设置环境变量：

export ANTHROPIC_API_KEY=your_key_here

下一篇：从工具人到 Chief of Staff —— 给 Agent 装上记忆和审计

老张的 Demo 通过了，但王总提出了新要求：Agent 要能记住公司背景，要有审计日志。这意味着老张需要学习 CLAUDE.md 记忆机制、Plan Mode、Hooks 审计……

进阶篇，我们将看到老张如何把一个「能用」的 Demo 变成「可靠」的产品。