zoogent

ZooGent

Architect AI を内蔵した軽量な AI エージェントオーケストレーターです。複数チームに対応しており、1 つのインスタンスで分離されたエージェントチームを実行できます。自動化したい内容を説明するだけで、実際に動作するエージェントを利用できます。

クイックスタート

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

http://localhost:3200 を開きます。アカウントを作成 > チームを作成 > チーム設定で Anthropic API キーを追加 > Architect に移動して、自動化したい内容を説明します。

ZooGent とは

ZooGent は AI エージェントチーム向けのプロセスマネージャーです。エージェントを起動し、タスクを振り分け、コストを追跡し、ログを記録します。各エージェントは、それぞれ独自の LLM を呼び出すスタンドアロンのスクリプトです。

マルチチーム分離 - 1 つのインスタンスで複数のチームを運用できます。各チームは独自のエージェント、スキル、メモリ、ナレッジ、Architect チャット、API キーを持ちます。チーム同士が互いのデータを見ることはありません。

利用方法は 2 通りです。

1. チャット UI - ブラウザーで Architect ページを開き、自然な言葉でタスクを説明します。Architect AI がチームを設計し、スキルを作成し、エージェントのコードを書き、すべてをテストします。

2. Claude Code + MCP - MCP を Claude Code に接続し、コードや設定を完全に制御しながら、ターミナルからエージェントを構築します。

どちらの方法でも同じ API、同じデータベース、同じエージェントを使用します。ワークフローに合った方法を選んでください。

はじめに

方法 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 は会話を通じてエージェントを設計し、スキルを作成し、コードを生成して、すべてをテストします。

サーバー

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、チーム、エージェント、API キー）に紐付けるため、MCP の設定はプロジェクト内に配置する必要があります。

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

-s project を指定すると、プロジェクトのルートにある .mcp.json に設定が書き込まれます。このファイルをコミットすれば、リポジトリをクローンしたチームメイトも同じ MCP 設定を自動的に利用できます。

Claude Code はローカルサーバーを自動検出します。Claude にチームの作成とエージェントの設計を依頼してください。

リモートサーバー

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

各プロジェクトは、それぞれ独自の URL と API キーを使って、個別の ZooGent（ローカルまたはリモート）を指定できます。設定をプロジェクトの .mcp.json に保存すると、この対応関係が明確になります。すべてのプロジェクトで共有する ZooGent インスタンスが 1 つだけの場合に限り、代わりに -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 ツールを通じて、チームの作成、エージェントの設計、コードの作成を行えます。エージェントはサーバー上で実行されます。

仕組み

1. ビジネスプロセス用のチームを作成します
2. チームの Architect チャットで、自動化したい内容を説明します
3. Architect がエージェント（目標、スケジュール、モデルを含む）を作成し、コードを書きます
4. エージェントはスケジュールまたはイベントに応じて実行され、タスクを通じて連携します
5. エージェントは経験から学習し（メモリ）、ナレッジを共有します（チームナレッジ）
6. 問題が発生すると、Architect がエラーログを確認し、修正を提案します

例

ソーシャルメディアのモニタリング。 Scout エージェントが、関連する投稿を探して Reddit と Hacker News を 2 時間ごとにスキャンします。コメント作成エージェントが適切なトーンで返信の草案を作成します。フィードバック収集エージェントが翌日に、どのコメントに賛成票が集まり、どのコメントが無視されたかを確認します。チームはそこから学び、適応します。

請求書の処理。 監視エージェントがメールの受信トレイを確認し、新しい請求書を探します。パーサーが金額、日付、販売元の情報を抽出します。ルーターが API を介して会計システムにエントリーを作成します。異常検知エージェントが、異常に見える請求書にフラグを付け、人による確認を促します。

カスタマーサポートの自動化。 受付エージェントが Webhook 経由で顧客からのリクエストを受け取ります。分析エージェントが緊急度と種類を分類し、プロジェクトトラッカーで人間のチームメンバー向けのタスクを作成します。フォローアップエージェントがタスクの完了状況を監視し、リクエストが解決したら顧客に通知します。

機能

チーム

1 つのインスタンス内に、互いに独立した複数のチームを作成できます。各チームには、独自のエージェント、スキル、メモリ、ナレッジ、Architect チャット、Anthropic API キーがあります。ヘッダーナビゲーション：Teams / Members / Settings。チームのサブナビゲーション：Architect / Agents / Tasks / Costs / Skills / Memory / Knowledge / Settings。

Architect AI

エージェントチームの設計と管理を行う、Claude を活用した組み込みチャットです。会話を通じて、エージェントの作成、スキルの作成、TypeScript コードの生成、スキルの割り当て、実行の開始、ログの読み取りなどを行います。SSE ストリーミングにより、ツールの実行状況をリアルタイムで表示します。各チームには、個別のチャット履歴を持つ専用の Architect があります。

エージェントのランタイム

typescript のエージェントは、厳選された許可済みパッケージからインポートできます：@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") を呼び出してください。

エージェントの種類

5 つのコミュニケーションチャネル

スキル

指示とナレッジを含む Markdown ドキュメントで、チームごとにデータベースに保存されます。エージェントに割り当てると、起動時にそのコンテキストに挿入されます。Architect チャット、MCP、または API から作成できます。システムスキル（team-design、agent-patterns、code-generation など）はグローバルに利用でき、Architect AI が使用します。

エージェントストア

実行をまたいで保持される、エージェントの作業データ用キー・バリューストレージです。URL の追跡、処理済み ID の保存、状態のキャッシュに使用できます。自動失効のための TTL も任意で設定できます。

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

コストの追跡

エージェントごと、チームごとの支出を追跡します。上限に達すると実行を停止する、月間予算を設定できます。チーム予算は Team Settings で、エージェントごとの予算はエージェント設定で指定します。

自己修復

エージェントが失敗すると、stderr の抜粋とともにエラーがチームの Architect チャットに表示されます。Architect を開いて問題を確認し、コードを修正するよう依頼できます。

Web ダッシュボード

ライトテーマとダークテーマ。全体ページ：Teams、Members、Settings。チームページ：Architect（チャット）、Agents、Tasks、Costs、Skills、Memory、Knowledge。

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 エージェントは、コンテキストとタスクのフローに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"のエージェントでは、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 の DB です。リモートデプロイでは、 ZOOGENT_URLに対して同じ MCP 呼び出しを使用でき、エージェントコード自体のデプロイ手順は必要ありません。

環境変数

サーバー

エージェントに注入される変数

技術スタック

• ランタイム：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

セキュリティ

• エージェントの環境変数は保存時に暗号化されます（AES-256-GCM）
• チームごとの設定（API キー）はデータベース内で暗号化されます
• API キーは Settings UI で管理されます（名前付きの複数キーを DB に保存）
• 統合認証：localhost のバイパス + API キー（DB から取得）+ セッション Cookie
• スキルパスに対するパストラバーサル対策
• ログのサニタイズ（標準出力／標準エラー出力から API キーを除去）
• 最初のユーザーはオーナーとなり、セットアップ後は登録が閉じられます
• チーム分離：エージェント、スキル、メモリー、ナレッジはチームごとにスコープされます
• エージェントのサンドボックス：TypeScript エージェントは常に Node.js 24 の--permissionを指定して実行されます。書き込みアクセスはチームの共有フォルダー（ZOOGENT_SHARED_DIR = data/teams/{id}/shared/）に制限されます。child_processの起動とネイティブアドオンは禁止されています。--max-old-space-size=512が適用されます。
• チーム共有フォルダー：data/teams/{id}/shared/ — 同じチーム内のエージェントは、クラウドストレージを使わずにファイル（画像、動画、CSV）をやり取りできます。data/が Docker ボリュームとしてマウントされている場合、再起動後も保持されます。

ライセンス

MIT