自定义应用

通过用 LangSmith Chat 聊天或在本地用 LangSmith CLI，构建运行在 LangSmith 内部并调用 LangSmith API 的自定义 UI。

NOTE

自定义应用在 Plus 和 Enterprise 方案上可用。

自定义应用是你构建的一个运行在 LangSmith 内部并调用 LangSmith API 的 UI。当内置 UI 未覆盖某个工作流时用它，例如一个专门构建的标注界面、一个实验对比视图，或一个限定到你自己追踪的仪表板。

已部署的应用会出现在侧边栏的 Custom Apps 下，对拥有 custom-apps:read 权限的工作区里的每个人可见。你无需托管单独的服务或管理单独的登录。

应用在一个自身没有网络访问的沙箱中运行。宿主使用查看者的凭据转发它的 LangSmith API 请求，因此每个人只会看到其权限所允许的数据。宿主不转发其他任何内容，并且它会阻止 API 密钥、成员、用户、身份、角色、权限、SCIM 和服务账户的端点。

构建一个应用

你可以通过在浏览器中用 LangSmith Chat 聊天来构建应用，或在本地用 CLI 和你自己的编码 agent 来构建。两条路径产生相同的应用并存储相同的源码，因此任一条都可以编辑另一条构建的内容。

用聊天构建

在浏览器中构建有两个要求：

• 沙箱：每个会话在一个沙箱中运行。在自托管部署上，请先启用沙箱。
• 权限：custom-apps:create、custom-apps:update、custom-apps:delete 和 custom-apps:download 权限，加上沙箱权限。

若两者都不满足，App 动作会改为打开 CLI 说明。Chat 还需要先为工作区设置一个模型 API 密钥才能发送消息。

要用聊天构建一个应用：

Start a new app

前往 Custom Apps 并选择 App 以打开聊天。在一个尚无应用的工作区中，该页面会直接打开聊天。

Describe what you want to build

在编辑器中输入该应用应做什么，并从编辑器中的模型菜单选择用于构建的模型。即使其背后的沙箱仍在启动，编辑器也接受一个提示。当 Chat 开始写入文件时，LangSmith 会保存一个草稿并在聊天旁打开 Preview 和 Code 标签。

Review what Chat built

Preview 标签渲染你更改的实时构建。Code 标签容纳文件树、源码和本次会话的更改。标题中的一个徽章会统计被更改的文件数。

Deploy the app

选择 Deploy。首次部署会询问一个名称、构建该应用，并将其发布到工作区。

如果你在首次部署前离开页面，LangSmith 会丢弃该应用。一旦 Chat 已开始编辑，LangSmith 会在丢弃前询问。

在本地用 CLI 构建

在本地构建使用 LangSmith CLI，它会搭建一个起始模板、在你机器上的一个真实沙箱中运行它，并在你准备好时上传它。要在本地构建一个应用：

Install the CLI

curl -fsSL https://cli.langsmith.com/install.sh | sh

有关 Windows、Homebrew 和其他选项，参阅安装。

Authenticate

langsmith auth login

要改用一个 API 密钥，请设置 LANGSMITH_API_KEY，对于自托管实例还需 LANGSMITH_ENDPOINT。有关配置文件和其他选项，参阅身份验证。

Scaffold an app

langsmith apps init --name my-annotation-view --template annotation-queue

init 会创建一个以应用命名的目录，并且如果你的 PATH 中有 npm，会安装其依赖。它还会写入一个 AGENTS.md，为编码 agent 提供首次尝试就能产出可用应用所需的约定和 API 接口。若要空白单文件起始模板，请省略 --template。

Iterate locally

cd my-annotation-view
langsmith apps dev

该应用运行在它进入 LangSmith 时所处的同种沙箱中，API 调用通过你自己的凭据代理。失败的调用和未捕获的错误会流式输出到终端，因此大多数调试都无需浏览器开发者工具。加上 --verbose 可看到每次成功的调用和所有控制台输出，或用 --quiet 静音该应用。

Push it live

langsmith apps push

首次 push 会创建该应用并在 .langsmith/app.json 中记录其 ID，该文件将目录与其关联。后续的 push 会更新同一个应用。提交那个文件，以便队友 push 到同一个应用。

起始模板

将以下之一传给 langsmith apps init --template：

模板	它搭建什么
annotation-queue	一个队列审查 UI：运行和线程项、一个类型专属查看器，以及一个反馈评分标准。
annotation-queue-grid	以可编辑电子表格形式呈现的同一审查工作流。
experiment-comparison	对照基线并排比较评估实验。
coding-agent-dashboard	覆盖编码 agent 运行的图表：随时间的用量、成本、错误和活动。

编辑一个应用

在浏览器中用聊天编辑一个应用，或拉取其源码并在本地编辑。

用聊天编辑

从 Custom Apps 打开一个应用并选择 Edit。已发布的应用会被编辑工作区取代：左边是聊天，右边是同样的 Preview 和 Code 标签。

在聊天中请求更改，或直接在 Code 中编辑一个文件并用 Cmd+S（Windows 和 Linux 上为 Ctrl+S）保存。无论哪种方式，预览都会重新构建，标题中的徽章会更新其被更改文件的计数。

有两个动作会结束会话：

• Deploy：构建该应用并将其作为一个新版本发布给工作区。
• Cancel：不部署就离开。未部署的更改留在编辑沙箱中。

编辑运行在一个会在一段不活动后停止的沙箱中。重新打开该应用会唤醒沙箱并保留未部署的更改。如果沙箱已被删除，请选择 Recreate from saved source 以从最后部署的源码重建会话。未部署的更改将丢失。

要重命名一个应用、复制其 ID，或更改它与谁共享，请从应用列表中的行菜单选择 Edit。

在本地用 CLI 编辑

从浏览器发起的部署会存储应用的源码，langsmith apps push 也会。要在本地编辑一个应用，将它拉下来：

langsmith apps pull my-app
npm install --prefix my-app

用你自己的编码 agent 编辑源码，然后运行 langsmith apps push 来发布它。

搭建出的 AGENTS.md 要求 agent 在应用根目录保留一个 context.md 作为应用的记忆：应用做什么、哪些文件重要，以及其背后的决策。任何根文件都会随源码一起走，因此一个拉取该应用的队友会从你已学到的东西开始，而非从零开始。

与你的组织共享一个应用

一个自定义应用归属于它被创建时所在的工作区。要与组织共享一个，请打开应用列表中的行菜单，选择 Edit，然后选择 Share with organization。此后组织中的每个工作区都能看到、更新和删除它。

要将一个共享应用移回单个工作区，请从那个工作区选择 Pull into this workspace。如果该工作区已有一个同名应用，LangSmith 会要求你重命名它。

当 CLI 按名称解析一个应用时，同名的工作区应用会优先于组织应用。

CLI 参考

命令	它做什么
langsmith apps init --name NAME [--template TEMPLATE]	在一个以应用命名的新目录中搭建一个起始应用，并安装其依赖。
langsmith apps dev	在一个真实沙箱中本地运行当前目录的应用。
langsmith apps push	将当前目录作为一个自定义应用上传，在首次 push 时创建它。传入 --no-build 以原样上传当前文件。
langsmith apps pull APP_ID_OR_NAME	将一个应用的源码下载到一个新目录。
langsmith apps list	列出自定义应用。
langsmith apps delete APP_ID_OR_NAME	按 ID 或名称删除一个应用。传入 --yes 以跳过确认。

dev 和 push 作用于当前目录，因此请先切换到应用目录。

权限

custom-apps:* 权限控制对自定义应用的访问。有关完整表格，参阅自定义应用。

在浏览器中编辑还需要 sandboxes:create、sandboxes:read、sandboxes:update、sandboxes:delete 和 sandboxes:exec 权限，因为每个会话都在一个沙箱中运行。Edit 动作只对拥有 custom-apps:update、custom-apps:download 和沙箱权限的用户出现。

---