LangGraph on HanGR的碎碎念

怎样把 LangGraph 接入真实应用：从 Runnable 到旅行任务 API

Fri, 14 Aug 2026 00:00:00 +0000

graph.invoke 只是最小起点

本地脚本可以直接执行：

1

result = graph.invoke(initial_state)

真实应用还要面对耗时、并发、失败和查询。一次六节点模型工作流可能运行几分钟，HTTP 请求不能一直让用户看着空白页面。

Voyager-AI 把一次执行包装成旅行任务：先返回 id，后台运行图，用户随后查询状态和结果。

sequenceDiagram
 participant U as 用户
 participant A as FastAPI
 participant D as PostgreSQL
 participant G as LangGraph
 U->>A: 创建旅行任务
 A->>D: 保存 pending
 A-->>U: 202 + travel_id
 A->>D: 更新为 running
 A->>G: ainvoke(initial_state)
 G-->>A: 最终 TravelState
 A->>D: 保存 completed + plan
 U->>A: 查询 status / plan
 A->>D: 读取任务
 A-->>U: 返回状态或计划

Runnable 提供统一执行方式

LangGraph 编译结果遵循 LangChain Runnable 接口。常见方法有：

invoke：同步执行并等待最终结果；
ainvoke：异步执行；
stream：同步逐步返回结果；
astream：异步流式返回。

项目用 _TravelWorkflow 包装编译图，在每次调用时补充 AgentContext，同时把 config 和其他参数继续传给底层 Runnable。包装层没有把 LangGraph 重新实现一遍。

事件让黑盒过程可观察

每个 Agent 会发出 started、completed 或 failed 事件。事件只保存角色、时间、耗时和安全错误码，不保存 Prompt、模型原文或 API Key。

flowchart LR
 A["Agent.run"] --> S["agent.started"]
 A --> C["agent.completed"]
 A --> F["agent.failed"]
 S --> DB[("agent_events")]
 C --> DB
 F --> DB
 DB --> API["状态接口"]

workflow id 用来关联一次图运行，travel id 用来关联一项持久化任务。它们属于运行上下文和后端记录，不应该混进模型看到的旅行状态。

API 为什么先返回 202

创建接口返回 202 Accepted 和 travel_id。202 表示服务器接收了任务，但尚未完成。

1
2
3


POST /api/travel/create
GET /api/travel/{travel_id}/status
GET /api/travel/{travel_id}/plan

任务不存在返回 404；任务存在但计划未完成时返回 409；只有 completed 才返回计划。明确状态比返回空 JSON 更容易让前端处理。

PostgreSQL 保存什么

数据库保存用户请求、pending/running/completed/failed 状态、时间戳、安全事件和最终计划。Repository 在状态迁移前检查旧状态，避免 completed 任务再次运行。

但持久化结果不等于持久化执行。当前后台工作仍使用 FastAPI BackgroundTasks，API 进程重启可能中断运行中的图。Redis 已在基础设施中，但真正可恢复的 Worker 还没有实现。

总结

把 LangGraph 接入应用，不只是把 graph.invoke 放进路由。耗时工作需要任务 id，执行过程需要安全事件，结果需要状态校验与持久化，HTTP 接口也要表达“已接收”和“已完成”的区别。

LangChain 与 LangGraph 负责模型和工作流，FastAPI 与 PostgreSQL 负责把它们变成用户可以提交、等待和查询的服务。边界分清后，每一层才能独立测试，也不会把模型调用、数据库事务和 HTTP 响应揉在一个函数里。

审核不通过怎么办：理解 LangGraph 的条件边与循环

Wed, 05 Aug 2026 00:00:00 +0000

工作流不一定永远向前

三个专家完成后，Reviewer 会检查目的地、餐饮和预算是否齐全。通过就进入 Final；缺少内容则需要返工。

普通边只能表达固定的下一步。LangGraph 的条件边（conditional edge）会根据当前状态选择路线。

flowchart LR
 R["Reviewer"] --> C{"review_status"}
 C -->|"approved"| F["Final"]
 C -->|"revise"| P["Planner"]
 P --> D["重新执行专家节点"]
 D --> R

路由函数只负责做选择

1
2
3
4
5
6


def route_after_review(
 state: Mapping[str, object],
) -> Literal["planner", "final"]:
 if state["review_status"] == "revise":
 return "planner"
 return "final"

Literal 表示返回值只能是两个指定字符串。路由函数不修改状态，也不直接调用节点，它只回答“下一站叫什么”。

随后把返回值映射到真实节点：

1
2
3
4
5
6
7
8


builder.add_conditional_edges(
 "reviewer",
 route_after_review,
 {
 "planner": "planner",
 "final": "final",
 },
)

把判断写成独立函数后，可以直接构造两份状态测试它，不必每次运行整张图。

Reviewer 怎样给出决定

确定性 Reviewer 会检查三个必需字段：

1
2
3
4
5


required = ("destination_info", "foods", "budget")
risks = [key for key in required if not state[key]]

if not risks:
 return {"review_status": "approved", "risks": []}

发现缺失项时返回 revise，同时增加 revision_count。使用模型时，Reviewer 会把状态交给 ReviewResult Schema，模型仍然只能在规定的状态和问题列表中返回结果。

循环必须有停止条件

只要图里有一条回到前面节点的边，就可能无限执行。模型如果持续返回 revise，任务会不断消耗时间和 Token。

Voyager-AI 把修订次数限制为一次：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


if result.status == "revise" and state["revision_count"] < 1:
 return {
 "review_status": "revise",
 "revision_count": state["revision_count"] + 1,
 "risks": result.issues,
 }

return {
 "review_status": "approved",
 "risks": result.issues,
}

这个策略并不完美。第二次仍有问题时，它会保留 risks 并结束流程，而不是保证方案已经没有问题。它解决的是工程上的“流程必须终止”，不是内容质量上的“计划一定正确”。

真实产品还可以选择失败、转人工审核或只重跑缺失节点。关键是必须明确达到上限后怎么办。

总结

条件边让工作流根据状态选择下一步，循环让 Agent 有机会修正结果，计数器则保证返工不会无限持续。

Reviewer 的价值不只是再调用一次模型，而是把“什么情况下继续、什么情况下返工”变成程序能够测试的规则。对于任何带自我修正的 Agent 系统，停止条件和返工条件同样重要。

多个 Agent 怎样同时工作：理解 LangGraph 的分支与汇合

Sun, 02 Aug 2026 00:00:00 +0000

顺序执行并不总是必要

Destination、Food 和 Budget 都读取同一份用户请求。预算计算不需要等待餐饮建议，FoodAgent 也不依赖 DestinationAgent 的介绍。如果仍然一个接一个运行，只会增加总等待时间。

普通 Python 可以用并发任务处理，但还要自己收集结果、处理异常并合并字典。LangGraph 允许直接用多条边表示这种关系。

从一个节点分出三条边

1
2
3


builder.add_edge("planner", "destination")
builder.add_edge("planner", "food")
builder.add_edge("planner", "budget")

这种“从一个节点分到多个节点”的结构常被称为 fan-out，也就是扇出。

flowchart LR
 P["Planner"] --> D["Destination"]
 P --> F["Food"]
 P --> B["Budget"]

Planner 完成后，三个节点都具备运行条件。它们读取 Planner 更新后的状态，各自返回不同字段。

这里说“可以并行”，重点是节点没有数据依赖。实际运行是否占用多个线程或进程，还取决于节点是同步还是异步、模型客户端如何实现。图描述的是依赖关系，不是对底层并发方式的承诺。

三份结果怎样汇合

Reviewer 必须等目的地、餐饮和预算都完成。LangGraph 用列表形式声明汇合边：

1
2
3
4


builder.add_edge(
 ["destination", "food", "budget"],
 "reviewer",
)

flowchart LR
 D["Destination
destination_info"] --> R["Reviewer"]
 F["Food
foods"] --> R
 B["Budget
budget"] --> R

这不是“任何一个完成就进入 Reviewer”，而是一个 barrier（屏障）：三条分支都到达后，Reviewer 才能继续。

并行写状态为什么没有互相覆盖

三个 Agent 返回不同字段：

1
2
3
4
5
6
7
8


# DestinationAgent
{"destination_info": [...]}

# FoodAgent
{"foods": [...]}

# BudgetAgent
{"budget": {...}}

因此合并没有冲突。如果两个并行节点都写 foods，就必须明确使用哪个结果，或者为该字段配置 reducer（归并规则）。Reducer 可以理解成“多个更新同时到来时，应该怎样组合”。

Voyager-AI 当前不需要复杂 reducer，因为并行节点有各自的写入范围。这也是拆 Agent 时明确输出边界的重要性。

测试怎样证明汇合有效

工作流测试会替换节点，记录实际调用情况。Reviewer 运行时检查三份专家结果是否都已经出现在状态中，而不是只看最终计划有没有生成。

图结构测试还会读取编译图，确认 Planner 有三条出边，并且三个专家共同连接 Reviewer。这样修改某条边时，流程契约会立即失败。

总结

多个 Agent 能不能同时工作，不取决于角色名称，而取决于数据依赖。只读取共同输入、写入不同字段的任务，适合从同一节点分支；需要完整结果的审核步骤，则应该放在汇合点之后。

LangGraph 的分支和汇合把这种依赖直接画进工作流。它减少的不只是运行时间，也避免把并发控制、结果收集和下一步调用散落在各个 Agent 中。

为什么需要一张图：理解 LangGraph 的节点、边和执行顺序

Tue, 28 Jul 2026 00:00:00 +0000

普通函数调用已经能工作

六个 Agent 完全可以手动串起来：

1
2
3
4
5
6


state.update(planner.run(state))
state.update(destination.run(state))
state.update(food.run(state))
state.update(budget.run(state))
state.update(reviewer.run(state))
state.update(final.run(state))

对于永远不变的直线流程，这种写法很清楚。旅行规划却不完全是一条直线：三个专家可以分别工作，Reviewer 还可能要求返工。继续用 if、循环和函数调用堆下去，流程规则会散落在业务代码里。

LangGraph 用“图”把执行关系单独表达出来。

flowchart LR
 S["START"] --> P["Planner"]
 P --> D["Destination"]
 P --> F["Food"]
 P --> B["Budget"]
 D --> R["Reviewer"]
 F --> R
 B --> R
 R -->|"approved"| O["Final"]
 R -->|"revise"| P
 O --> E["END"]

这张图比一串函数调用多表达了两件事：Planner 后出现了三条分支；Reviewer 也不一定继续向前，它可能回到 Planner。

节点和边是什么

图由节点（Node）和边（Edge）组成。

节点是一个处理步骤。在 Voyager-AI 中，Planner、Food、Budget 都是节点。节点接收 TravelState，返回局部更新。

边表示节点之间的执行关系。planner -> food 的意思是 Planner 完成后，Food 节点可以开始。

1
2
3
4
5
6
7
8


builder = StateGraph(TravelState, context_schema=AgentContext)

builder.add_node("planner", planner_node)
builder.add_node("destination", destination_node)
builder.add_node("food", food_node)
builder.add_node("budget", budget_node)
builder.add_node("reviewer", reviewer_node)
builder.add_node("final", final_node)

StateGraph(TravelState) 表示所有节点围绕同一种状态工作。context_schema 则描述 workflow id 等不会写入业务状态的运行信息。

START 和 END 不是 Agent

LangGraph 使用 START 和 END 标记入口与出口：

1
2


builder.add_edge(START, "planner")
builder.add_edge("final", END)

它们不执行旅行任务，只告诉图从哪里开始、什么情况下算结束。缺少 END 的循环图可能一直运行，因此出口也是流程设计的一部分。

Agent 怎样变成节点

LangGraph 节点通常是可调用对象。项目用 _agent_node 把 Agent 包装成符合节点签名的函数：

1
2
3
4
5
6


def _agent_node(agent):
 def run(state: TravelState, runtime: Runtime[AgentContext]):
 context = runtime.context
 return AgentNode(agent, context)(state)

 return run

LangGraph 提供 state 和 runtime，包装函数取出 Context，再调用 Agent。这样 Agent 本身不需要导入 LangGraph，也能在图外单独测试。

编译以后怎样运行

节点和边添加完成后，调用 builder.compile() 得到可执行图。LangGraph 的可执行对象属于 Runnable，也就是具有统一调用方式的组件。

1
2


graph = build_workflow()
result = graph.invoke(create_initial_state(request))

invoke 是同步执行；ainvoke 是异步执行；stream 和 astream 则可以逐步取得运行结果。项目用 _TravelWorkflow 包装编译图，同时保留这些调用方式。

图带来的价值不是画图好看

图把流程控制从 Agent 内部拿了出来。FoodAgent 不负责决定下一个节点，Reviewer 也不直接调用 Planner。角色逻辑改变时看 Agent，执行关系改变时看 workflow。

测试还可以读取编译图，检查 START 是否连接 Planner、Final 是否连接 END，而不必只靠一次完整运行猜测路径是否正确。

总结

普通函数调用适合简单直线流程。出现分支、汇合、返工和流式执行后，把执行关系表示成图会更容易理解和测试。

LangGraph 的基本思想并不神秘：节点负责处理数据，边负责安排顺序，StateGraph 负责让状态在节点之间流动。Voyager-AI 使用它，不是为了让 Agent 自动变聪明，而是为了把越来越复杂的流程规则放到一个看得见的位置。

Agent 之间怎样传递信息：用 Voyager-AI 理解 LangGraph 状态

Sat, 25 Jul 2026 00:00:00 +0000

Agent 分开以后，数据放在哪里

把旅行规划拆成 Destination、Food 和 Budget 等 Agent 后，新问题马上出现了：FoodAgent 怎样知道用户要去杭州？Reviewer 又去哪里读取前三个 Agent 的结果？

最直接的办法是让 Agent 互相调用：

1
2
3
4


destination = destination_agent(request)
foods = food_agent(request, destination)
budget = budget_agent(request, destination, foods)
result = reviewer_agent(destination, foods, budget)

任务一多，函数参数会越来越长，执行顺序也被写死。任何 Agent 想增加一个结果，后面的调用都可能跟着修改。

LangGraph 采用另一种思路：准备一份共享状态，让节点读取它，再返回需要更新的字段。状态可以理解成旅行策划小组共用的一张工作单。

flowchart TD
 U["用户请求"] --> I["创建初始 TravelState"]
 I --> P["Planner 写入 tasks"]
 P --> D["Destination 写入 destination_info"]
 D --> F["Food 写入 foods"]
 F --> B["Budget 写入 budget"]
 B --> R["Reviewer 读取已有结果"]
 R --> O["Final 写入 final_plan"]

图中的箭头表示状态继续向后流动。每个节点看到的都是同一类 TravelState，但其中已经填写的栏目会越来越多。

先区分用户请求和工作流状态

Voyager-AI 用 TravelRequest 保存用户输入：

1
2
3
4
5
6
7


class TravelRequest(BaseModel):
 destination: str
 days: int
 people: int
 budget: Decimal
 interests: list[str]
 pace: str

Pydantic 的 BaseModel 会在程序入口检查字段类型和范围。这里的数据回答“用户想去哪里、有什么要求”。

工作流内部使用 TravelState：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class TravelState(TypedDict):
 user_request: TravelRequest
 tasks: list[str]
 destination_info: list[DestinationEntry]
 foods: list[FoodEntry]
 budget: BudgetPlan | None
 risks: list[str]
 review_status: str
 revision_count: int
 final_plan: str

TypedDict 仍然是普通字典，只是提前声明了允许出现的字段和类型。编辑器与类型检查器因此能发现 destination_info 拼错之类的问题。

两者的区别是：TravelRequest 在一次任务中基本不变；TravelState 会随着节点执行逐渐被填满。

状态是怎样变化的

工作流开始时，状态大致是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "user_request": request,
 "tasks": [],
 "destination_info": [],
 "foods": [],
 "budget": None,
 "risks": [],
 "review_status": "pending",
 "revision_count": 0,
 "final_plan": "",
}

Planner 不需要复制完整字典，只返回：

1

{"tasks": ["destination", "food", "budget", "review", "final"]}

FoodAgent 也只返回：

1

{"foods": [{"name": "杭州本地风味", "category": "local"}]}

LangGraph 会把这些局部更新合并回状态。Agent 不需要知道其他节点的函数地址，也不需要主动把结果传给下一个 Agent。

flowchart TB
 S0["初始状态
只有 user_request"] --> S1["Planner 后
增加 tasks"]
 S1 --> S2["专家节点后
增加 destination_info、foods、budget"]
 S2 --> S3["Reviewer 后
增加 review_status、risks"]
 S3 --> S4["Final 后
增加 final_plan"]

为什么统一创建初始状态

项目使用 create_initial_state(request) 创建工作单，而不是在每个入口手写空字典。这样可以保证所有字段都有初始值，也避免不同请求共享同一份列表。

如果把空列表放在一个全局默认对象里，第一次任务向 foods 添加数据后，第二次任务可能读到同一份内容。测试会创建两份初始状态，修改其中一份，再确认另一份没有变化。

状态不是越大越好

共享状态虽然方便，也很容易变成什么都往里塞的“公共垃圾桶”。Voyager-AI 没有把模型客户端、API Key、数据库 Session 或 HTTP Request 放进 TravelState。

状态只保存工作流真正需要流转的业务数据。模型连接属于依赖，workflow id 属于运行上下文，数据库连接属于后端基础设施。把它们分开后，状态才能安全序列化、测试和持久化。

总结

Agent 之间不一定要直接互相调用。让它们围绕一份结构明确的状态工作，可以减少参数传递，也能让节点只关心自己读写的字段。

TravelRequest 保存不会随流程改变的用户要求，TravelState 记录逐步产生的旅行数据，LangGraph 负责把节点返回的局部结果合并进去。共享状态真正解决的，是多个 Agent 怎样在不过度耦合的情况下共同完成一件事。

从一个 Prompt 到多个 Agent：用 Voyager-AI 理解任务拆分

Wed, 22 Jul 2026 00:00:00 +0000

从一个 Prompt 开始

我最开始想做 Voyager-AI 时，第一反应很直接：写一个 Prompt，把目的地、天数、预算和兴趣交给大模型，让它生成一份旅行计划。

Prompt 就是我们交给模型的要求和背景资料。这里说的大模型，也就是常见的 LLM（Large Language Model），例如 GPT 或本地运行的 Qwen。

如果只是做个演示，这个方案完全可行。代码甚至不需要多少行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


prompt = f"""
请帮我制定一份旅行计划。

目的地：杭州
天数：3 天
人数：2 人
预算：1200 元
兴趣：茶文化、历史

请给出景点、美食、预算和注意事项。
"""

answer = model.invoke(prompt)
print(answer.content)

代码中的 model.invoke(prompt)，可以直接理解成“把这份要求发给模型，然后等待回答”。

生成了答案，程序却接不住

模型通常能返回一篇看起来不错的攻略。问题是，程序除了把它显示出来，几乎什么也做不了。

预算有没有超过 1200 元？餐饮和住宿分别花了多少？景点信息缺失时应该只补景点，还是整篇重新生成？如果模型前半段说“预算充足”，后半段的明细却加起来超支，程序又该相信哪一段？

这些问题让我意识到：一段完整的自然语言答案，适合人阅读，却不一定适合程序继续处理。

这也是 Voyager-AI 开始拆分 Agent 的原因。

flowchart LR
 U["旅行需求"] --> O["一个大 Prompt"]
 O --> T["一整篇自然语言攻略"]
 U --> P["Planner"]
 P --> D["Destination"]
 P --> F["Food"]
 P --> B["Budget"]
 D --> S["结构化旅行数据"]
 F --> S
 B --> S

上半条路线把所有要求一次性交给模型；下半条路线把任务拆开，让每部分返回程序可以分别检查的数据。

先用普通 Python 拆开任务

“Agent”这个词很容易让人想到几个 AI 在会议室里互相讨论。实际写代码时，可以先把它理解成一个更普通的东西：

一个只负责某项任务的处理单元。它读取已有数据，完成自己的工作，再返回一小部分新数据。

例如，旅行规划可以先拆成几个普通 Python 函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


def plan_destination(request: dict) -> dict:
 return {
 "destination_info": {
 "name": request["destination"],
 "focus": request["interests"],
 }
 }


def plan_food(request: dict) -> dict:
 return {
 "foods": [
 {
 "name": f"{request['destination']}本地风味",
 "category": "local",
 }
 ]
 }


def plan_budget(request: dict) -> dict:
 total = int(request["budget"] * 100)
 return {
 "budget": {
 "total_minor": total,
 "categories": [
 {"category": "transport", "amount_minor": int(total * 0.3)},
 {"category": "lodging", "amount_minor": int(total * 0.35)},
 ],
 }
 }

这里还没有 LangChain，也没有 LangGraph。但分工已经出现了：目的地函数只返回 destination_info，美食函数只返回 foods，预算函数只返回 budget。

相比“一次生成整篇攻略”，这种做法多了几个好处：

预算可以单独测试，不用比较整篇文案；
美食生成失败时，不必重新生成目的地信息；
每一部分都能使用不同的数据结构；
后面可以让互不依赖的任务同时执行。

所以，多 Agent 的第一步并不是安装框架，而是先判断问题能不能拆成职责清楚的小任务。

Voyager-AI 的六个 Agent

项目现在有六个 Agent：

Agent	负责什么	主要返回字段
Planner	决定本轮需要完成哪些任务	`tasks`
Destination	整理目的地信息	`destination_info`
Food	整理餐饮建议	`foods`
Budget	分配旅行预算	`budget`
Reviewer	检查结果是否完整	`review_status`、`risks`
Final	把已有数据整理成最终方案	`final_plan`

这些 Agent 并不是六个不同的大模型。它们可以共用同一个模型，也可以完全不调用模型。在这个项目里，Agent 指的是一个职责明确的处理单元：读取当前旅行数据，必要时调用模型，再交回自己负责的结果。

一个 Agent 是怎样实现的

比如当前项目的 BudgetAgent 在默认模式下使用普通 Python 计算：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


class BudgetAgent(_TravelAgent):
 prompt_key = "budget"

 def _execute(self, state: TravelState) -> dict[str, object]:
 if self.model is not None:
 result = self._invoke_model(state, _BudgetResult)
 return {"budget": result.model_dump()}

 total_minor = int(
 (
 Decimal(str(state["user_request"]["budget"]))
 * 100
 ).quantize(Decimal(1))
 )

 # 按比例计算交通、住宿、餐饮等预算
 # 最后用总额减去已分配金额，避免取整后对不上账
 ...

 return {
 "budget": {
 "total_minor": total_minor,
 "categories": categories,
 }
 }

先看最重要的分支：

1

if self.model is not None:

有模型时，BudgetAgent 请求模型生成 _BudgetResult；没有模型时，就走下面的确定性计算。所谓“确定性”，就是相同输入一定得到相同结果，不依赖网络，也不会因为模型状态不同而变化。

这样设计以后，工作流和测试不必绑定某个模型。先用确定性逻辑确认数据能正确流动，再换成 Ollama 或 OpenAI 兼容模型，出了问题也更容易判断是工作流错了，还是模型输出不符合要求。

LangChain 在这里做了什么

LangChain 是一套开发大模型应用的工具库。Voyager-AI 并没有大量使用传统的 LLMChain，而是把 LangChain 当成一层统一的模型接口。

项目支持两种模型实现：

1
2


from langchain_ollama import ChatOllama
from langchain_openai import ChatOpenAI

本地运行可以使用 Ollama：

1
2
3
4
5


ChatOllama(
 model="qwen3.5:9b",
 base_url="http://localhost:11434",
 temperature=0,
)

OpenAI 或兼容接口则使用：

1
2
3
4
5
6


ChatOpenAI(
 model=settings.model,
 base_url=settings.base_url,
 api_key=settings.api_key,
 temperature=settings.temperature,
)

上层 Agent 不需要分别学习两套 SDK。只要拿到的对象符合 LangChain 的 ChatModel 接口，就可以用相同方式调用。

更关键的是结构化输出（Structured Output）。普通模型回答是一段文字，结构化输出则要求模型按照规定字段交回数据：

1
2
3
4
5
6
7


def invoke_structured(model, schema, payload, *, prompt=None):
 model_input = prompt or json.dumps(payload, ensure_ascii=False)

 runnable = model.with_structured_output(schema)
 result = runnable.invoke(model_input)

 return schema.model_validate(result)

这里的 schema 可以理解成数据填写规则：它规定有哪些字段、字段是什么类型。项目使用 Pydantic 编写这份规则；Pydantic 是 Python 中常见的数据校验库。例如 BudgetAgent 使用的结构可以简化成：

1
2
3
4
5
6
7
8


class BudgetCategory(BaseModel):
 category: str
 amount_minor: int


class BudgetResult(BaseModel):
 total_minor: int
 categories: list[BudgetCategory]

调用 with_structured_output(BudgetResult) 后，我们期待的就不再是一篇随意发挥的预算说明，而是一份字段明确的数据：

1
2
3
4
5
6
7
8
9


{
 "total_minor": 120000,
 "categories": [
 {"category": "transport", "amount_minor": 36000},
 {"category": "lodging", "amount_minor": 42000},
 {"category": "food", "amount_minor": 24000},
 {"category": "activities", "amount_minor": 18000}
 ]
}

程序现在可以把分类金额加起来，检查是否等于 120000；也可以把预算单独显示在前端。自然语言仍然有价值，但它不再是程序唯一能拿到的结果。

什么时候值得拆成 Agent

如果两个步骤总是使用完全相同的输入、一起执行、一起失败，也没有独立测试的必要，把它们硬拆成两个 Agent 只会增加复杂度。

我现在判断一个任务要不要单独成为 Agent，主要看四件事：

它是否有清楚的输入和输出？
它能否独立测试？
它失败时，是否可以单独重试或替换？
它是否需要与其他任务采用不同的 Prompt、模型或工具？

Voyager-AI 中的 Destination、Food 和 Budget 基本满足这些条件。Reviewer 也值得独立，因为它不负责生成新内容，而是决定当前结果能否进入下一步。

总结

刚开始做 Voyager-AI 时，我会把注意力放在“项目里有几个 Agent”上，仿佛角色越多，系统就越智能。真正把代码拆开以后，我发现数量其实没那么重要。

更值得关心的是，每个角色能不能把自己的事情说清楚：需要读取哪些数据，会交回什么结果，出错以后能不能单独检查。Destination、Food 和 Budget 之所以适合分开，并不是因为给它们起了不同的名字，而是因为三项工作确实可以分别完成。

回到文章最开始的问题：一个 Prompt 并不是不能生成旅行计划，而是它把资料整理、预算计算、结果检查和文字组织全部揉在了一起。只要其中一部分需要重新生成，整份结果都可能发生变化，程序也很难判断新结果究竟好在哪里。

把任务拆成 Agent 后，这些工作有了各自的边界。LangChain 再把不同模型和结构化输出接到这些边界上，让模型生成的内容可以被代码检查和继续使用。对 Voyager-AI 来说，这比单纯增加角色数量更重要，也是这次拆分真正解决的问题。