注意

LlamaAgents 的云端部署目前处于 beta 预览阶段，已广泛开放以供反馈。你可以在本地试用，或部署到 LlamaCloud 并通过应用内的反馈按钮把意见发给我们。

本页说明如何配置一个自定义前端，让它与你的 LlamaAgents 工作流服务端一起构建并通信。如果你是从模板起步的，现在就可以直接用。往下读可以了解更多信息。

LlamaAgents 工具链对 UI 技术栈不做主张 —— 界面由你自己带。多数模板用 Vite 配 React，但任何框架都可以，只要它能：

• 为生产环境构建静态资源，并且
• 在构建与开发期间读取若干个环境变量

集成是如何工作的

开发期间，llamactl 通过调用你的 npm run dev 命令来启动并代理你的前端。部署时，它用 npm run build 静态构建你的界面。这两条命令都可以配置，见配置参考中的 UIConfig。如果你启用了 corepack，也可以使用其他包管理器。

开发期间，llamactl 会启动它的工作流服务端（默认端口 4501）并启动 UI，同时传入一个 PORT 环境变量（默认 4502）以及一个 LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH（例如 /deployments/<name>/ui，即 UI 将被提供的路径）。随后它把服务端的请求从该基础路径代理给客户端应用。

部署之后，Kubernetes operator 会用配置好的 npm 脚本（默认 build）构建你的应用，并在同一个基础路径上提供你的静态资源。

必需的配置

1. 在配置好的 PORT 上提供开发期 UI。这个环境变量告诉你的开发服务器在开发时用哪个端口。许多框架（例如 Next.js）会自动读取它。
2. 把你应用的基础路径设为 LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH 的值。LlamaAgents 应用依赖这个路径来路由到多个工作流部署。代理会原样保留这段路径，因此你的应用可以用绝对路径在内部互相链接。你的开发服务器与路由器都需要知道这个基础路径。多数框架都提供了配置它的方式，例如 Vite 用 base。
3. 把 LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH 环境变量重新导出给你的应用。读取这个值（例如在 React Router 中）来配置基础路径。要正确链接静态资源，往往也需要它。
4. 如果你要和 LlamaCloud 集成，请把 LLAMA_DEPLOY_PROJECT_ID 环境变量重新导出给你的应用，并用它把你的 LlamaCloud 请求限定在同个项目内。更多见配置参考。
5. 我们也建议重新导出 LLAMA_DEPLOY_DEPLOYMENT_NAME，它在把请求正确路由到你的工作流服务端时会有帮助。

示例

Vite（React）

配置 vite.config.ts 读取注入的环境变量，并设置基础路径与端口：

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig(() => {
  const basePath = process.env.LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH;
  const port = process.env.PORT ? parseInt(process.env.PORT) : undefined;
  return {
    plugins: [react()],
    server: { port, host: true, hmr: { port } },
    base: basePath,
    // Pass-through env for client usage
    define: {
      ...(basePath && {
        "import.meta.env.VITE_LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH": JSON.stringify(basePath),
      }),
      ...(process.env.LLAMA_DEPLOY_DEPLOYMENT_NAME && {
        "import.meta.env.VITE_LLAMA_DEPLOY_DEPLOYMENT_NAME": JSON.stringify(
          process.env.LLAMA_DEPLOY_DEPLOYMENT_NAME,
        ),
      }),
      ...(process.env.LLAMA_DEPLOY_PROJECT_ID && {
        "import.meta.env.VITE_LLAMA_DEPLOY_PROJECT_ID": JSON.stringify(
          process.env.LLAMA_DEPLOY_PROJECT_ID,
        ),
      }),
    },
  };
});

package.json 里的脚本通常长这样：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Next.js（静态导出）

Next.js 支持静态导出。配置 next.config.mjs 使用提供的基础路径并启用静态导出：

next.config.mjs

const basePath = process.env.LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH || "";
const deploymentName = process.env.LLAMA_DEPLOY_DEPLOYMENT_NAME;
const projectId = process.env.LLAMA_DEPLOY_PROJECT_ID;

export default {
  // Mount app under /deployments/<name>/ui
  basePath,
  // For assets when hosted behind a path prefix
  assetPrefix: basePath || undefined,
  // Enable static export for production
  output: "export",
  // Expose base path to browser for runtime URL construction
  env: {
    NEXT_PUBLIC_LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH: basePath,
    NEXT_PUBLIC_LLAMA_DEPLOY_DEPLOYMENT_NAME: deploymentName,
    NEXT_PUBLIC_LLAMA_DEPLOY_PROJECT_ID: projectId,
  },
};

确保你的脚本会导出到一个目录（默认：out/）：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build && next export"
  }
}

开发服务器会绑定到应用服务端设定的 PORT，无需额外配置。对于动态路由或与静态导出不兼容的服务端特性，你可以不做导出，改为依赖向 Python 应用服务端的代理。不过，生产环境的静态托管需要一个构建输出目录。

运行时拼接 URL（图片/资源）

• Vite：用配置好的 base 或 import.meta.env.BASE_URL（或那个透传变量）来为你在运行时拼出的资源 URL 加前缀：

const base = import.meta.env.VITE_LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH || import.meta.env.BASE_URL || "/";
<img src={`${base.replace(/\/$/, "")}/images/logo.png`} />

• Next.js 静态导出：使用暴露出来的 NEXT_PUBLIC_LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH，让路由能正确解析绝对的资源路径：

const base = process.env.NEXT_PUBLIC_LLAMA_DEPLOY_DEPLOYMENT_BASE_PATH || "";
export default function Logo() {
  return <img src={`${base}/images/logo.png`} alt="logo" />;
}

PUBLIC_* 环境变量覆盖

设置 PUBLIC_X 只会覆盖 UI 构建环境中的 X。后端保留原值。PUBLIC_* 这些 key 会从构建环境中剥离。

env:
  API_URL: "http://internal.svc:8000"
  PUBLIC_API_URL: "https://api.example.com"  # UI build sees API_URL=https://api.example.com

之后你的 vite/next 配置就可以照常把被覆盖的值映射成框架专用的变量（例如通过 define 块得到 VITE_API_URL）。

配置界面的输出目录

你的 UI 必须输出平台能够定位到的静态资源。请按部署配置参考说明配置 ui.directory 与 ui.build_output_dir。默认值：${ui.directory}/dist。