跳到主要内容
AI教程

使用 useAgent 构建并自托管 AI 协作者

了解如何通过统一界面运行 Claude Code、Codex 和 OpenCode，并可靠地自托管 AI Agent 工作负载。

AI我搜编辑部阅读约 11 分钟
useAgent AI 协作者工作区
Alpha 版警告：useAgent 正在积极开发中。不同版本之间的 API 和 schema 可能发生变化，因此在稳定性至关重要时，请固定使用某个发布标签。

什么是 useAgent？

useAgent 是一个开源 AI 协作者平台，用于运行 Claude Code、Codex 和 OpenCode 等 Agent。Agent 不仅会返回对话式答案，还能在隔离的 Linux 环境中工作，并交付完整的网站、演示文稿、电子表格、研究报告以及经过测试的 pull request。

每个线程都会获得一台工作站，其中包含终端、代码仓库、浏览器，以及可通过 noVNC 查看的桌面。运行过程在 Postgres 中表示为事件溯源时间线，因此具有持久性，可在完成后重放和检查。

useAgent workspace and agent composer

主要功能

  • 一个界面管理多个 Agent：特定于提供商的引擎通过规范化事件契约进行通信。
  • 持久化执行：后端重启后运行仍会保留，恢复机制可以重新探测活动会话并接管已完成的工作。
  • 隔离的 Linux 沙箱：每个线程都会获得一台独立工作站。Daytona 和 CubeSandbox 均实现了共享沙箱契约。
  • 可信工具网关：凭据保留在控制平面中，不会进入 Agent 沙箱。
  • 人工审批：破坏性工具调用会暂停，等待用户在 Web 界面或 Slack 中审批；批准后，系统会使用与参数绑定的单次能力令牌继续执行。
  • 基于 GitHub 的技能：团队可以导入带版本控制的 SKILL.md 文件、同步变更，并将相关技能排序后加入 Agent 的每轮交互。
  • 组织上下文：知识检索包含引用来源，团队记忆则采用经人工审核的学习流程。
  • 原生制品：平台支持带修订版本的 DOCX、XLSX、PPTX 和 PDF 文件，并提供原生渲染器。
  • 多种入口渠道：任务可以通过 Web 应用、Slack、REST API 或计划任务进入。

架构如何运作

useAgent 将自托管控制平面与 Agent 的工作环境分离。各入口渠道通过同一条运行路径创建任务。引擎适配器将特定于提供商的活动转换为规范化事件，同时为每个线程分配一个隔离沙箱。

以下三个架构特性尤为重要：

  1. 引擎可替换：更换引擎时，无需替换线程、制品或记忆的通用表示形式。
  2. Postgres 是事实来源：每次运行都存储为事件日志，因此重启后仍可精确重放和检查。
  3. 密钥保留在沙箱之外：集成通过可信网关以类型化工具的形式公开，凭据仅存储在控制平面中。
useAgent session timeline and workspace

代码仓库结构

  • frontend/ 包含会话、技能、运行手册、Wiki、制品、自动化和设置等产品界面。
  • backend/ 包含身份验证、运行编排、引擎适配器、沙箱、知识、记忆、制品和连接器。
  • packages/ 包含共享事件契约、工作件、制品格式、渲染器及相关软件包。
  • docs-site/ 包含文档网站。
  • infra/self-host/ 包含与提供商无关的部署工具以及 Hetzner Terraform 参考实现。
  • memory/ 包含可选的团队记忆服务。

环境要求

本地开发安装需要 Bun 和 Postgres 16 或更高版本，并安装 pgvector 扩展。标准 Postgres 容器镜像不包含 pgvector，因此请使用合适的、已启用 pgvector 的镜像。

如果计划通过提供的数据库容器命令启动数据库，还应安装 Docker。请从 useAgent 代码仓库的根目录执行以下步骤。

第 1 步：启动带有 pgvector 的 Postgres

如果尚未运行兼容的数据库，请在 Docker 中启动一个：

docker run -d --name useagent-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres

第一条命令通过端口 5432 公开 Postgres。第二条命令设置应用使用的连接字符串。信任配置适合本地开发；生产环境应使用经过适当安全保护的数据库凭据。

第 2 步：安装工作区依赖项

共享软件包、后端和前端工作区的依赖项需要分别安装：

for workspace in \
  packages/agent-harness packages/artifact-workspace \
  packages/agent-client packages/artifact-formats packages/conformance \
  backend frontend; do
  (cd "$workspace" && bun install)
done

第 3 步：启动后端和前端

打开不同的终端会话，分别启动两个开发进程：

bun run dev:backend
bun run dev:frontend

后端在端口 3201 上提供 API 和编排服务。前端运行在端口 3400 上，并将 /api/* 下的请求代理到后端。

在浏览器中打开 http://localhost:3400 即可访问界面。提供商和沙箱配置可能有所不同，因此在连接 Agent 引擎或配置其执行环境时，请遵循最新的 useAgent 文档。

第 4 步：验证代码库

安装完成后或提交变更前，请运行覆盖整个代码仓库的类型检查器：

bun run typecheck

此命令覆盖代码仓库中的每个软件包，有助于发现共享契约、后端和前端之间不兼容的变更。

基本用法

创建 Agent 运行任务

  1. 打开端口 3400 上的 Web 界面。
  2. 使用 Agent 编排器描述你需要的最终成果。
  3. 启动运行并关注其实时事件时间线。
  4. 在 Agent 执行过程中检查终端、浏览器、桌面或工作区活动。
  5. 在允许执行破坏性工具操作之前，检查所有审批卡片。
  6. 获取会话返回的完整制品或代码仓库变更。

任务可以围绕具体交付成果进行描述，例如：

研究该主题，引用相关来源，并以结构化报告的形式返回结果。

对于软件开发任务，请明确预期实现和验证方式：

在代码仓库中实现请求的变更，运行相关测试，并准备好完整成果以供审核。

这些是自然语言任务示例，而非特殊命令语法。一次运行具体可使用哪些工具，取决于已配置的引擎、沙箱、知识来源、技能和集成。

通过 Slack 工作

配置原生 Slack 集成后，用户可以提及 Agent 来启动任务。回复、附件、制品和审批请求都会保留在 Slack 线程中。这样既能使用与 Web 界面相同的运行路径，又能让协作留在原始渠道内。

使用组织知识和技能

知识、Wiki 内容和团队记忆可以提供组织范围内的上下文及引用来源。可复用指令还可以从 GitHub 以带版本控制的 SKILL.md 技能形式导入。useAgent 可以自动重新同步这些技能，并将相关技能排序后加入每轮交互。

自托管 useAgent

useAgent 可以在任何 Linux 主机上运行，包括 AWS、Google Cloud、Azure、Hetzner 或裸机服务器。代码仓库提供了与提供商无关的部署脚本，以及一个使用 Terraform 构建、可通过单条命令部署的 Hetzner 参考主机。

准备好 Linux 主机和所需参数后，从代码仓库调用部署脚本：

SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
  infra/self-host/deploy-app.sh /path/to/this/repo

配置过程通过 SSH 连接目标机器。请查阅 infra/self-host/README.md，了解完整的生产环境指南和所需环境信息，不要将上述简化示例视为完整的安全配置。

选择沙箱运行时

  • Daytona：一种托管式沙箱服务，可与任何云平台上的控制平面主机配合使用。README 将其描述为最容易上手的选项。
  • CubeSandbox：面向希望在自有硬件上运行沙箱并要求数据完全本地化的组织的自托管运行时。

两种运行时均位于同一个沙箱契约之后，使控制平面能够编排 Agent 工作，而无需让其核心运行模型绑定某个特定沙箱提供商。

高级运维技巧

  • 固定发布标签：由于项目仍处于 Alpha 阶段，固定使用已知标签可减少 API 或 schema 变化导致的意外故障。
  • 保护 Postgres：事件日志是运行任务的事实来源。请据此制定数据库备份和运维策略。
  • 将凭据保留在网关中：不要通过将长期有效的集成密钥复制到沙箱中来绕过该架构。
  • 审慎使用审批：对于破坏性操作，请保持人工介入控制处于启用状态，尤其是在任务通过 Slack 或计划任务启动时。
  • 根据运维需求选择沙箱：Daytona 提供托管式方案，而 CubeSandbox 支持自托管执行和数据本地化。
  • 持续运行类型检查：共享契约横跨多个工作区，因此在进行跨软件包变更后，请运行 bun run typecheck。
  • 查看生产部署路径：完整部署指南位于 infra/self-host/ 下，附加的不可变容器发布路径则记录在 docs/operations/immutable-releases.md 中。
  • 检查请求流程：代码仓库在 docs/architecture/request-flow.html 中提供了交互式图表，可用于深入研究架构。

集成与交付界面

除了原生 Slack 和 GitHub 支持外，平台还通过连接器提供 Gmail、Linear、Notion 和 HubSpot 集成。OAuth 由代理服务处理，令牌在服务器端进行密封保护。工作区界面包括知识库、团队记忆、技能、运行手册和计划自动化任务。

GitHub 集成支持 GitHub App 身份验证、代码仓库克隆和 pull request 工作流。无论采用哪种集成，工具调用都会经过可信网关，而不会将凭据直接暴露给 Agent 工作站。

许可证注意事项

useAgent 按照 GNU AGPL v3.0-only 许可证分发。用户可以根据这些条款使用、修改和自托管该平台。对于专有嵌入、OEM 或白标产品、不承担 AGPL 义务的分发方式或其他许可需求，useAgent 还提供商业许可证。

总结

useAgent 将多个 Agent 引擎、由 Postgres 支持的持久化运行、隔离的 Linux 沙箱、组织上下文、安全集成、审批机制和可编辑制品整合到一个可自托管的平台中。你可以先使用 Bun 和 pgvector 在本地启动项目，通过类型检查器验证 monorepo，然后在迁移至 Linux 生产主机时使用文档中说明的自托管部署路径。