以编程方式使用文档

本示例帮助你从本地代码快速部署一个带可工作聊天界面的 LangChain 深度智能体。后端作为 LangSmith Deployment运行，前端是 Vite + React 应用，从中获取流式响应。

当你想要在本地运行智能体、将其部署到 LangSmith，并让界面连接到已部署的智能体服务器时，请使用本指南。

Source: js-langsmith 在部署烹饪书中。

你要部署的内容

A **LangSmith Deployment** 在 LangSmith 的托管智能体服务器上运行 LangGraph 图。在本示例中：

  • - agent/ 包含深度智能体图、子智能体、中间件和工具。
  • - langgraph.json 告诉 LangGraph CLI 要服务哪个图以及如何部署。
  • - src/ 包含 React 聊天界面。
  • - 界面通过 LangGraph SDK 与智能体服务器 API 通信， @langchain/react.

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

  • - researcher 使用本地 search_web tool.
  • - math-whiz 使用本地 calculator tool.

各部分如何配合

%%{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 托管智能体，静态主机提供 Vite 构建的界面。

前置条件

  • - A LangSmith API 密钥 具有部署访问权限。
  • - 用于智能体模型的 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_API_KEY 用于部署或测试界面连接远程 LangSmith 部署时。

Start the agent and UI

pnpm run dev

这会同时启动两个进程：

Open the chat

打开 http://localhost:5173。尝试一个使用两个子智能体的提示：

Research LangGraph streaming, and separately calculate 42 * 17.

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

将智能体部署到 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

If LANGSMITH_DEPLOYMENT_NAME 未设置时，部署名称默认为目录名称。

Deploy the agent to LangSmith

pnpm run deploy

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

Copy the deployment API URL

部署后，在 LangSmith 中打开部署并复制其 **API URL**。应该看起来像这样：

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

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

Test the UI against the remote deployment

设置 VITE_AGENT_API_URL in .env:

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

然后运行 UI：

pnpm run dev

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

部署前端

代理和 UI 单独部署。之后 pnpm run deploy 成功后，托管 Vite 构建（dist/）在任意静态平台上，并将其指向您的 LangSmith 部署 URL。

Vercel

Import the repository

点击 **使用 Vercel 部署** 下方，或导入 langchain-ai/deployment-cookbook manually.

Deploy with Vercel

Configure the project

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

Netlify

Import the repository

点击 **部署到 Netlify** 下方，或导入 langchain-ai/deployment-cookbook manually.

Deploy to Netlify

Configure the project

设置 **基础目录** to js-langsmith。使用默认构建命令（pnpm build or npm run build）和发布目录 dist/.

Set environment variables

在 Netlify 部署前添加以下变量：

  • - VITE_AGENT_API_URL：LangSmith 部署根 URL。
  • - LANGSMITH_API_KEY：演示客户端使用的 LangSmith API 密钥。

Cloudflare Pages

Connect the repository

在 Cloudflare 仪表板中，创建一个 **Workers & Pages** 项目，从 langchain-ai/deployment-cookbook.

Configure the build

  • 根目录: js-langsmith
  • 构建命令: pnpm install && pnpm build
  • 构建输出目录: dist

Set environment variables

在 Pages 项目设置中添加以下变量：

  • - VITE_AGENT_API_URL：LangSmith 部署根 URL。
  • - LANGSMITH_API_KEY：演示客户端使用的 LangSmith API 密钥。

故障排除

  • - pnpm run dev 启动但 UI 无法连接：保留 VITE_AGENT_API_URL 本地开发为空，然后重启 pnpm run dev.
  • - 代理本地回答失败：确认 OPENAI_API_KEY 在 .env.
  • - pnpm run deploy 认证失败：确认 LANGSMITH_API_KEY 具有部署访问权限。
  • - 远程 UI 无法连接：确认 VITE_AGENT_API_URL 是部署根 URL，不含路径后缀。
  • - 本地开发重启后线程消失：本地 langgraph dev 使用内存中的 MemorySaver; LangSmith 部署在生产环境中提供持久化存储。
  • - 您更改了以下文件 agent/ 但生产环境未更改：请运行 pnpm run deploy again.

了解项目

Agent files

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 部署在生产环境中用持久的 Postgres 后端存储替换它，无需代码更改。

LangGraph config

langgraph.json 将 CLI 指向图：

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

图 ID 为 agent。前端在流式传输时使用该 ID 作为助手 ID。

Chat UI

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

前端使用：

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

请参阅 Agent Server API 参考 了解底层的线程和流式传输 API。

Local commands

运行两个本地进程：

pnpm run dev

分别运行它们：

pnpm run dev:agent
pnpm run dev:web

构建并预览前端：

pnpm build
pnpm preview

CI/CD

当以下文件或共享配置文件更改时，代理通过 GitHub Actions 部署： js-langsmith/agent/ 或共享配置文件更改：

前端通过静态主机的 Git 集成部署（例如 Vercel、Netlify 或 Cloudflare Pages）。

另请参阅