LangChain 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 响应揉在一个函数里。

怎样约束大模型的回答：理解 LangChain 结构化输出

Tue, 11 Aug 2026 00:00:00 +0000

“请返回 JSON”还不够

在 Prompt 末尾写“请严格返回 JSON”，模型仍可能改字段名、漏字段，或者把数字写成带单位的文字。JSON 能解析，也不代表业务上可用。

Voyager-AI 把约束分成三层：Prompt 说明任务，Schema 规定数据形状，业务校验检查字段之间是否合理。

flowchart LR
 P["Prompt
说明要做什么"] --> M["大模型"]
 M --> S["Schema
检查字段和类型"]
 S --> V["业务校验
检查数据关系"]
 V --> R["可使用的结果"]

用 Pydantic 编写 Schema

Schema 是数据结构约定。预算结果可以写成：

1
2
3
4
5
6
7
8


class BudgetCategory(BaseModel):
 category: str
 amount_minor: int = Field(ge=0)


class BudgetResult(BaseModel):
 total_minor: int = Field(gt=0)
 categories: list[BudgetCategory]

Pydantic 会检查 total_minor 是正整数、分类金额不是负数、categories 是列表。BaseModel 还提供 model_validate，可以把真实数据放进去验证。

LangChain 怎样绑定结构

1
2
3
4
5
6
7
8


def invoke_structured(model, schema, payload, *, prompt):
 try:
 runnable = model.with_structured_output(schema)
 result = runnable.invoke(prompt)
 except (ValidationError, OutputParserException) as error:
 raise AgentOutputError() from error

 return schema.model_validate(result)

with_structured_output(schema) 返回一个 Runnable。Runnable 可以理解成“具有统一 invoke 调用方式的可执行组件”。LangChain 会根据模型能力请求结构化结果，再由本地 Pydantic 复查。

解析错误被转换为 AgentOutputError，模型连接失败则是 AgentModelError。区分两者后，排错时能知道是服务不可用，还是回答不符合结构。

类型正确仍然可能算错账

下面的数据完全符合 Schema：

1
2
3
4
5
6
7


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

但分类合计只有 78000。Pydantic 只知道每个字段类型正确，不知道业务上必须对账。

因此最终计划还会执行：

1
2
3
4
5
6
7


category_total = sum(
 item["amount_minor"]
 for item in budget["categories"]
)

if category_total != budget["total_minor"]:
 raise InvalidTravelPlanError()

同一层校验还要求 Reviewer 已批准、final_plan 有足够内容。结构化输出减少模型自由度，业务校验继续保护真正重要的规则。

总结

约束模型不能只靠一句更强硬的 Prompt。Prompt、Schema 和业务校验解决的是不同问题：一个表达意图，一个检查形状，一个判断数据关系。

LangChain 的结构化输出让不同模型以相近方式绑定 Schema，Pydantic 在本地提供可重复的验证。模型负责生成不确定内容，代码负责守住可以确定的边界。

一个 Agent 是怎样实现的：从普通 Python 类到 LangChain 模型调用

Sun, 26 Jul 2026 00:00:00 +0000

Agent 并不是一种特殊语法

在代码里，Agent 可以从一个普通类开始：读取状态，执行任务，返回更新。

1
2
3
4
5
6


class FoodAgent:
 def run(self, state: TravelState) -> dict[str, object]:
 destination = state["user_request"].destination
 return {
 "foods": [{"name": f"{destination}本地风味"}]
 }

随着角色增加，每个 Agent 都需要记录开始和结束、计算耗时、处理异常。如果把这些逻辑复制六遍，很快会出现不同版本。

flowchart TB
 A["调用 Agent.run"] --> B["发送 started 事件"]
 B --> C["执行子类 _execute"]
 C --> D{"执行是否成功"}
 D -->|"成功"| E["发送 completed 事件"]
 E --> F["返回状态更新"]
 D -->|"失败"| G["映射为安全异常"]
 G --> H["发送 failed 事件"]
 H --> I["向上抛出异常"]

这张图就是 BaseAgent.run 的固定骨架。Destination、Food、Budget 等子类只替换中间的 _execute，前后的生命周期处理保持一致。

BaseAgent 负责共同生命周期

Voyager-AI 把公共流程放进 BaseAgent.run：

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


def run(self, state, context):
 self.event_sink.emit(
 AgentEvent.started(context.workflow_id, self.name)
 )
 started_at = perf_counter()

 try:
 update = self._execute(state)
 except Exception as error:
 mapped = map_agent_exception(error)
 self.event_sink.emit(AgentEvent.failed(...))
 raise mapped from error

 self.event_sink.emit(AgentEvent.completed(...))
 return update

子类只实现 _execute。这是一种模板方法：父类固定执行骨架，子类填入角色自己的工作。

event_sink 可以理解成事件接收器。内存测试可以把事件放进列表，后端则可以把它们写入数据库。Agent 不需要知道事件最终存在哪里。

为什么先保留确定性执行

DestinationAgent 在没有模型时使用固定规则：

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


def _execute(self, state):
 if self.model is not None:
 result = self._invoke_model(state, DestinationEntry)
 return {"destination_info": [result.model_dump()]}

 request = state["user_request"]
 return {
 "destination_info": [{
 "name": request["destination"],
 "description": "围绕兴趣安排的旅行",
 "best_time": "按当季天气灵活安排",
 }]
 }

确定性模式不联网，相同输入得到相同结果。它适合验证工作流顺序和数据结构。模型模式则适合生成更丰富的内容。

这里没有在模型失败时偷偷退回固定结果。否则线上模型已经出错，接口却返回一份看似成功的默认计划，问题会被隐藏。

LangChain 统一不同模型

项目可以创建 ChatOllama 或 ChatOpenAI。两者底层服务不同，但都符合 LangChain 的聊天模型接口。Agent 因此只依赖“能够进行结构化调用的模型”，不依赖某个厂商 SDK。

这种做法叫依赖倒置：上层业务依赖稳定接口，具体模型实现可以替换。

flowchart LR
 A["Travel Agent"] --> I["LangChain ChatModel 接口"]
 I --> O["ChatOllama
本地模型"]
 I --> P["ChatOpenAI
OpenAI 兼容接口"]
 I --> T["Fake Model
单元测试"]

1
2


class StructuredChatModel(Protocol):
 def with_structured_output(self, schema): ...

Protocol 是 Python 的结构化接口。一个对象只要提供所需方法，就可以被 Agent 使用。

AgentContext 为什么不放进状态

AgentContext 保存 workflow id，用于关联一次运行产生的事件。它不是旅行计划本身，所以不会写入 TravelState。

调用 run(state, context) 时，state 回答“正在规划什么”，context 回答“这是哪一次执行”。分开以后，旅行状态不会混入日志标识和运行配置。

总结

Voyager-AI 的 Agent 本质上仍然是普通 Python 对象。BaseAgent 统一生命周期，子类负责具体任务，LangChain 提供可替换的模型接口，Context 携带一次运行的附加信息。

把这些职责分开后，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 来说，这比单纯增加角色数量更重要，也是这次拆分真正解决的问题。