zoogent

ZooGent

轻量级 AI Agent 编排器，内置 Architect AI。支持多团队——在单个实例中运行彼此隔离的 Agent 团队。描述你想要自动化的内容，即可获得可运行的 Agent。

快速开始

npx zoogent create my-agents
cd my-agents
npx zoogent start

打开 http://localhost:3200。创建账号 > 创建团队 > 在团队设置中添加 Anthropic API 密钥 > 前往 Architect 并描述你想要自动化的内容。

什么是 ZooGent

ZooGent 是 AI Agent 团队的进程管理器。它会启动 Agent、在它们之间分派任务、跟踪成本并收集日志。每个 Agent 都是独立脚本，会调用自己的 LLM。

多团队隔离——一个实例，多个团队。每个团队都有自己的 Agent、技能、记忆、知识库、Architect 聊天和 API 密钥。各团队无法查看彼此的数据。

两种使用方式：

1. 聊天 UI——在浏览器中打开 Architect 页面，用日常语言描述任务。Architect AI 会设计团队、创建技能、编写 Agent 代码并测试所有内容。

2. Claude Code + MCP——将 MCP 连接到 Claude Code，在终端中全面掌控代码和配置，构建 Agent。

两种方式使用相同的 API、数据库和 Agent。选择最适合你工作流的方式即可。

开始使用

路径 1：Web UI + Architect

本地

npx zoogent create my-agents
cd my-agents
npx zoogent start

1. 打开 http://localhost:3200
2. 创建账号
3. 创建团队
4. 前往团队设置 > 添加你的 Anthropic API 密钥
5. 前往 Architect > 描述你想要自动化的内容

Architect 会通过对话设计 Agent、编写技能、生成代码并测试所有内容。

服务器

npx zoogent create my-agents
cd my-agents
npx zoogent start -d

在 .env 中将 BETTER_AUTH_URL 设置为你的公网 URL。使用反向代理（nginx、Caddy），或通过 Docker 部署（参见部署部分）。Web UI 保持不变，只是改为远程访问。

路径 2：Claude Code + MCP

本地

在本地启动服务，然后通过 MCP 连接 Claude Code：

npx zoogent create my-agents
cd my-agents
npx zoogent start -d

将 MCP 服务添加到 Claude Code。请在你想要使用的项目目录中运行——每个项目通常绑定到自己的 ZooGent 实例（使用各自的 SQLite、团队、Agent 和 API 密钥），因此 MCP 配置应放在项目中：

claude mcp add zoogent -s project -- npx zoogent mcp

-s project 会将配置写入项目根目录中的 .mcp.json——提交该文件后，克隆仓库的队友也会自动获得相同的 MCP 配置。

Claude Code 会自动发现本地服务。让 Claude 创建团队并设计你的 Agent。

远程服务

将 ZooGent 部署到服务器（参见部署）。打开 Web UI，创建账号，然后前往设置 > 生成 API 密钥。

请在需要连接此 ZooGent 实例的项目目录中运行：

claude mcp add zoogent -s project \
  -e ZOOGENT_URL=https://your-domain.com \
  -e ZOOGENT_API_KEY=zg_your-key-from-settings \
  -- npx zoogent mcp

每个项目都可以连接到自己的 ZooGent（本地或远程），并使用各自的 URL 和 API 密钥。将配置保存在项目的 .mcp.json 中，可以明确记录这种对应关系。只有在所有项目共用一个 ZooGent 实例时，才改用 -s user。

{
  "mcpServers": {
    "zoogent": {
      "command": "npx",
      "args": ["zoogent", "mcp"],
      "env": {
        "ZOOGENT_URL": "https://your-domain.com",
        "ZOOGENT_API_KEY": "zg_your-key-from-settings"
      }
    }
  }
}

Claude Code 会连接到远程服务。通过 MCP 工具创建团队、设计 Agent、编写代码。Agent 会在服务器上运行。

工作原理

1. 为你的业务流程创建团队
2. 在团队的 Architect 聊天中描述你想要自动化的内容
3. Architect 创建 Agent（包含目标、计划和模型）并编写它们的代码
4. Agent 按计划或事件运行，并通过任务相互通信
5. Agent 从经验中学习（记忆）并共享知识（团队知识库）
6. 出现故障时，Architect 会查看错误日志并提出修复建议

示例

社交媒体监控。 Scout Agent 每 2 小时扫描一次 Reddit 和 Hacker News，查找相关帖子。评论撰写 Agent 按合适的语气起草回复。反馈收集 Agent 在次日检查哪些评论获得了点赞，哪些被忽略。团队不断学习并调整。

发票处理。 监听 Agent 轮询电子邮件收件箱，查找新发票。解析器提取金额、日期和供应商信息。路由器通过 API 在你的会计系统中创建条目。异常检测器标记看起来异常的发票，供人工审核。

客户支持自动化。 接收 Agent 通过 webhook 接收客户请求。分析器对紧急程度和类型进行分类，并在项目跟踪工具中为团队成员创建任务。跟进 Agent 监控任务完成情况，并在客户请求解决后通知客户。

功能

团队

在一个实例中运行多个相互隔离的团队。每个团队都有自己的 Agent、技能、记忆、知识库、Architect 聊天和 Anthropic API key。顶部导航：团队 / 成员 / 设置。团队子导航：Architect / Agent / 任务 / 成本 / 技能 / 记忆 / 知识库 / 设置。

Architect AI

内置的 Claude 驱动聊天工具，用于设计和管理你的 Agent 团队。通过对话创建 Agent、编写技能、生成 TypeScript 代码、分配技能、触发运行、读取日志。通过 SSE 流式传输，并实时显示工具执行情况。每个团队都有自己的 Architect 和独立的聊天记录。

Agent 运行时

对于 typescript，Agent 可以从经过精选和认可的集合中导入模块：@anthropic-ai/sdk、openai、@google/generative-ai、axios、cheerio、googleapis、zod、p-limit/p-retry/p-map/p-queue、date-fns、yaml、csv-parse/csv-stringify、cheerio、fast-xml-parser、marked、turndown、slugify、tiktoken、nodemailer、imapflow、mailparser、jsonwebtoken，以及所有 Node 内置模块。上传时遇到未知导入会失败，并显示易于理解的错误。完整列表位于 code-generation 系统技能中——通过 MCP 调用 get_agent_guide("code-generation")。

Agent 类型

5 种通信渠道

技能

包含指令和知识的 Markdown 文档，按团队存储在数据库中。分配给 Agent，并在启动时注入其上下文。可通过 Architect 聊天、MCP 或 API 创建。系统技能（team-design、agent-patterns、code-generation 等）是全局的，由 Architect AI 使用。

Agent 存储

用于存储 Agent 工作数据的键值存储，可在多次运行之间持久保存。跟踪 URL、保存已处理的 ID、缓存状态。可选设置 TTL，自动过期。

await storeSet('seen_urls', ['https://...'], 604800); // expires in 7 days
const urls = await storeGet('seen_urls');

成本跟踪

按 Agent 和团队跟踪支出。设置每月预算并启用硬性限制——超出预算时 Agent 将无法运行。在团队设置中设置团队预算，在 Agent 配置中设置单个 Agent 的预算。

自我修复

Agent 运行失败时，错误信息及 stderr 摘录会显示在团队的 Architect 聊天中。打开 Architect，查看问题所在，并让它修复代码。

Web Dashboard

浅色和深色主题。全局页面：团队、成员、设置。团队页面：Architect（聊天）、Agents、任务、成本、技能、记忆、知识。

CLI 命令

zoogent create <name>  # Create new project (recommended)
zoogent init           # Initialize in current directory
zoogent start          # Start server (foreground)
zoogent start -d       # Start server (daemon)
zoogent stop           # Stop daemon
zoogent status         # Check if running
zoogent logs           # View server logs (-f to follow)
zoogent mcp            # Start MCP server (stdio)

部署

服务端（无需 Docker）

npx zoogent create my-agents
cd my-agents
npx zoogent start -d

Docker / Dokploy / Railway

无需仓库。将此 compose 粘贴到托管平台（Dokploy、Railway 等）并部署。

services:
  app:
    image: node:24-slim
    working_dir: /app
    command: sh -c "npm install [email protected] @anthropic-ai/sdk && npx zoogent init && npx zoogent start"
    expose:
      - "3200"
    environment:
      - DATABASE_URL=./data/zoogent.db
      - PORT=3200
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - BETTER_AUTH_URL=${BETTER_AUTH_URL}
    volumes:
      - zoogent-data:/app/data
    restart: unless-stopped

volumes:
  zoogent-data:

在平台的环境设置中设置 BETTER_AUTH_SECRET（生成方式：openssl rand -hex 32）和 BETTER_AUTH_URL（你的公开 URL）。

要升级 ZooGent：将 [email protected] 改为新版本并重新部署。

必需的环境变量

Agent SDK

TypeScript Agent 使用 zoogent/client 处理上下文和任务流程：

import {
  // Tasks
  createTask, getMyTasks, checkoutTask, completeTask, failTask,
  // Reporting
  reportCost, reportMemory, reportTeamKnowledge,
  // Context
  getGoal, getSkills, getMemories, getTeamKnowledge,
  // Store
  storeGet, storeSet, storeDelete, storeKeys,
  // Skills
  loadSkill, loadSkills,
  // Consensus
  submitEvaluation,
  // Health
  heartbeat,
} from 'zoogent/client';

对于 runtime="typescript" 的 Agent，zoogent 会托管这些依赖项，你的代码只需导入即可。 对于任何语言的 runtime="exec"，直接调用 HTTP API：有关报告约定，请参阅 /llms-agent-guide.txt 端点。

所有 SDK 调用均采用故障开放模式（错误会被静默捕获）。所有函数都会自动读取 ZOOGENT_* 环境变量。

工作流

1. MCP: create_agent with source=<boilerplate> → zoogent bundles with esbuild, agent is ready
2. MCP: trigger_agent + get_logs → test
3. MCP: write_agent_code with new source → re-bundle, iterate

无需维护本地 agents/ 目录来保持同步。zoogent 的数据库是真实数据源。在远程部署中， 相同的 MCP 调用可通过 ZOOGENT_URL 使用，Agent 代码本身无需执行任何部署步骤。

环境变量

服务端

注入到 Agent 的变量

技术栈

• 运行时：Node.js 24、TypeScript
• HTTP：Hono（JSX SSR）
• 数据库：SQLite（better-sqlite3、WAL、FTS5）+ Drizzle ORM
• 身份验证：Better Auth（邮箱 + 密码、会话）
• AI：Anthropic SDK（Architect 使用 Claude）
• UI：htmx + Tailwind CDN（服务端渲染）
• MCP：@modelcontextprotocol/sdk（stdio）
• Cron：node-cron

安全性

• Agent 环境变量静态加密（AES-256-GCM）
• 每个团队的设置（API 密钥）均在数据库中加密
• 在设置 UI 中管理 API 密钥（多个命名密钥，存储在数据库中）
• 统一身份验证：localhost 绕过 + API 密钥（来自数据库）+ 会话 Cookie
• 技能路径的路径遍历防护
• 日志清理（从 stdout/stderr 中剥离 API 密钥）
• 首位用户为所有者，完成设置后关闭注册
• 团队隔离：Agent、技能、记忆和知识均按团队划分
• Agent 沙箱：TypeScript Agent 始终在 Node.js 24 --permission 模式下运行。写入权限仅限团队共享文件夹（ZOOGENT_SHARED_DIR = data/teams/{id}/shared/）。禁止生成 child_process，不允许使用原生插件。应用 --max-old-space-size=512。
• 团队共享文件夹：data/teams/{id}/shared/ — 同一团队中的 Agent 可以交换文件（图像、视频、CSV），无需云存储。如果将 data/ 挂载为 Docker 卷，重启后文件仍会保留。

许可证

MIT