单次 Prompt 和 Agentic Prompt 的区别
之前几章讲的都是"单次 Prompt"：你问一个问题，AI 给一个答案，结束。
Agentic Prompt 完全不同。你给 AI 一个目标，AI 自己规划步骤、调用工具、检查结果、纠正错误，直到完成任务。
单次模式：
用户 → [Prompt] → AI → 答案
Agentic 模式：
用户 → [目标] → AI → 规划 → 工具调用 → 观察结果 → 继续/调整 → ... → 最终答案
2026 年的主流 AI 开发框架（Claude Agents SDK、LangGraph、AutoGen）都是这个模式。理解 Agentic Prompt 设计，是从"会用 AI"到"会用 AI 做产品"的关键跨越。
ReAct 模式：思考 → 行动 → 观察
ReAct 是 Agentic Prompt 的基础架构，全称 Reasoning + Acting。
核心结构：
Thought: 我需要先了解当前情况，然后决定下一步
Action: 调用工具 [tool_name]，参数是 [params]
Observation: 工具返回了 [result]
Thought: 根据结果，我需要...
Action: ...
... (循环直到完成)
Final Answer: [最终结果]
在 System Prompt 里定义 ReAct 框架
import anthropic
REACT_SYSTEM_PROMPT = """你是一个自主执行任务的 AI Agent。
完成任务时，严格按照以下格式思考和行动：
Thought: [分析当前情况，决定下一步]
Action: [工具名称]
Action Input: [工具参数，JSON 格式]
Observation: [工具返回的结果]
（重复以上循环，直到任务完成）
Final Answer: [最终答案，面向用户，简洁清晰]
可用工具：
- search_web(query: str) → 搜索网络，返回摘要
- read_file(path: str) → 读取文件内容
- write_file(path: str, content: str) → 写入文件
- run_code(code: str, lang: str) → 执行代码，返回输出
规则：
1. 每次只执行一个 Action
2. 没有足够信息时，先用工具收集信息，不要猜测
3. 遇到错误，分析原因，调整策略重试
4. 不确定的地方，优先做验证再继续
"""
client = anthropic.Anthropic()
def run_agent(user_task: str):
messages = [{"role": "user", "content": user_task}]
while True:
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
system=REACT_SYSTEM_PROMPT,
messages=messages,
)
text = response.content[0].text
# 如果 AI 给出了最终答案，结束循环
if "Final Answer:" in text:
return text.split("Final Answer:")[-1].strip()
# 否则解析 Action，执行工具，把结果加回上下文
messages.append({"role": "assistant", "content": text})
observation = execute_action(text) # 你的工具执行逻辑
messages.append({"role": "user", "content": f"Observation: {observation}"})
工具调用 Prompt：让 AI 知道何时用工具
工具调用（Function Calling / Tool Use）是 Agentic 系统的核心。写 Prompt 时，要让 AI 清楚知道：
- 有哪些工具
- 每个工具适合什么场景
- 工具用不了时怎么办
工具定义：用 Claude Tools API
tools = [
{
"name": "search_database",
"description": """搜索产品数据库，返回匹配的产品列表。
适用场景：用户询问产品信息、库存、价格时。
不适用：用户问通用知识、公司政策、操作指南。""",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索关键词，尽量具体（产品名/型号/类别）"
},
"max_results": {
"type": "integer",
"description": "返回结果数量，默认 5，最多 20",
"default": 5
}
},
"required": ["query"]
}
},
{
"name": "get_order_status",
"description": """查询订单状态。
适用场景：用户提供了订单号，询问物流/配送状态。
不适用：没有订单号时不要调用此工具，先向用户索取。""",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号，格式：ORD-XXXXXXXX"
}
},
"required": ["order_id"]
}
}
]
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "我的订单 ORD-20260415001 到哪了？"}]
)
# 处理工具调用
if response.stop_reason == "tool_use":
tool_use = next(b for b in response.content if b.type == "tool_use")
tool_result = execute_tool(tool_use.name, tool_use.input)
# 把工具结果发回，让 AI 生成最终回复
messages = [
{"role": "user", "content": "我的订单 ORD-20260415001 到哪了？"},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": str(tool_result)
}]
}
]
final_response = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
tools=tools,
messages=messages
)
工具描述的关键：要写清楚不适用的场景。AI 不知道"这个工具什么时候不该用"，你不说清楚它就会乱调用。
Reflection 模式：让 AI 自我审查
Reflection（反思）是让 AI 生成初稿 → 自我批评 → 改进输出的模式。研究表明，这个模式能把代码任务准确率从 80% 提升到 91%。
REFLECTION_SYSTEM_PROMPT = """你是一个严格的代码审查专家。
工作流程：
1. 首先写出初版代码（用 <draft> 标签包裹）
2. 然后以审查者身份批评自己的代码（用 <critique> 标签），检查：
- 是否有 bug 或边界情况遗漏
- 性能是否有明显问题
- 安全性问题（SQL 注入、XSS 等）
- 代码是否符合任务要求
3. 根据批评，写出改进版（用 <final> 标签包裹）
示例格式：
<draft>
# 初版代码...
</draft>
<critique>
问题1：没有处理空输入的情况
问题2：循环里有 N+1 查询问题
</critique>
<final>
# 修改后的代码...
</final>
"""
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
system=REFLECTION_SYSTEM_PROMPT,
messages=[{
"role": "user",
"content": "写一个 Python 函数，从 PostgreSQL 查询用户列表，支持分页和搜索"
}]
)
# 提取最终版本
import re
final_code = re.search(r'<final>(.*?)</final>', response.content[0].text, re.DOTALL)
什么时候用 Reflection：
- 生成的代码会直接上生产（质量要求高）
- 复杂的分析报告（需要自我验证逻辑）
- 写作任务（让 AI 自己检查是否偏题）
不适合 Reflection：简单查询、格式转换等任务，加 Reflection 只是浪费 token。
规划 Prompt：让 AI 先做计划再执行
对于复杂任务，让 AI 先输出计划，你审查后再执行，比直接让它闷头干好得多：
你是一个软件开发 Agent。
任务：[用户描述的需求]
第一步，先输出你的执行计划，格式如下：
## 执行计划
### 理解
[用一句话说明你理解这个任务的目标是什么]
### 步骤
1. [步骤描述] — 预期结果：[你期望得到什么]
2. [步骤描述] — 预期结果：[你期望得到什么]
...
### 风险
[可能遇到的问题，以及你的应对策略]
### 需要确认的问题
[如果有信息缺失，在这里列出，不要猜测]
---
输出计划后，等待用户确认再开始执行。
这个模式的价值：在 AI 开始做之前发现方向错误。尤其是在 AI Agent 有权限操作数据库、发邮件、提交代码的场景，先看计划再确认，避免事后无法回滚的错误。
自我纠错 Prompt：处理工具失败和意外情况
真实的 Agentic 系统一定会遇到工具调用失败、输出格式不对、API 超时等情况。在 System Prompt 里预先定义错误处理行为：
ERROR_HANDLING_PROMPT = """
遇到以下情况时，按对应策略处理：
**工具调用失败（网络错误/超时）**
→ 等待 2 秒后重试，最多重试 2 次
→ 两次都失败：告诉用户具体是什么工具失败了，建议手动操作
**工具返回了意外格式**
→ 不要假设数据结构，先用 Thought 记录你看到了什么
→ 尝试从返回值中提取你需要的信息
→ 如果确实无法解析，停下来向用户说明
**任务中途发现需要用户输入的信息**
→ 立即停下，明确列出你需要的信息，不要猜测或跳过
→ 格式：「继续任务需要以下信息：\n1. [信息名]：[用途]\n2. ...」
**发现任务可能有副作用（删除数据、发消息、扣钱等）**
→ 停下来描述你即将执行的操作和后果
→ 明确询问用户确认，不要自行判断"这应该是安全的"
"""
一个完整的 Agentic Agent 示例
把以上模式组合起来，一个实际可用的代码审查 Agent：
import anthropic
import subprocess
client = anthropic.Anthropic()
tools = [
{
"name": "read_file",
"description": "读取代码文件内容",
"input_schema": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "文件路径"}
},
"required": ["path"]
}
},
{
"name": "run_tests",
"description": "运行测试套件，返回测试结果。只有当代码改动完成后才调用。",
"input_schema": {
"type": "object",
"properties": {
"test_command": {"type": "string", "description": "测试命令，如 pytest tests/"}
},
"required": ["test_command"]
}
}
]
AGENT_SYSTEM = """你是一个代码审查 Agent。
任务流程：
1. 读取用户指定的文件
2. 分析代码质量：安全性、性能、可维护性
3. 如果有测试，运行测试验证现有功能
4. 输出审查报告
审查报告格式：
## 总体评分：X/10
## 严重问题（必须修复）
- [问题] → [修复建议 + 代码示例]
## 警告（建议修复）
- [问题] → [建议]
## 亮点
- [代码做得好的地方]
遇到工具调用失败，最多重试 1 次，失败后在报告里注明"[工具名] 调用失败，以下分析基于静态审查"。
"""
def execute_tool(name: str, inputs: dict) -> str:
if name == "read_file":
try:
with open(inputs["path"]) as f:
return f.read()
except FileNotFoundError:
return f"错误：文件 {inputs['path']} 不存在"
elif name == "run_tests":
result = subprocess.run(
inputs["test_command"].split(),
capture_output=True, text=True, timeout=60
)
return result.stdout + result.stderr
def code_review_agent(file_path: str):
messages = [{"role": "user", "content": f"请审查 {file_path} 这个文件"}]
while True:
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
system=AGENT_SYSTEM,
tools=tools,
messages=messages
)
if response.stop_reason == "end_turn":
return response.content[0].text
if response.stop_reason == "tool_use":
messages.append({"role": "assistant", "content": response.content})
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
messages.append({"role": "user", "content": tool_results})
# 使用
report = code_review_agent("src/api/auth.py")
print(report)
Agentic Prompt 的三条核心原则
1. 定义好边界，不要定义每一步
好的 Agent System Prompt 告诉 AI 目标、工具、错误处理规则，但不把每一步都写死。写死了等于你在替 AI 思考，失去了 Agent 的意义。
2. 让 AI 在不确定时停下来问，而不是猜
# 在 System Prompt 里加上这段
"""
当你需要做一个可能不可逆的操作，或者任务信息不完整时：
停下来，用 <clarification> 标签列出你需要的信息，等用户回复。
不要猜测，不要跳过，不要假设。
"""
3. 给 AI 一个"放弃"的出口
真实环境里有些任务 AI 无法完成（权限不够、信息缺失、超出能力范围）。要在 Prompt 里允许 AI 说"我做不了"：
如果你判断这个任务超出了你的能力范围，或者继续会有未知风险，
直接说：「这个任务我无法自主完成，原因是：[原因]，建议：[替代方案]」
不要强行完成一个你没有把握的任务。
没有这个出口，AI 会在卡住时乱猜，产生你不可预知的结果。
