026. LangGraph 接口服务、客户端调用与跨域

学习目标

这一节把最简单的 LangGraph 工作流部署成接口，并演示客户端如何调用，同时处理前端跨域问题。

学完后，你应该能理解：

• LangGraph 工作流如何暴露成后端接口；
• invoke、batch、stream 分别适合什么场景；
• Python / TypeScript 客户端如何调用工作流接口；
• 为什么前端调用本地后端会遇到跨域；
• 跨域配置为什么要放到环境变量里；
• 直接调用云厂商模型和通过 LangChain 调用有什么区别。

定义最简单的工作流

这一节先定义一个最简单的 LangGraph 工作流。

工作流可以理解成 Agent 的执行图。

图里至少会有：

• 模型节点；
• 工具节点；
• 开始；
• 结束；
• 节点之间的跳转规则。

当前重点不是做复杂业务，而是先把工作流跑起来，并把它部署成接口服务。

部署成接口

工作流本身是 Python 里的对象。

前端不能直接调用 Python 对象。

所以需要把它暴露成 HTTP 接口。

课程里通过后端路由把工作流挂出来，形成类似 graph proxy 的接口前缀。

接口跑起来后，可以在接口文档里看到对应路径。

这样前端、脚本或调试工具都能通过 HTTP 请求调用这个工作流。

三种调用方式

LangChain / LangGraph 里的 runnable 通常有几类调用方法。

常见的是：

• invoke：单次调用；
• batch：批量调用；
• stream：流式调用。

也有对应的异步版本。

这三种能力对应不同场景。

invoke 适合一次输入一次输出。

batch 适合同时处理多条输入。

stream 适合模型边生成边返回，前端可以逐步显示内容。

客户端调用

后端把工作流接口暴露出来后，客户端有两种常见调用方式。

一种是 Python 客户端。

它适合后端脚本、测试脚本或服务之间调用。

另一种是 TypeScript 客户端。

它适合前端项目里调用后端工作流接口。

课程里演示了前端通过客户端 API 调用本地模型接口。

这一步说明 LangGraph 不只是后端内部工具，它可以被前端页面真正消费。

跨域问题

前端本地页面调用本地后端接口时，经常会遇到跨域。

原因是浏览器会检查：

• 协议；
• 域名；
• 端口。

只要其中一个不同，就可能触发 CORS 限制。

课程里通过后端配置放开跨域。

这样前端才能从自己的开发服务器访问后端模型接口。

跨域配置放到环境变量

跨域白名单不应该随便写死在代码里。

不同环境会有不同地址：

• 本地开发地址；
• 测试环境地址；
• 线上域名；
• 局域网调试地址。

所以更适合通过环境变量控制。

开发环境可以放宽一点。

生产环境要明确允许哪些域名，不要无脑允许所有来源。

代理文档静态资源

课程里还整理了文档静态资源代理。

接口文档、Playground 或相关页面可能依赖静态 JS / CSS。

如果后端没有正确代理这些资源，页面会打开异常。

所以模型服务不是只写一个接口函数。

文档访问、静态资源、跨域、路由前缀都要一起处理。

直接调用云厂商模型

课程也对比了直接调用云厂商模型。

直接调用当然可以。

但你需要自己处理：

• 请求格式；
• 流式返回；
• 思考内容和普通内容；
• 错误处理；
• 模型切换；
• 重试逻辑。

使用 LangChain / LangGraph 的好处是，它已经封装了很多通用调用形态。

你可以用更统一的方式调用模型、批量任务和流式输出。

阶段重点

这一节把 LangGraph 从代码里的工作流变成了可访问的后端接口。

接口服务、客户端调用、跨域配置和静态资源代理都跑通后，前端才真正能把 Agent 能力接进页面。