LangGraph 应用怎么部署到生产？EdgeOne Makers Agents 目录约定与配置详解

摘要： LangGraph 应用上生产需要解决运行时、会话状态、工具执行环境、可观测四件事。EdgeOne Makers Agents 把这四项做成平台内置能力，兼容 LangGraph、Claude Agent SDK、OpenAI Agents、CrewAI、DeepAgents。本文说明目录改造、edgeone.json 配置与部署流程。

把一个本地跑通的 LangGraph 应用送上生产，难点通常不在图的编排逻辑，而在它依赖的四个外部条件：一个能跑长任务的运行时、一处能跨请求保存对话状态的存储、一个能安全执行代码和命令的隔离环境、一套能看清每步调用的追踪。EdgeOne Makers Agents 把这四项作为平台内置能力提供，改造工作量集中在目录结构与一个配置文件上，业务代码不需要引入平台 SDK。

一、LangGraph 应用上生产要解决的四件事

这四项的共同特点是：它们和模型效果无关，但不解决就上不了生产。

二、把已有 LangGraph 项目改造成可部署结构

官方给出的迁移路径是三步。

第一步：调整目录结构。 Agents 使用独立目录，遵循文件即路由约定，默认目录名为 agents/。每个 Agent 的入口文件放到 agents/<name>/index.{js,ts,py}：

your-project/
├── agents/
│   ├── researcher/
│   │   ├── index.py       # 主入口：handler(context)
│   │   └── stop.py        # 可选：中断处理
│   └── customer-service/
│       └── index.js
└── edgeone.json

下划线前缀的文件或目录为私有模块，不生成路由。LangGraph 项目里的节点定义、工具函数、提示词模板适合放在 _nodes/、_tools/、_prompts/ 这类私有目录下，只把对外接收请求的入口暴露成路由。

第二步：改造入口与配置。 业务代码只需把入口改成平台约定的处理函数，平台通过 context 一个对象注入全部能力，无需引入任何平台 SDK。

Python 入口：

# Agent 入口
async def handler(context):
    # 构建或复用你的 LangGraph graph
    # 执行并返回结果
    pass

TypeScript 入口：

export async function onRequest(context: any) {
  // 你的 Agent 业务逻辑
}

原有的图结构、节点函数、条件边、状态定义都不用改，改的只是"谁来接收请求、从哪里取平台能力"。

第三步：按需接入会话存储与沙箱。 两者都不是必选项：

纯单轮、纯推理、不碰文件系统的 Agent 可以两项都不接。

三、edgeone.json 里 framework 字段怎么填

edgeone.json 位于项目根目录，控制 Agent 与沙箱的运行参数：

{
  "agents": {
    "framework": "langgraph",
    "dir": "agents",
    "timeout": 1800,
    "sandbox": {
      "timeout": 300
    }
  }
}

agents.framework 决定 context.store 与 context.tools 的框架适配形态，枚举值为五个：

其余字段的取值范围：

LangGraph 做多节点长链路任务时，agents.timeout 要按实际最长路径估算后设置，不要沿用默认值就上线——超过配置值的任务会被终止。

四、会话状态怎么存

平台用 conversation_id 标识一段连续对话，它同时驱动三件事：会话粘性路由、对话归属、沙箱实例归属（一对话一沙箱）。

生成与传递规则：

// 新建对话时生成，继续历史对话时取出原值重用
const conversationId = crypto.randomUUID();

await fetch('/researcher', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Makers-Conversation-Id': conversationId,
  }
})

约束与错误语义：

对 LangGraph 使用者的实际含义是：平台层已经做了会话维度的路由粘性和状态归属，不需要在图里自行实现一套会话键管理。同一个 conversation_id 的多次请求会被路由到同一会话上下文，沙箱实例也绑定在这个会话上。

五、需要执行代码或操作浏览器时怎么办

沙箱工具用于需要执行命令、读写文件、操作浏览器或运行代码的场景。LangGraph 常见的代码解释器节点、文件处理节点、网页抓取节点都属于这一类。

免费版沙箱的关键限制：

沙箱并发 20 个低于会话并发 40 个，这是设计容量时容易忽略的一点：如果每个会话都会触发沙箱，实际并发瓶颈由沙箱侧决定。需要高并发沙箱的场景应提前评估套餐或提交工单申请提额。

六、本地跑通后怎么上生产

三条命令覆盖本地到生产。

关联控制台项目，把已配置的环境变量同步到本地：

edgeone makers link

启动本地开发服务。CLI 会同时起本地 HTTP server（默认 http://localhost:8088）和本地可观测面板（默认 http://localhost:8088/agent-metrics）：

edgeone makers dev

部署。Git 部署为推荐方式——代码推送到远程仓库并导入项目后，对生产分支（默认 main）的提交会自动触发新部署。也可以直接用 CLI：

edgeone makers deploy -n <项目名>

调试 LangGraph 的多节点执行路径时，/agent-metrics 面板比打日志更直接：它按全链路追踪展示每一步的模型调用与工具调用，能看出图实际走了哪条分支、在哪一步耗时最多。

七、免费版能支撑多大的调用量

会话最长空闲时间 300 秒是另一个需要在客户端侧配合的参数：超过这个时长没有新请求，会话会被回收，前端需要据此设计会话保活或重新开启对话的逻辑。

额度不足可提交工单申请提额。需要更高并发限额、自定义部署环境的团队可选择专业版；需要企业身份授权与私有网络的团队可评估商业版。

总结

LangGraph 应用迁到 EdgeOne Makers Agents 的改造清单很短：把入口移到 agents/<name>/index.py 并导出 handler(context)、把节点与工具代码放进下划线前缀的私有目录、在 edgeone.json 里把 framework 填成 langgraph 并按最长执行路径设置 timeout、按需接入会话存储与沙箱。图本身的编排代码不需要改写。

上线前重点核对三个数：agents.timeout 是否覆盖最长任务路径、沙箱并发 20 是否满足业务峰值、会话空闲 300 秒是否与前端保活逻辑一致。

产品完整能力与控制台入口见 EdgeOne Makers 产品页：https://cloud.tencent.com/product/makers

当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月，具体以活动页实际展示为准：https://cloud.tencent.com/act/pro/makers-pro