メインコンテンツへ移動
AIチュートリアル

useAgentでAI同僚を構築・セルフホストする

useAgentがClaude Code、Codex、OpenCodeを1つのインターフェースに統合する仕組みを学びます。このチュートリアルでは、イベントソース型アーキテクチャ、安全なサンドボックス、前提条件、ローカル環境のセットアップ、基本的なワークフロー、本番環境でのセルフホスティング、連携、検証、信頼性の高いAIエージェント処理を運用するためのヒントを解説します。

約15分で読了
useAgentでAI同僚を構築・セルフホストする
アルファ版に関する警告: useAgent は現在も活発に開発されています。リリース間で API やスキーマが変更される可能性があるため、安定性が重要な場合はリリースタグを固定してください。

useAgent とは？

useAgent は、Claude Code、Codex、OpenCode などのエージェントを実行するためのオープンソース AI コワーカー・プラットフォームです。会話形式の回答だけを返すのではなく、エージェントは分離された Linux 環境で作業し、完成した Web サイト、プレゼンテーション、スプレッドシート、調査レポート、テスト済みのプルリクエストを納品できます。

各スレッドには、ターミナル、リポジトリ、ブラウザ、noVNC による可視デスクトップを備えたワークステーションが割り当てられます。実行は Postgres のイベントソース型タイムラインとして表現されるため、完了後も永続化され、再生や検査が可能です。

useAgent のワークスペースとエージェント作成画面

主な機能

  • 複数エージェントに対応する単一インターフェース: プロバイダー固有のエンジンが、標準イベント契約を介して通信します。
  • 永続的な実行: バックエンドが再起動しても実行は保持され、復旧時にはアクティブなセッションを再検査して完了済みの作業を引き継げます。
  • 分離された Linux サンドボックス: 各スレッドに個別のワークステーションが割り当てられます。Daytona と CubeSandbox が共通サンドボックス契約を実装します。
  • 信頼できるツールゲートウェイ: 認証情報はエージェントのサンドボックス内に入れず、コントロールプレーンに保持されます。
  • 人による承認: 破壊的なツール呼び出しは、Web インターフェースまたは Slack で承認されるまで一時停止し、引数に紐付いた一回限りの機能を使って再開します。
  • GitHub ベースのスキル: チームはバージョン管理された SKILL.md ファイルをインポートして変更を同期し、関連性の高いスキルをエージェントのターンに組み込めます。
  • 組織のコンテキスト: ナレッジ検索には引用が含まれ、チームメモリは人間がレビューする学習レーンを利用します。
  • ネイティブアーティファクト: このプラットフォームは、ネイティブレンダラーによるバージョン管理された DOCX、XLSX、PPTX、PDF ファイルに対応します。
  • 複数の入力チャネル: 作業は Web アプリケーション、Slack、REST API、またはスケジュールから受け付けられます。

アーキテクチャの仕組み

useAgent は、セルフホスト型のコントロールプレーンと、エージェントが作業する環境を分離しています。入力チャネルは同じ実行経路を通じて実行を作成します。エンジンアダプターはプロバイダー固有のアクティビティを標準イベントに変換し、各スレッドには分離されたサンドボックスが割り当てられます。

特に重要なアーキテクチャ上の特性は、次の 3 つです。

  1. エンジンは交換可能: エンジンを変更しても、スレッド、アーティファクト、メモリの共通表現を置き換える必要はありません。
  2. Postgres が信頼できる唯一の情報源: すべての実行はイベントログとして保存されるため、再起動後も正確な再生と検査が可能です。
  3. 秘密情報はサンドボックスの外部に保持: 統合機能は信頼できるゲートウェイを介して型付きツールとして公開され、認証情報はコントロールプレーンにのみ保存されます。
useAgent のセッションタイムラインとワークスペース

リポジトリの構成

  • frontend/ には、セッション、スキル、プレイブック、Wiki、アーティファクト、自動化、設定のための製品インターフェースが含まれます。
  • backend/ には、認証、実行オーケストレーション、エンジンアダプター、サンドボックス、ナレッジ、メモリ、アーティファクト、コネクターが含まれます。
  • packages/ には、共有イベント契約、ワークピース、アーティファクト形式、レンダラー、および関連パッケージが含まれます。
  • docs-site/ にはドキュメントサイトが含まれます。
  • infra/self-host/ には、プロバイダーに依存しないデプロイツールと Hetzner Terraform リファレンスが含まれます。
  • memory/ には、オプションのチームメモリサービスが含まれます。

前提条件

ローカル開発環境のインストールには、Bun と、pgvector 拡張を備えた Postgres 16 以降が必要です。標準の 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

1 つ目のコマンドは Postgres をポート 5432 で公開します。2 つ目はアプリケーションが使用する接続文字列を設定します。trust 設定はローカル開発には便利ですが、本番環境では適切に保護されたデータベース認証情報を使用してください。

ステップ 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: バックエンドとフロントエンドを起動する

別々のターミナルセッションを開き、2 つの開発プロセスを起動します。

bun run dev:backend
bun run dev:frontend

バックエンドはポート 3201 で API とオーケストレーションサービスを提供します。フロントエンドはポート 3400 で動作し、/api/* 配下のリクエストをバックエンドにプロキシします。

ブラウザで http://localhost:3400 を開くと、インターフェースにアクセスできます。プロバイダーとサンドボックスの設定は異なる場合があるため、エージェントエンジンへの接続や実行環境のプロビジョニングを行う際は、最新の useAgent ドキュメントに従ってください。

ステップ 4: コードベースを検証する

インストール後、または変更を提出する前に、リポジトリ全体の型チェッカーを実行します。

bun run typecheck

このコマンドはリポジトリ内のすべてのパッケージを対象とし、共有コントラクト、バックエンド、フロントエンド間の互換性のない変更を検出するのに役立ちます。

基本的な使い方

エージェントの実行を作成する

  1. ポート 3400 でウェブインターフェースを開きます。
  2. エージェントコンポーザーを使って、必要な完成結果を説明します。
  3. 実行を開始し、ライブイベントのタイムラインを確認します。
  4. エージェントの進行中に、ターミナル、ブラウザ、デスクトップ、ワークスペースでのアクティビティを確認します。
  5. 破壊的なツール操作を許可する前に、承認カードを確認します。
  6. セッションから返された完成済みの成果物またはリポジトリの作業結果を取得します。

タスクは、次のように具体的な成果物を中心に定義できます。

トピックを調査し、関連する情報源を引用して、構造化されたレポートとして結果を返してください。

ソフトウェア開発では、期待する実装と検証方法を定義します。

リポジトリに要求された変更を実装し、関連するテストを実行して、レビュー用の完成した作業を準備してください。

これらは自然言語によるタスク例であり、特別なコマンド構文ではありません。実行で利用できる正確なツールは、設定されたエンジン、サンドボックス、ナレッジソース、スキル、インテグレーションによって異なります。

Slack を通じて作業する

ネイティブ Slack インテグレーションが設定されている場合、ユーザーはエージェントにメンションして作業を開始できます。返信、添付ファイル、成果物、承認リクエストは Slack スレッド内に残ります。これにより、元のチャンネルでコラボレーションを続けながら、ウェブインターフェースと同じ実行経路を利用できます。

組織のナレッジとスキルを利用する

ナレッジ、Wiki コンテンツ、チームの記憶を、引用付きの組織スコープのコンテキストとして利用できます。再利用可能な指示は、バージョン管理された SKILL.md スキルとして GitHub からインポートすることもできます。useAgent はこれらのスキルを自動的に再同期し、各ターンに関連するスキルをランク付けして組み込めます。

useAgent のセルフホスティング

useAgent は、AWS、Google Cloud、Azure、Hetzner、ベアメタルなど、あらゆる Linux ホストで実行できます。リポジトリにはプロバイダーに依存しないデプロイスクリプトに加え、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: 自社のハードウェア上でサンドボックスを運用し、完全なデータローカリティを必要とする組織向けのセルフホスト型ランタイムです。

どちらのランタイムも同じサンドボックスコントラクトの背後で動作するため、コントロールプレーンは、コアの実行モデルを特定のサンドボックスプロバイダーに依存させずに、エージェントの作業をオーケストレーションできます。

高度な運用のヒント

  • リリースタグを固定する: プロジェクトはアルファ版であるため、既知のタグを固定すると、変更される API やスキーマによる予期しない破損を減らせます。
  • 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 インテグレーションは、アプリ認証、リポジトリのクローン、プルリクエストのワークフローをサポートします。インテグレーションにかかわらず、ツール呼び出しは信頼できるゲートウェイを経由するため、認証情報がエージェントのワークステーションに直接公開されることはありません。

ライセンスに関する考慮事項

useAgentはGNU AGPL v3.0-onlyライセンスの下で提供されています。このライセンスの条件に従って、使用、変更、セルフホスティングが可能です。独自仕様への組み込み、OEM製品やホワイトレーベル製品、AGPL上の義務を伴わない配布、その他のライセンス要件には、商用ライセンスを利用できます。

まとめ

useAgentは、複数のエージェントエンジン、Postgresを基盤とする永続的な実行環境、分離されたLinuxサンドボックス、組織コンテキスト、安全なインテグレーション、承認機能、編集可能なアーティファクトを、セルフホスティング可能な1つのプラットフォームに統合します。まずBunとpgvectorを使ってローカルで開始し、型チェッカーでモノレポを検証してから、Linux本番ホストへ移行する際は、ドキュメントに記載されたセルフホスティング手順を利用してください。