使用 LangSmith 和 Vite 部署

将 LangChain deep agent 部署到 LangSmith Deployment，并从部署在 Vercel、Netlify 或 Cloudflare Pages 上的 Vite React 聊天 UI 进行流式传输。

本示例将带你从本地检出开始，构建一个已部署的 LangChain deep agent 和可用的聊天 UI。后端作为 LangSmith Deployment运行，前端是一个 Vite + React 应用，从后端进行流式传输。

当你希望在本地运行 agent、将其部署到 LangSmith，并让 UI 指向已部署的 Agent Server 时，请使用本指南。

来源：部署 cookbook 中的 js-langsmith。

你正在部署什么

LangSmith Deployment 在 LangSmith 托管的 Agent Server 上运行 LangGraph 图。在此示例中：

• agent/ 包含 deep agent 图、子 agent、中间件和工具。
• langgraph.json 告诉 LangGraph CLI 要服务和部署哪个图。
• src/ 包含 React 聊天 UI。
• UI 通过 LangGraph SDK 和 @langchain/react 与 Agent Server API 通信。

已部署的 agent 是一个协调器，包含两个子 agent：

• researcher 使用本地 search_web 工具。
• math-whiz 使用本地 calculator 工具。

各部分如何协同工作

%%{init: {"themeVariables": {"lineColor": "#40668D", "primaryColor": "#E5F4FF", "primaryTextColor": "#030710", "primaryBorderColor": "#006DDD"}}}%%
flowchart LR
  A["agent/<br/>createDeepAgent graph"] -->|"pnpm run deploy"| B["LangSmith Deployment<br/>Agent Server"]
  C["React chat UI<br/>src/"] -->|"LangGraph SDK<br/>threads + streaming"| B

  classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
  classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
  class A,C process
  class B output

在本地开发期间，pnpm run dev 会同时启动 LangGraph 开发服务器和 Vite 应用。在生产环境中，LangSmith 托管 agent，静态托管服务提供 Vite 构建的 UI。

前提条件

• 具有部署访问权限的 LangSmith API 密钥。
• 用于 agent 模型的 OpenAI API 密钥。
• pnpm。

本地运行

Install dependencies

cd js-langsmith
pnpm install

Create your environment file

cp .env.example .env

打开 .env 并设置：

OPENAI_API_KEY=<your OpenAI API key>

本地开发时，请将 LANGSMITH_API_KEY 和 VITE_AGENT_API_URL 留空。只有在部署或针对远程 LangSmith 部署测试 UI 时，才需要 LANGSMITH_API_KEY。

Start the agent and UI

pnpm run dev

这会启动两个进程：

• LangGraph 开发服务器：http://localhost:2024。
• Vite 开发服务器：http://localhost:5173。

Open the chat

打开 http://localhost:5173。尝试一个同时使用两个子 agent 的提示：

Research LangGraph streaming, and separately calculate 42 * 17.

当 VITE_AGENT_API_URL 为空时，Vite 应用会使用其位于 /api/langgraph 的本地代理，将请求转发到 LangGraph 开发服务器，从而避免 CORS 问题。

将 agent 部署到 LangSmith

Confirm your environment

你的 .env 必须包含：

OPENAI_API_KEY=<your OpenAI API key>
LANGSMITH_API_KEY=<your LangSmith API key>

可选地设置部署名称：

LANGSMITH_DEPLOYMENT_NAME=deployment-cookbook-agent

如果未设置 LANGSMITH_DEPLOYMENT_NAME，部署名称将默认为目录名。

Deploy the agent to LangSmith

pnpm run deploy

这会运行 langgraphjs deploy。CLI 使用 langgraph.json 从 agent/index.ts 部署 agent 图。

Copy the deployment API URL

部署后，在 LangSmith 中打开该部署并复制其 API URL。它应类似于：

https://your-app.us.langgraph.app/

仅使用根 URL。不要添加任何 API 路径后缀。

Test the UI against the remote deployment

在 .env 中设置 VITE_AGENT_API_URL：

VITE_AGENT_API_URL=https://your-app.us.langgraph.app

然后运行 UI：

pnpm run dev

浏览器客户端在与远程部署通信时会复用 LANGSMITH_API_KEY。

WARNING

此演示会将 LANGSMITH_API_KEY 暴露到浏览器 bundle 中，以便 UI 直接调用 LangSmith 部署。这便于本地测试，但不适合生产环境。对于真实应用，请通过你自己的后端代理请求，并将密钥保留在服务器端。

部署前端

agent 和 UI 分别部署。pnpm run deploy 成功后，将 Vite 构建产物（dist/）托管在任何静态平台上，并将其指向你的 LangSmith 部署 URL。

导入仓库

点击下方的 Deploy with Vercel，或手动导入 langchain-ai/deployment-cookbook。

配置项目

1. 将 Root Directory 设置为 js-langsmith。
2. 使用默认的 Vite 构建。构建输出为 dist/。
3. 设置以下环境变量：
   • VITE_AGENT_API_URL：LangSmith 部署根 URL。
   • LANGSMITH_API_KEY：演示客户端使用的 LangSmith API 密钥。

故障排查

• pnpm run dev 能启动，但 UI 无法连接：本地开发时请将 VITE_AGENT_API_URL 留空，然后重启 pnpm run dev。
• agent 在本地无法回答：确认 .env 中已设置 OPENAI_API_KEY。
• pnpm run deploy 因身份验证错误失败：确认 LANGSMITH_API_KEY 具有部署访问权限。
• 远程 UI 无法连接：确认 VITE_AGENT_API_URL 是部署根 URL，且没有路径后缀。
• 重启本地开发后线程消失：本地 langgraph dev 使用内存中的 MemorySaver；LangSmith Deployment 在生产环境中提供持久存储。
• 你更改了 agent/ 中的文件但生产环境没有变化：再次运行 pnpm run deploy。

了解项目

Agent 文件

LangSmith 后端位于 agent/：

agent/
├── index.ts       # createDeepAgent graph
├── middleware.ts  # response middleware
└── tools.ts       # custom code tools

agent/index.ts 导出 LangGraph 在本地提供服务并由 LangSmith 部署的图。本地 MemorySaver 检查点器仅由 langgraph dev 使用。LangSmith Deployment 会在生产环境中将其替换为持久化的 Postgres 存储，而无需更改代码。

LangGraph 配置

langgraph.json 让 CLI 指向该图：

{
  "graphs": {
    "agent": "./agent/index.ts:agent"
  },
  "env": ".env"
}

图的 ID 是 agent。前端在流式传输时将该 ID 用作 assistant ID。

聊天 UI

src/ 中的 React 应用提供流式聊天、线程历史、子 agent 渲染和工具调用渲染。

前端使用：

• client.threads.search() 用于线程侧边栏。
• client.threads.create() 和 client.threads.delete() 用于对话管理。
• StreamProvider 配合 assistantId: "agent" 用于流式聊天。

有关底层的线程和流式 API，请参阅 Agent Server API 参考。

本地命令

同时运行两个本地进程：

pnpm run dev

分别运行它们：

pnpm run dev:agent
pnpm run dev:web

构建并预览前端：

pnpm build
pnpm preview

CI/CD

当 js-langsmith/agent/ 下的文件或共享配置文件发生变化时，agent 会通过 GitHub Actions 部署：

• 工作流：.github/workflows/deploy-langsmith-agent.yml
• 操作：langgraphjs deploy 到 LangSmith。
• 必需的 secret：LANGSMITH_API_KEY。
• 可选变量：LANGSMITH_DEPLOYMENT_NAME。

前端通过静态托管服务的 Git 集成（例如 Vercel、Netlify 或 Cloudflare Pages）部署。

另请参阅

• 框架和平台概览
• LangSmith Deployment 概览
• LangGraph CLI
• Deep Agents 投入生产

---