start-agentrun-langgraph

start-agentrun-langgraph 是一个用于将 LangGraph 应用部署到阿里云 AgentRun 的 Serverless Devs 模板。模板内置 FastAPI HTTP 服务、ReAct Agent、自定义 StateGraph 示例、AgentRun 平台模型接入、OpenAI 兼容接口接入、可选 ToolSet 与沙箱集成，适合从最小示例快速扩展到生产形态。

这个仓库同时维护两种部署模式：

模板	Registry 包名	部署形态	适合场景
代码包模式	start-agentrun-langgraph	s build 安装 Python 依赖，再由 AgentRun 部署代码包	想保留 Serverless Devs 标准代码包流程，快速初始化和部署
容器镜像模式	start-agentrun-langgraph-container	用户先构建并推送镜像，AgentRun 通过 customContainerConfig.image 拉取运行	已有 Docker/ACR/CI 流水线，或需要固定系统依赖和运行环境

当前文件主要说明代码包模式；容器镜像模式的详细说明在 container/readme.md。

功能特性

• 基于 AgentRun 运行 LangGraph 应用，提供完整 s.yaml 模板。
• FastAPI 服务暴露 GET /health、POST / 和 POST /invocations，兼容 AgentRun endpoint 转发行为。
• 内置两种图结构：
  • react：基于 langgraph.prebuilt.create_react_agent。
  • graph：模板内自定义 StateGraph，展示 agent 节点和 tools 节点循环。
• 支持两类模型后端：
  • MODEL_BACKEND=openai：接 OpenAI 兼容接口，例如百炼 DashScope OpenAI-compatible endpoint。
  • MODEL_BACKEND=agentrun：接 AgentRun 平台托管模型。
• 支持通过 roleArn 绑定 RAM Role，例如 AliyunAgentRunDefaultRole，运行时由 AgentRun 兑换临时密钥，SDK 自动读取默认凭证。
• 支持可选 AgentRun ToolSet、代码解释器沙箱、浏览器沙箱。
• 默认关闭 tool calling 绑定，避免不支持工具调用的模型返回 400；需要时设置 ENABLE_TOOLS=true。
• 依赖安装使用本地精简 AgentRun SDK wheel，避免拉取模板未使用的 memory/vector-store/direct-completion 重依赖链。
• 支持通过 FC_DOCKER_IMAGE_URL 指定国内 FC 构建镜像，降低 Docker Hub 访问影响。

目录结构

仓库结构：

.
├── publish.yaml              # 代码包模式 registry 元数据和初始化参数
├── readme.md                 # 代码包模式说明，也作为 registry README
├── version.md                # 代码包模式版本说明
├── hook/
│   └── index.js              # 代码包模式 s init 钩子
├── src/                      # 代码包模式 s init 后输出给用户的项目
│   ├── s.yaml
│   ├── .env.example
│   ├── .gitignore
│   └── code/
│       ├── server.py
│       ├── agent_react.py
│       ├── agent_graph.py
│       ├── llm_factory.py
│       ├── tools.py
│       ├── agentrun_loader.py
│       ├── requirements.txt
│       └── vendor/
└── container/                # 容器镜像模式独立 registry 包
    ├── publish.yaml
    ├── readme.md
    ├── version.md
    ├── hook/
    └── src/

用户通过 s init start-agentrun-langgraph 得到的是 src/ 里的内容，而不是整个仓库。

初始化后的项目结构：

.
├── s.yaml                    # AgentRun 部署描述
├── .env.example              # 本地调试环境变量示例
├── .gitignore
└── code/
    ├── server.py             # FastAPI HTTP 入口
    ├── agent_react.py        # ReAct Agent 示例
    ├── agent_graph.py        # 自定义 StateGraph 示例
    ├── llm_factory.py        # 模型后端选择
    ├── tools.py              # 自定义工具、ToolSet、沙箱工具
    ├── agentrun_loader.py    # 轻量加载 AgentRun SDK builtin 子模块
    ├── requirements.txt
    └── vendor/
        └── agentrun_sdk-0.0.41-py3-none-any.whl

前置条件

1. 安装 Serverless Devs 3.x：

npm install -g @serverless-devs/s
s -v

2. 配置阿里云访问凭证：

s config add

初始化参数里的 accessAlias 要和这里配置的别名一致，默认是 default。

3. 开通并准备云服务：

• AgentRun / Function AI
• 函数计算
• 日志服务
• 如果使用 AgentRun 平台模型，准备可用模型名称或模型代理名称
• 如果使用 ToolSet 或沙箱，准备对应资源名称

4. 安装 Docker：

代码包模式的 s build 会在构建容器中安装 Python 依赖。建议使用国内 FC 构建镜像：

docker pull registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0
export FC_DOCKER_IMAGE_URL=registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0

快速开始：OpenAI 兼容接口

OpenAI 兼容模式最适合先快速跑通 HTTP 链路，例如使用百炼 DashScope OpenAI-compatible endpoint。

s init start-agentrun-langgraph -d my-langgraph-agent
cd my-langgraph-agent

cp .env.example .env

编辑 .env，至少准备：

MODEL_BACKEND=openai
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=qwen-plus
OPENAI_TEMPERATURE=0.7

构建并部署：

export FC_DOCKER_IMAGE_URL=registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0
s build
s deploy
s info

调用 endpoint：

curl -X POST '<endpoint-url>' \
  -H 'Content-Type: application/json' \
  -d '{"input":"请用一句中文介绍 LangGraph。","graph_type":"react"}'

快速开始：AgentRun 平台模型

如果希望使用 AgentRun 平台托管模型，初始化时选择 modelBackend=agentrun，并建议绑定运行时 Role。

示例参数：

s init start-agentrun-langgraph -d my-agentrun-langgraph \
  --parameters '{
    "agentName":"my-agentrun-langgraph",
    "region":"cn-hangzhou",
    "accessAlias":"default",
    "modelBackend":"agentrun",
    "defaultGraphType":"react",
    "roleArn":"acs:ram::<account-id>:role/AliyunAgentRunDefaultRole",
    "cpu":1,
    "memory":2048
  }'

部署前设置模型和可选资源：

export AGENTRUN_MODEL=<your-model-name-or-proxy-name>
export AGENTRUN_SANDBOX_CODE=
export AGENTRUN_SANDBOX_BROWSER=
export AGENTRUN_TOOLSET=
export ENABLE_TOOLS=false

export FC_DOCKER_IMAGE_URL=registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0
s build
s deploy

说明：

• roleArn 会写入 s.yaml 的 agent.role。
• AgentRun 启动运行时后会基于该 Role 兑换临时密钥。
• AgentRun SDK 默认凭证链会读取运行时注入的临时凭证。
• 不建议把长期 AK/SK 写入云上运行时环境变量。

在容器中执行 Serverless Devs

如果不希望操作宿主机环境，可以把项目目录和 Docker socket 挂进容器，在容器内执行 s build 和 s deploy。

示例：

docker run --rm -it \
  -v "$PWD:/app" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -w /app \
  -e FC_DOCKER_IMAGE_URL=registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0 \
  -e AGENTRUN_MODEL="$AGENTRUN_MODEL" \
  -e AGENTRUN_SANDBOX_CODE="$AGENTRUN_SANDBOX_CODE" \
  -e AGENTRUN_SANDBOX_BROWSER="$AGENTRUN_SANDBOX_BROWSER" \
  node:20-alpine sh

容器内安装并执行：

npm config set registry https://registry.npmmirror.com
npm install -g @serverless-devs/s@3.1.10
s build
s deploy

如果容器内需要调用宿主机 Docker daemon，必须挂载 /var/run/docker.sock，并且容器中需要可用的 Docker CLI。

模板参数

参数	必填	默认	说明
agentName	是	my-langgraph-agent	AgentRun 运行时实例名称，字母开头，支持字母、数字、下划线、中划线
region	是	cn-hangzhou	部署地域
accessAlias	否	default	本地 Serverless Devs 凭证别名
modelBackend	是	openai	openai 或 agentrun
defaultGraphType	否	react	默认图类型，react 或 graph
roleArn	否	空	AgentRun 运行时绑定的 RAM Role ARN
cpu	否	1	AgentRun CPU 核数
memory	否	2048	AgentRun 内存，单位 MB

运行时环境变量

变量	适用后端	必填	说明
MODEL_BACKEND	全部	是	openai 或 agentrun，通常由 s init 参数渲染进 s.yaml
DEFAULT_GRAPH_TYPE	全部	否	默认图类型，react 或 graph
ENABLE_TOOLS	全部	否	是否绑定工具，默认 false
AGENTRUN_MODEL	agentrun	是	AgentRun 平台模型或模型代理名称
AGENTRUN_REGION	agentrun	是	部署地域，模板自动设置为 ${vars.region}
AGENTRUN_TOOLSET	agentrun	否	AgentRun ToolSet 名称
AGENTRUN_SANDBOX_CODE	agentrun	否	代码解释器沙箱名称
AGENTRUN_SANDBOX_BROWSER	agentrun	否	浏览器沙箱名称
OPENAI_API_KEY	openai	是	OpenAI 兼容接口 API Key
OPENAI_BASE_URL	openai	否	OpenAI 兼容接口 Base URL
OPENAI_MODEL	openai	是	OpenAI 兼容模型名称
OPENAI_TEMPERATURE	openai	否	温度参数

HTTP 接口

健康检查：

curl '<endpoint-url-base>/health'

Agent 调用：

curl -X POST '<endpoint-url>' \
  -H 'Content-Type: application/json' \
  -d '{"input":"你好","graph_type":"react"}'

请求体：

字段	类型	必填	说明
input	string	是	用户输入
graph_type	string	否	react 或 graph，不传时使用 DEFAULT_GRAPH_TYPE

返回体：

{
  "output": "模型回复内容",
  "graph_type": "react"
}

模板同时支持 POST / 和 POST /invocations。这是因为 AgentRun 公网 endpoint 形如 /agent-runtimes/<name>/endpoints/default/invocations，转发到运行时时可能剥离外层 /invocations 前缀。

图结构说明

code/agent_react.py 使用 LangGraph 预置 ReAct Agent，适合入门和简单工具调用场景。

code/agent_graph.py 展示自定义 StateGraph，适合继续扩展：

• 增加 plan 节点
• 增加 reflect 节点
• 增加 critic 节点
• 增加人工确认节点
• 增加业务状态字段

调用时可用请求体切换：

curl -X POST '<endpoint-url>' \
  -H 'Content-Type: application/json' \
  -d '{"input":"用 graph 模式回答。","graph_type":"graph"}'

工具、ToolSet 与沙箱

模板里的 code/tools.py 默认包含一个本地示例工具，并预留 AgentRun ToolSet 和沙箱转换逻辑。

默认情况下：

ENABLE_TOOLS=false

如果模型支持 tool calling，可以启用：

export ENABLE_TOOLS=true

可选资源：

export AGENTRUN_TOOLSET=<your-toolset>
export AGENTRUN_SANDBOX_CODE=<code-interpreter-sandbox>
export AGENTRUN_SANDBOX_BROWSER=<browser-sandbox>

注意：部分模型不支持 OpenAI tool calling 协议。如果启用工具后模型返回 tool call is not supported，请关闭 ENABLE_TOOLS 或更换支持工具调用的模型。

构建细节

代码包模式使用 AgentRun component 的 code 配置：

code:
  src: ./code
  language: python3.10
  command:
    - /var/fc/lang/python3.10/bin/python3
    - server.py

s build 会把依赖安装到 code/python，运行时通过：

PYTHONPATH: /code/python
PATH: /code/python/bin:/var/fc/lang/python3.10/bin:...

让应用优先加载构建产物。

模板显式使用 /var/fc/lang/python3.10/bin/python3，避免 custom runtime 中系统 python3 指向较旧版本导致依赖导入失败。

容器镜像模式

如果不想在部署阶段执行 s build，可以改用容器镜像模板：

s init start-agentrun-langgraph-container -d my-agent-image

容器版流程：

cd my-agent-image
export IMAGE_URI=registry.cn-hangzhou.aliyuncs.com/<namespace>/langgraph-agent:latest
docker build --platform linux/amd64 -t "$IMAGE_URI" .
docker push "$IMAGE_URI"
s deploy

容器版不上传代码包，而是在 s.yaml 中使用：

customContainerConfig:
  image: <image-uri>

完整说明见 container/readme.md。

常见问题

s build 为什么会拉 Docker Hub 镜像？

AgentRun / FC component 默认可能会根据 runtime 选择默认构建镜像。网络环境不稳定时，建议显式设置：

export FC_DOCKER_IMAGE_URL=registry.cn-beijing.aliyuncs.com/aliyunfc/runtime-python3.10:build-3.0.0

为什么依赖里有 alibabacloud-endpoint-util？

这是阿里云 Python SDK 依赖链的一部分，不是业务代码额外引入的功能。模板已经通过精简 AgentRun SDK wheel 避免安装未使用的 memory/vector-store/direct-completion 重依赖，但 AgentRun 控制面、模型、ToolSet、沙箱相关 SDK 仍会带上必要的阿里云公共依赖。

部署成功但调用返回 Not Found？

确认服务同时支持 POST / 和 POST /invocations。当前模板已经兼容这两种路径。

调用模型时报 tool call is not supported？

关闭工具绑定：

export ENABLE_TOOLS=false
s deploy

或者换用支持 tool calling 的模型。

AgentRun 后端提示找不到凭证？

推荐在 s init 时传入：

roleArn=acs:ram::<account-id>:role/AliyunAgentRunDefaultRole

并确保该 Role 具备调用 AgentRun 模型、ToolSet、沙箱等资源所需权限。

可以不在宿主机安装 s 吗？

可以。把项目目录和 Docker socket 挂到容器里，在容器中安装并执行 s 即可。注意 s build 需要容器内可用 Docker CLI，并通过 /var/run/docker.sock 调用宿主机 Docker daemon。

版本发布

代码包模式发布：

s registry publish

容器镜像模式发布：

cd container
s registry publish

发布前请确认：

• publish.yaml 中版本号已递增。
• README 和 version.md 已更新。
• 没有提交 .env、AK/SK、registry token 等敏感信息。

License

MIT