阶段4(上):LangGraph、Function Calling、MCP(SDK 2.x)、Agent 评测与运维、Agent 设计专题;run_examples 设置 RUN_EXAMPLES=1
This commit is contained in:
1 parent
6650f7eb6d
commit
caaec830b3
38 files changed
+3515
-64
No files matched your search
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: ai.agent-design.react-planning
|
||||
title: Agent 推理模式:ReAct、Plan-and-Execute、反思和 Agentic RAG
|
||||
type: lesson
|
||||
domain: ai
|
||||
stack: [agent-design]
|
||||
tags: [ReAct, Plan-and-Execute, 规划, 反思, Agentic RAG, 工作流 vs Agent]
|
||||
level: intermediate
|
||||
prerequisites: [ai.function-calling.tool-loop]
|
||||
est_hours: 3
|
||||
related: [ai.agent-design.context-skills-multiagent, ai.langgraph.state-graph, ai.agent-design.interview]
|
||||
week: [10, 11]
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Agent 推理模式:ReAct、Plan-and-Execute、反思和 Agentic RAG
|
||||
|
||||
## 解释说明
|
||||
|
||||
### 先问:真的需要 Agent 吗?
|
||||
|
||||
| 形态 | 特点 | 适合 |
|
||||
| --- | --- | --- |
|
||||
| 单次调用 | 一个提示词一次输出 | 分类、提取、改写 |
|
||||
| **工作流(Workflow)** | 步骤由代码固定,模型只完成其中的环节 | 流程明确的业务:工单分类 → 起草 → 审批 |
|
||||
| **Agent** | 模型自己决定下一步做什么、调用什么工具、何时结束 | 步骤不固定、需要探索的任务:排查问题、调研、复杂查询 |
|
||||
|
||||
企业里大多数需求用工作流就够了,更可控、更便宜、更好评测。Agent 用在确实需要灵活性的地方,并且要有步数、预算、权限的边界。面试时能说出这个判断,比背模式名更重要。
|
||||
|
||||
### 常见模式
|
||||
|
||||
| 模式 | 做法 | 优点 | 缺点 |
|
||||
| --- | --- | --- | --- |
|
||||
| **ReAct**(推理 + 行动) | 循环:思考 → 调用工具 → 观察结果 → 再思考,直到给出答案 | 简单通用,现代工具调用 Agent 基本都是这个循环 | 每步都调用大模型,长任务容易跑偏 |
|
||||
| **Plan-and-Execute**(先规划后执行) | 先生成完整计划(步骤列表),再逐步执行;失败时把错误反馈给规划器重新规划 | 全局视角,步骤可展示给用户确认,执行步骤可以用便宜模型 | 计划可能不切实际,需要重新规划机制 |
|
||||
| **反思(Reflection)** | 生成后让模型(或另一个模型)按标准检查并修改 | 提升质量 | 成本和延迟翻倍;检查标准要明确 |
|
||||
| **Agentic RAG** | 由 Agent 决定是否检索、改写查询、多次检索、选择数据源、检查答案是否有依据 | 能处理多跳、模糊问题 | 延迟高,必须有最大步数 |
|
||||
|
||||
### 规划的工程要点
|
||||
|
||||
- 计划用**结构化输出**(步骤列表:工具、参数、依赖),而不是自由文本。
|
||||
- 每一步有状态(待执行 / 完成 / 失败),可展示、可恢复(用 LangGraph 检查点)。
|
||||
- 失败时把**具体错误**反馈给规划器;设置最大重新规划次数,超过后转人工。
|
||||
- 有副作用的步骤在执行前让用户确认计划。
|
||||
|
||||
## 案例
|
||||
|
||||
运营人员说“生成 9 月各大区销售报表并发给运营组”。Plan-and-Execute:规划出“查询销售数据 → 生成图表 → 发送”三步并展示给用户;第一次查询因为缺少月份参数失败,错误反馈给规划器后修正参数,第二次执行成功。整个过程每一步的状态都在界面上可见。
|
||||
|
||||
## 代码示例
|
||||
|
||||
完整可运行版本:[examples/agent-patterns/patterns.py](examples/agent-patterns/patterns.py)。Plan-and-Execute 核心:
|
||||
|
||||
```python
|
||||
def plan_and_execute(goal: str, max_replans: int = 2):
|
||||
log, feedback = [], None
|
||||
for attempt in range(max_replans + 1):
|
||||
steps = plan(goal, feedback) # 真实项目:大模型输出结构化计划
|
||||
for s in steps:
|
||||
s.result = TOOLS[s.tool](s.args)
|
||||
if "error" in s.result:
|
||||
s.status = "failed"
|
||||
feedback = f"{s.tool} 失败:{s.result['error']}" # 具体错误反馈给规划器
|
||||
break
|
||||
s.status = "done"
|
||||
else:
|
||||
return steps, log # 全部成功
|
||||
return steps, log + ["超过最大重新规划次数,转人工"]
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
第 1 次规划:['query_sales', 'make_chart', 'send_report']
|
||||
query_sales 失败:缺少 month 参数
|
||||
第 2 次规划:['query_sales', 'make_chart', 'send_report']
|
||||
最终步骤状态: [('query_sales', 'done'), ('make_chart', 'done'), ('send_report', 'done')]
|
||||
```
|
||||
|
||||
## 易错点
|
||||
|
||||
- 所有需求都做成 Agent:流程固定的用工作流。
|
||||
- 没有最大步数 / 最大重新规划次数,失败时无限循环、成本失控。
|
||||
- 计划是自由文本,无法校验和展示。
|
||||
- 反思步骤没有明确标准(“检查一下有没有问题”),模型只会说“没问题”。
|
||||
- 只测最终答案,不测中间过程(工具调用序列、步数)。
|
||||
|
||||
## 面试常问
|
||||
|
||||
- ReAct 是什么?和 Plan-and-Execute 有什么区别?
|
||||
- 工作流和 Agent 怎么选?
|
||||
- Agentic RAG 和普通 RAG 的区别?
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
id: ai.agent-design.context-skills-multiagent
|
||||
title: 上下文工程、Skills、多 Agent 和 A2A
|
||||
type: lesson
|
||||
domain: ai
|
||||
stack: [agent-design]
|
||||
tags: [上下文工程, Context Engineering, Skills, 多 Agent, Supervisor, Handoff, A2A]
|
||||
level: advanced
|
||||
prerequisites: [ai.agent-design.react-planning]
|
||||
est_hours: 3.5
|
||||
related: [ai.prompt-engineering.index, ai.mcp.protocol-server, ai.ai-coding.index, ai.agent-design.interview]
|
||||
week: [11, 13]
|
||||
order: 2
|
||||
---
|
||||
|
||||
# 上下文工程、Skills、多 Agent 和 A2A
|
||||
|
||||
> Skills、A2A 都是 2025 年之后快速发展的概念,规范和各产品的支持情况以官方文档为准。
|
||||
|
||||
## 解释说明
|
||||
|
||||
### 上下文工程(Context Engineering)
|
||||
|
||||
提示词工程关注“怎么写指令”,上下文工程关注**每一次调用时,模型的上下文窗口里放什么**:系统提示词、工具定义、检索结果、对话历史、记忆、工具返回、当前任务状态。Agent 效果不好,很多时候不是模型不行,而是上下文里缺了关键信息,或者塞了太多无关内容。
|
||||
|
||||
| 手段 | 说明 |
|
||||
| --- | --- |
|
||||
| 选择(Select) | 只放相关的:检索结果精选、按任务挑选工具子集、按需加载技能 |
|
||||
| 压缩(Compress) | 历史对话摘要、工具结果只保留需要的字段 |
|
||||
| 隔离(Isolate) | 子任务交给子 Agent,在独立的上下文中完成,只把结论返回 |
|
||||
| 外部化(Write) | 长期信息写进文件 / 记忆库 / 状态,需要时再读取 |
|
||||
|
||||
### Skills(技能)
|
||||
|
||||
把某类任务的说明、规范、脚本打包成一个目录(例如 `SKILL.md` + 辅助文件),系统提示词里只放每个技能的**名字和一句话描述**,模型判断需要时再加载全文——这叫**渐进式披露**,可以在不撑爆上下文的前提下给 Agent 很多“专业知识”。Claude Code 等 AI 编程工具已经支持这种形式;团队也可以用它沉淀开发工作流(见 [AI 编程专题](../ai-coding/index.md))。
|
||||
|
||||
### 多 Agent
|
||||
|
||||
| 模式 | 做法 | 适合 |
|
||||
| --- | --- | --- |
|
||||
| Supervisor(主管) | 一个主 Agent 分派任务给多个专职子 Agent,汇总结果 | 任务可拆分、子任务独立 |
|
||||
| Handoff(转交) | 当前 Agent 把对话转交给更合适的 Agent | 客服分流(售前 → 售后 → 技术) |
|
||||
| 流水线 | 固定顺序:研究 → 写作 → 审校 | 内容生产 |
|
||||
|
||||
多 Agent 的代价:调用次数多、成本高、Agent 之间信息传递会丢失细节、更难调试。**先用单 Agent + 好的工具,确实需要上下文隔离或专业分工时再拆。**
|
||||
|
||||
### A2A(Agent2Agent 协议)
|
||||
|
||||
MCP 解决“Agent 怎么调用工具”,A2A 解决“**不同团队 / 不同框架的 Agent 之间怎么协作**”。核心概念:Agent Card(描述 Agent 的能力、地址、鉴权方式)、Task(有状态的任务:已提交、处理中、需要输入、完成、失败等)、Message / Artifact(消息和产出物),基于 HTTP + JSON-RPC,支持流式更新。了解即可,面试时能说清和 MCP 的区别。
|
||||
|
||||
## 案例
|
||||
|
||||
一个企业助手接入了 40 个工具和 6 份业务规范,系统提示词超过 2 万 token,模型经常选错工具。改造:
|
||||
|
||||
1. 规范改成 Skills,系统提示词只保留索引,按需加载;
|
||||
2. 按意图把工具分组,每次只给相关的 8 个;
|
||||
3. 报表类任务交给“数据分析子 Agent”,它在自己的上下文里多轮查询,只把结论和图表返回;
|
||||
4. 长对话超过预算时压缩早期内容。
|
||||
|
||||
提示词长度降到 5000 token 左右,工具选择错误明显减少(用评测集验证)。
|
||||
|
||||
## 代码示例
|
||||
|
||||
[examples/agent-patterns/patterns.py](examples/agent-patterns/patterns.py) 中的 Skills 渐进式加载和上下文预算:
|
||||
|
||||
```python
|
||||
def skills_index(skills):
|
||||
"""放进系统提示词的只有名字和描述。"""
|
||||
return "\n".join(f"- {s.name}: {s.description}" for s in skills)
|
||||
|
||||
|
||||
skill = pick_skill("我上周买的耳机想退款,800 元", skills) # 真实项目由模型决定加载哪个
|
||||
context.append(skill.body()) # 需要时才加载全文
|
||||
|
||||
|
||||
@dataclass
|
||||
class Context:
|
||||
system: str
|
||||
budget: int
|
||||
keep_recent: int = 4
|
||||
...
|
||||
def add(self, role, text):
|
||||
self.messages.append((role, text))
|
||||
while self.size() > self.budget and len(self.messages) > self.keep_recent:
|
||||
old = self.messages[: -self.keep_recent]
|
||||
self.messages = self.messages[-self.keep_recent:]
|
||||
self.summary = summarize(self.summary, old) # 早期对话压缩成摘要
|
||||
```
|
||||
|
||||
技能文件示例:[skills/refund-policy/SKILL.md](examples/agent-patterns/skills/refund-policy/SKILL.md)。
|
||||
|
||||
## 易错点
|
||||
|
||||
- 把所有规范、所有工具都塞进系统提示词。
|
||||
- 摘要丢失了关键事实(订单号、用户已确认的选择):摘要要求明确保留哪些信息,并用评测验证。
|
||||
- 多 Agent 之间只传结论不传依据,出错后无法追溯。
|
||||
- 为了“看起来高级”上多 Agent,实际效果和成本都不如单 Agent。
|
||||
- 混淆 MCP 和 A2A:一个是 Agent 与工具,一个是 Agent 与 Agent。
|
||||
|
||||
## 面试常问
|
||||
|
||||
- 什么是上下文工程?和提示词工程有什么区别?
|
||||
- 工具很多时怎么办?
|
||||
- 什么时候需要多 Agent?有什么代价?
|
||||
- A2A 和 MCP 的区别?
|
||||
@@ -0,0 +1,146 @@
|
||||
# 只用标准库
|
||||
"""三个 Agent 设计模式的最小实现(离线可运行):
|
||||
|
||||
1. Plan-and-Execute + 失败重新规划
|
||||
2. Skills 渐进式加载:启动时只把技能的名字和描述放进上下文,需要时再加载全文
|
||||
3. 上下文预算:超过预算时把早期对话压缩成摘要,保留系统提示词和最近几轮
|
||||
|
||||
模型部分用规则模拟,接口形状和真实做法一致;真实项目中 plan / summarize 由大模型完成。
|
||||
运行:python patterns.py
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
|
||||
# ---------------- 1. Plan-and-Execute ----------------
|
||||
TOOLS = {
|
||||
"query_sales": lambda a: {"rows": [("华北", 120), ("华东", 200)]} if a.get("month") else {"error": "缺少 month 参数"},
|
||||
"make_chart": lambda a: {"chart": f"bar({len(a['rows'])} bars)"},
|
||||
"send_report": lambda a: {"sent_to": a["to"]},
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class Step:
|
||||
tool: str
|
||||
args: dict
|
||||
status: str = "pending" # pending / done / failed
|
||||
result: dict | None = None
|
||||
|
||||
|
||||
def plan(goal: str, feedback: str | None = None) -> list[Step]:
|
||||
"""规划器(真实项目中由大模型输出结构化计划)。收到失败反馈时修正计划。"""
|
||||
month = re.search(r"(\d{4}-\d{2})", goal)
|
||||
args = {"month": month.group(1)} if (month and feedback) else {}
|
||||
return [Step("query_sales", args), Step("make_chart", {}), Step("send_report", {"to": "ops@example.com"})]
|
||||
|
||||
|
||||
def plan_and_execute(goal: str, max_replans: int = 2) -> tuple[list[Step], list[str]]:
|
||||
log, feedback = [], None
|
||||
for attempt in range(max_replans + 1):
|
||||
steps = plan(goal, feedback)
|
||||
log.append(f"第 {attempt + 1} 次规划:{[s.tool for s in steps]}")
|
||||
ctx: dict = {}
|
||||
for s in steps:
|
||||
args = {**s.args, **({"rows": ctx["rows"]} if s.tool == "make_chart" else {})}
|
||||
s.result = TOOLS[s.tool](args)
|
||||
if "error" in s.result:
|
||||
s.status = "failed"
|
||||
feedback = f"{s.tool} 失败:{s.result['error']}"
|
||||
log.append(feedback)
|
||||
break
|
||||
s.status = "done"
|
||||
ctx.update(s.result)
|
||||
else:
|
||||
return steps, log
|
||||
return steps, log + ["超过最大重新规划次数,转人工"]
|
||||
|
||||
|
||||
# ---------------- 2. Skills 渐进式加载 ----------------
|
||||
@dataclass
|
||||
class Skill:
|
||||
name: str
|
||||
description: str
|
||||
path: Path
|
||||
|
||||
def body(self) -> str:
|
||||
text = self.path.read_text(encoding="utf-8")
|
||||
return text.split("---", 2)[2].strip() # 去掉 frontmatter
|
||||
|
||||
|
||||
def discover_skills(root: Path) -> list[Skill]:
|
||||
skills = []
|
||||
for f in sorted(root.glob("*/SKILL.md")):
|
||||
meta = dict(re.findall(r"^(name|description):\s*(.+)$", f.read_text(encoding="utf-8"), re.M))
|
||||
skills.append(Skill(meta["name"], meta["description"], f))
|
||||
return skills
|
||||
|
||||
|
||||
def skills_index(skills: list[Skill]) -> str:
|
||||
"""放进系统提示词的只有这一小段索引。"""
|
||||
return "\n".join(f"- {s.name}: {s.description}" for s in skills)
|
||||
|
||||
|
||||
def pick_skill(question: str, skills: list[Skill]) -> Skill | None:
|
||||
"""真实项目中由模型根据索引决定加载哪个技能(或通过一个 load_skill 工具)。"""
|
||||
keywords = {"refund-policy": ["退款", "退货"], "sql-report": ["统计", "报表"]}
|
||||
return next((s for s in skills if any(k in question for k in keywords.get(s.name, []))), None)
|
||||
|
||||
|
||||
# ---------------- 3. 上下文预算 ----------------
|
||||
def n_tokens(text: str) -> int:
|
||||
return len(text) # 粗略估算:中文约 1 字 1 token;真实项目用模型的分词器
|
||||
|
||||
|
||||
@dataclass
|
||||
class Context:
|
||||
system: str
|
||||
budget: int
|
||||
keep_recent: int = 4
|
||||
messages: list[tuple[str, str]] = field(default_factory=list)
|
||||
summary: str = ""
|
||||
|
||||
def add(self, role: str, text: str) -> None:
|
||||
self.messages.append((role, text))
|
||||
while self.size() > self.budget and len(self.messages) > self.keep_recent:
|
||||
old = self.messages[: len(self.messages) - self.keep_recent]
|
||||
self.messages = self.messages[len(self.messages) - self.keep_recent:]
|
||||
self.summary = summarize(self.summary, old)
|
||||
|
||||
def size(self) -> int:
|
||||
return n_tokens(self.system) + n_tokens(self.summary) + sum(n_tokens(t) for _, t in self.messages)
|
||||
|
||||
def render(self) -> list[tuple[str, str]]:
|
||||
head = [("system", self.system)] + ([("system", "之前对话摘要:" + self.summary)] if self.summary else [])
|
||||
return head + self.messages
|
||||
|
||||
|
||||
def summarize(prev: str, msgs: list[tuple[str, str]]) -> str:
|
||||
"""真实项目中由模型生成摘要,要求保留:用户目标、已确认的事实、未完成事项。"""
|
||||
facts = [t for r, t in msgs if r == "user" and re.search(r"\d|地址|改", t)]
|
||||
if not facts:
|
||||
return prev
|
||||
return (prev + ";" if prev else "") + "用户提供的信息:" + ";".join(facts)[:60]
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
steps, log = plan_and_execute("生成 2026-09 各大区销售报表并发给运营")
|
||||
print("\n".join(log))
|
||||
print("最终步骤状态:", [(s.tool, s.status) for s in steps])
|
||||
assert [s.status for s in steps] == ["done", "done", "done"] and len(log) == 3
|
||||
|
||||
skills = discover_skills(Path(__file__).parent / "skills")
|
||||
print("系统提示词中的技能索引:\n" + skills_index(skills))
|
||||
s = pick_skill("我上周买的耳机想退款,800 元", skills)
|
||||
print("按需加载技能:", s.name, "->", s.body().splitlines()[0])
|
||||
assert s.name == "refund-policy" and "500" in s.body()
|
||||
|
||||
ctx = Context(system="你是售后助手。", budget=40)
|
||||
for i, t in enumerate(["我的订单号是 A1001", "好的", "收货地址改到上海", "嗯",
|
||||
"什么时候发货", "预计明天", "能开发票吗", "可以"]):
|
||||
ctx.add("user" if i % 2 == 0 else "assistant", t)
|
||||
print("压缩后上下文:", ctx.render())
|
||||
assert ctx.size() <= 40 or len(ctx.messages) == ctx.keep_recent
|
||||
assert "A1001" in ctx.summary
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: refund-policy
|
||||
description: 处理退款、退货、换货相关的问题时使用。包含退款规则、审批阈值和回复模板。
|
||||
---
|
||||
|
||||
# 退款处理规则
|
||||
|
||||
1. 签收 7 天内无理由退货;超过 7 天只处理质量问题。
|
||||
2. 退款金额 >= 500 元需要主管审批,先告知用户“已提交审批”。
|
||||
3. 不承诺具体到账时间,只说明“原路退回,以支付渠道为准”。
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
name: sql-report
|
||||
description: 用户要求统计数据、生成报表或查询数据库时使用。包含可用的表、只读查询规范。
|
||||
---
|
||||
|
||||
# 报表查询规范
|
||||
|
||||
- 只允许 SELECT;必须带时间范围条件;单次最多返回 1000 行。
|
||||
- 订单表 orders(id, user_id, amount, status, created_at)。
|
||||
@@ -0,0 +1,29 @@
|
||||
# requires: pytest
|
||||
from pathlib import Path
|
||||
|
||||
import patterns as p
|
||||
|
||||
|
||||
def test_replan_after_failure():
|
||||
steps, log = p.plan_and_execute("生成 2026-09 报表")
|
||||
assert "query_sales 失败" in log[1] and all(s.status == "done" for s in steps)
|
||||
|
||||
|
||||
def test_give_up_after_max_replans():
|
||||
steps, log = p.plan_and_execute("生成报表(没有月份)", max_replans=1)
|
||||
assert log[-1].startswith("超过最大重新规划次数")
|
||||
|
||||
|
||||
def test_skill_index_is_small_and_body_loaded_on_demand():
|
||||
skills = p.discover_skills(Path(p.__file__).parent / "skills")
|
||||
idx = p.skills_index(skills)
|
||||
assert "500" not in idx and len(skills) == 2 # 索引里没有技能全文
|
||||
assert p.pick_skill("帮我统计上月订单", skills).name == "sql-report"
|
||||
assert p.pick_skill("今天天气", skills) is None
|
||||
|
||||
|
||||
def test_context_keeps_recent_and_summary():
|
||||
ctx = p.Context(system="s", budget=20, keep_recent=2)
|
||||
for t in ["订单 A1", "好", "地址 上海 1 号", "嗯", "发票", "可以"]:
|
||||
ctx.add("user", t)
|
||||
assert len(ctx.messages) == 2 and "A1" in ctx.summary
|
||||
@@ -1,15 +1,45 @@
|
||||
---
|
||||
id: ai.agent-design.index
|
||||
title: Agent 设计:规划、上下文工程与多 Agent
|
||||
title: Agent 设计
|
||||
type: index
|
||||
domain: ai
|
||||
stack: [agent-design]
|
||||
tags: []
|
||||
tags: [ReAct, 规划, 上下文工程, Skills, 多 Agent, A2A, Agentic RAG]
|
||||
week: [10, 11, 13]
|
||||
---
|
||||
|
||||
# Agent 设计:规划、上下文工程与多 Agent
|
||||
# Agent 设计
|
||||
|
||||
ReAct、Planning、Context Engineering、Skills、多 Agent 与 A2A、Agentic RAG。
|
||||
Agent 岗位面试必问的设计问题:什么时候用 Agent、ReAct 和规划、上下文工程、Skills、多 Agent 和 A2A、Agentic RAG。BOSS直聘 2026-10-23 的调研中,约 22 个岗位要求 Agent 开发经验,其中不少明确列出了这些概念。
|
||||
|
||||
> 本专题建设中:课程、企业场景、面试题和示例代码会陆续补充。
|
||||
## 学习路线
|
||||
|
||||
| 顺序 | 课程 | 级别 | 预计 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | [Agent 推理模式:ReAct、Plan-and-Execute、反思和 Agentic RAG](01-react-planning.md) | 进阶 | 3 小时 |
|
||||
| 2 | [上下文工程、Skills、多 Agent 和 A2A](02-context-skills-multiagent.md) | 高级 | 3.5 小时 |
|
||||
|
||||
## 企业场景
|
||||
|
||||
- [运营报表 Agent:规划、只读 SQL 工具、结构化输出和任务进度](scenarios/report-agent.md)
|
||||
|
||||
## 面试题
|
||||
|
||||
- [Agent 设计面试题](interview.md)
|
||||
|
||||
## 示例代码
|
||||
|
||||
- [examples/agent-patterns](examples/agent-patterns/):Plan-and-Execute + 失败重新规划、Skills 渐进式加载(含两个 `SKILL.md` 示例)、上下文预算和摘要压缩(只用标准库,带测试)
|
||||
|
||||
## 在 16 周计划中
|
||||
|
||||
- [第 10 周](../../../plan/week10-agent-m1-tools-mcp.md)、[第 11 周](../../../plan/week11-agent-m2-langgraph.md)、[第 13 周](../../../plan/week13-agent-m4-eval-lowcode.md)
|
||||
|
||||
## 官方资料
|
||||
|
||||
概念发展很快,以官方文档为准:
|
||||
|
||||
- Anthropic《Building effective agents》:https://www.anthropic.com/engineering/building-effective-agents
|
||||
- LangGraph 多 Agent:https://docs.langchain.com/oss/python/langchain/multi-agent
|
||||
- Agent Skills:https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview
|
||||
- A2A 协议:https://a2a-protocol.org/
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: ai.agent-design.interview
|
||||
title: Agent 设计面试题
|
||||
type: interview
|
||||
domain: ai
|
||||
stack: [agent-design]
|
||||
tags: [ReAct, 规划, 上下文工程, 多 Agent, A2A, 面试]
|
||||
level: advanced
|
||||
related: [ai.agent-design.react-planning, ai.agent-design.context-skills-multiagent]
|
||||
week: [11, 13, 16]
|
||||
---
|
||||
|
||||
# Agent 设计面试题
|
||||
|
||||
## 基础
|
||||
|
||||
### 【基础】什么是 Agent?和普通的大模型调用有什么区别?
|
||||
|
||||
**参考答案**:Agent 是由大模型决定执行步骤的系统:根据目标和当前观察,选择调用工具、获取结果、继续决策,直到完成。普通调用是单次输入输出;工作流是代码固定步骤、模型完成其中的环节。Agent 更灵活,但更难控制和评测。
|
||||
|
||||
**追问**:你的项目为什么用 Agent 而不是工作流?→ 按实际说明哪些环节步骤不固定、需要模型决策;哪些环节固定成了工作流。
|
||||
|
||||
### 【基础】ReAct 是什么?
|
||||
|
||||
**参考答案**:Reasoning + Acting:模型交替进行推理和行动(调用工具),根据工具返回的观察结果继续推理,直到得出答案。现在基于原生工具调用的 Agent 循环就是 ReAct 的工程实现。
|
||||
|
||||
**追问**:ReAct 的缺点?→ 每一步都要调用模型,长任务成本高、容易偏离目标;需要最大步数和更好的规划。
|
||||
|
||||
### 【基础】什么是上下文工程?
|
||||
|
||||
**参考答案**:设计和管理每次模型调用时上下文窗口中的内容:系统提示词、工具、检索结果、历史、记忆、任务状态。手段包括选择相关内容、压缩、用子 Agent 隔离、把信息外部化存储后按需读取。
|
||||
|
||||
**追问**:上下文越长越好吗?→ 不是。无关信息会干扰模型、增加成本和延迟;关键信息放在显眼位置,长上下文中间的内容容易被忽略。
|
||||
|
||||
## 进阶
|
||||
|
||||
### 【进阶】Plan-and-Execute 和 ReAct 怎么选?
|
||||
|
||||
**参考答案**:步骤可以提前规划、需要给用户确认或展示进度的任务,用 Plan-and-Execute(执行阶段还能用便宜模型);需要根据每一步结果动态调整的探索性任务,用 ReAct。也可以结合:先规划,执行中每一步用 ReAct,失败时重新规划。
|
||||
|
||||
**追问**:计划执行到一半失败怎么办?→ 把具体错误和已完成步骤反馈给规划器重新规划,已完成的步骤不重复执行;设置最大次数。
|
||||
|
||||
### 【进阶】什么是 Skills?解决什么问题?
|
||||
|
||||
**参考答案**:把某类任务的说明、规范、脚本打包成目录,系统提示词中只放名字和描述,需要时加载全文(渐进式披露)。解决“专业知识太多放不进上下文”的问题,也便于团队沉淀和复用工作流。
|
||||
|
||||
**追问**:Skills 和 RAG 有什么区别?→ RAG 按相似度检索知识片段;Skill 是完整的操作说明,由模型根据描述决定是否加载,更像“按需打开的操作手册”。
|
||||
|
||||
### 【进阶】多 Agent 有哪些模式?什么时候用?
|
||||
|
||||
**参考答案**:主管模式(分派和汇总)、转交模式(按领域转给专门的 Agent)、流水线。在需要上下文隔离、专业分工、并行处理时使用;代价是成本、延迟、信息丢失和调试难度,能用单 Agent 解决的不拆。
|
||||
|
||||
**追问**:A2A 和 MCP 有什么区别?→ MCP 是 Agent 调用工具和数据的协议;A2A 是不同 Agent 之间协作的协议(Agent Card 描述能力,Task 有状态)。
|
||||
|
||||
## 场景题
|
||||
|
||||
### 【场景题】设计一个运营报表 Agent,你会怎么做?
|
||||
|
||||
**参考答案**:固定流程 + 局部 Agent;指标口径作为 Skill;SQL 工具连只读库,用解析器限制只读和表白名单,强制时间范围、LIMIT、超时;结论结构化输出,数字必须来自查询结果;任务状态和进度通过 SSE 推送。详见[报表 Agent 场景](scenarios/report-agent.md)。
|
||||
|
||||
**追问**:用户问的指标没有定义怎么办?→ 不猜,回复“该指标没有统一口径”,引导用户选择已有指标或联系数据组。
|
||||
|
||||
### 【场景题】Agent 接入了 40 个工具,经常选错,怎么优化?
|
||||
|
||||
**参考答案**:先用评测集确认错误类型;优化工具描述(何时用 / 何时不用);按意图分组,每次只提供相关工具;把相关工具合并或拆分到子 Agent;规范改成 Skills 按需加载;修改后用评测集验证。
|
||||
|
||||
**追问**:怎么评估工具选择的准确率?→ 评测用例标注期望调用的工具和参数,统计工具选择正确率和参数正确率。
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: ai.agent-design.scenario.report-agent
|
||||
title: 运营报表 Agent:规划、只读 SQL 工具、结构化输出和任务进度
|
||||
type: scenario
|
||||
domain: ai
|
||||
stack: [agent-design, langgraph, postgresql, fastapi]
|
||||
tags: [报表 Agent, Text-to-SQL, 规划, 结构化输出, 任务状态, 流式进度]
|
||||
level: advanced
|
||||
prerequisites: [ai.agent-design.react-planning]
|
||||
est_hours: 3
|
||||
related: [ai.agent-design.interview, ai.langgraph.persistence-hitl, ai.agent-ops.observability-cost]
|
||||
week: [11, 13]
|
||||
---
|
||||
|
||||
# 运营报表 Agent:规划、只读 SQL 工具、结构化输出和任务进度
|
||||
|
||||
## 业务背景与问题
|
||||
|
||||
运营每周要找数据组要报表(“9 月各大区 GMV 和环比”),排队要两三天。希望做一个报表 Agent:用自然语言提需求,自动查数、出图、写结论。原型的问题:
|
||||
|
||||
1. 生成的 SQL 偶尔写错表名,或者把“退款订单”也算进了 GMV;
|
||||
2. 有一次生成了没有时间条件的查询,扫描了整张订单表,拖慢了业务库;
|
||||
3. 复杂报表要跑一两分钟,页面一直转圈,用户以为卡死了;
|
||||
4. 结论里的数字和图表对不上。
|
||||
|
||||
## 约束
|
||||
|
||||
- 只能读,不能写;不能影响线上业务库。
|
||||
- 指标口径(GMV、退款率)以数据组的定义为准。
|
||||
|
||||
## 方案设计
|
||||
|
||||
1. **工作流 + 局部 Agent**:整体流程固定为“理解需求 → 规划 → 查询 → 出图 → 写结论”,只在“规划和查询”环节让模型多步探索。
|
||||
2. **指标口径作为 Skill**:把指标定义、表结构、示例 SQL 写成技能文件,按需加载,而不是让模型猜。
|
||||
3. **SQL 工具的安全边界**:连接只读从库 / 数仓;只允许 SELECT(用 SQL 解析器校验,不靠字符串匹配);强制时间范围、`LIMIT`、语句超时(`statement_timeout`);先 `EXPLAIN` 检查预估行数,超过阈值拒绝。
|
||||
4. **结构化输出**:结论用 Schema 输出(指标名、数值、来源查询 ID),数值必须来自查询结果——生成后程序校验每个数字都能在结果中找到。
|
||||
5. **任务状态和进度**:任务表记录状态(排队 / 规划中 / 查询中 / 生成中 / 完成 / 失败),LangGraph 节点用 `custom` 流推送进度,前端通过 SSE 显示;失败的步骤可以重试,不用从头开始。
|
||||
|
||||
## 关键代码
|
||||
|
||||
只读 SQL 工具的校验(使用 `sqlglot` 解析 SQL,示意,API 以官方文档为准):
|
||||
|
||||
```python
|
||||
import sqlglot
|
||||
from sqlglot import exp
|
||||
|
||||
|
||||
def validate_sql(sql: str) -> str:
|
||||
tree = sqlglot.parse_one(sql, read="postgres")
|
||||
if not isinstance(tree, exp.Select):
|
||||
raise ValueError("只允许 SELECT")
|
||||
tables = {t.name for t in tree.find_all(exp.Table)}
|
||||
if not tables <= ALLOWED_TABLES:
|
||||
raise ValueError(f"不允许访问的表:{tables - ALLOWED_TABLES}")
|
||||
if "created_at" not in sql:
|
||||
raise ValueError("必须带时间范围条件")
|
||||
if not tree.args.get("limit"):
|
||||
tree = tree.limit(1000)
|
||||
return tree.sql(dialect="postgres")
|
||||
|
||||
|
||||
async def run_query(sql: str) -> list[dict]:
|
||||
sql = validate_sql(sql)
|
||||
async with readonly_pool.connection() as conn:
|
||||
await conn.execute("SET statement_timeout = '15s'")
|
||||
return await (await conn.execute(sql)).fetchall()
|
||||
```
|
||||
|
||||
## 取舍
|
||||
|
||||
| 选择 | 优点 | 缺点 |
|
||||
| --- | --- | --- |
|
||||
| **工作流 + 局部 Agent(本方案)** | 可控、可展示进度、容易评测 | 灵活性有限 |
|
||||
| 完全自主的 Agent | 能处理开放问题 | 难控制成本和正确性 |
|
||||
| 预定义指标 API(语义层),不让模型写 SQL | 口径一致、最安全 | 需要先建设指标体系,覆盖不到的问题答不了 |
|
||||
| 模型直接写 SQL | 覆盖面广 | 口径和安全风险,需要本方案中的护栏 |
|
||||
|
||||
## 易错点
|
||||
|
||||
- 只用字符串判断 `SELECT`,被 `WITH ... DELETE` 或多语句绕过:用解析器,并且数据库账号本身只读。
|
||||
- 连接业务主库查询。
|
||||
- 结论中的数字由模型“复述”,不校验来源。
|
||||
- 长任务没有进度和超时,用户反复点击生成多个重复任务(要防重复提交)。
|
||||
|
||||
## 面试怎么讲
|
||||
|
||||
> “报表 Agent 我没有做成完全自主的,而是固定流程,只在规划和查询环节让模型多步探索。指标口径写成 Skill 按需加载;SQL 工具连只读从库,用解析器只允许 SELECT 和白名单表,强制时间范围、LIMIT 和语句超时;结论用结构化输出,每个数字都要能在查询结果里找到;任务有明确的状态,进度通过 SSE 推给前端,失败的步骤可以单独重试。”
|
||||
Reference in new issue
Block a user