🤖 技術調査 - Trinity（自己ホスト型 AI エージェント運用基盤）

Trinity は、AI エージェントを本番環境で稼働させるための自己ホスト型オーケストレーション基盤です。Claude Code や Gemini CLI で開発したエージェントを Docker コンテナとして隔離実行し、スケジューリング・観測性・監査証跡・マルチエージェント連携を付与します。本調査では、構造（C4 モデル）・データモデル・構築/利用方法・運用までを一次情報（README / 開発者向け CLAUDE.md / src/backend/db/schema.py 等の実装ソース）に基づいて整理します。

■概要

Trinity は、AI エージェントを本番環境で稼働させるための自己ホスト型オーケストレーション基盤です。開発元は Ability.ai、ライセンスは Apache-2.0、現行バージョンは v0.6.1 です。

Trinity が解決する課題

AI エージェントの本番運用には 3 つの壁があります。SaaS プラットフォームはデータが自社の管理外に出ます。自前実装は 6〜12 か月・数千万円規模の工数がかかります。フレームワーク単体ではフリート管理・スケジューリング・監査証跡がありません。Trinity はこの 3 つを同時に解決します。

位置づけ

「Claude Code がエージェントを書く、Trinity が本番で動かす」という分業が公式の位置づけです。Claude Code（または Gemini CLI）で開発したエージェントを Trinity に登録すると、Docker コンテナとして隔離されたランタイムで稼働し、スケジューリング・監視・監査が自動で付与されます。

2 つの運用モデル

どちらのモデルでも、データは第三者の SaaS 環境に流出しません。

関連技術との比較

■特徴

Trinity の機能は 4 つのカテゴリに整理されます。

フリート可観測性（Fleet Observability）

• グラフビュー — エージェント群の接続トポロジーをリアルタイム描画。各エージェントの成功率・コスト・リソース使用量を表示します。
• タイムラインビュー — ガントチャート形式の実行履歴。トリガー種別（手動 / スケジュール / MCP / エージェント起動 / 公開 / 課金）ごとに色分けされます。
• ホストテレメトリー — ダッシュボードヘッダーにホストの CPU・メモリ・ディスクをリアルタイム表示します。
• フリートヘルス監視 — Docker・ネットワーク・ビジネスロジックの多層ヘルスチェック。WebSocket でアラートを配信します。
• OpenTelemetry 連携 — コスト・トークン使用量・生産性の指標を Grafana や Datadog にエクスポートできます。マルチエージェント呼び出しの分散トレースもサポートします。

エージェントランタイム（Agent Runtime）

• コンテナ隔離 — エージェント 1 つにつき 1 Docker コンテナ。リソースを独立して割り当てます。
• マルチランタイム — Claude Code（Anthropic）と Gemini CLI（Google）をエージェントごとに選択できます。
• モデル選択 — タスク・スケジュールごとに Claude モデル（Opus / Sonnet / Haiku）を切り替えられます。
• カスタムダッシュボード — dashboard.yaml で定義した 11 種類のウィジェットで、エージェントの指標を可視化します。
• プレイブック — エージェントが持つスキル（.claude/skills/）を UI から直接呼び出せます。
• 動的思考ステータス — エージェントの動作状況（ファイル読込・コード検索など）をリアルタイムにラベル表示します。
• 永続メモリ — ファイルベースおよびデータベースバックの記憶がセッション間を通じて維持されます。
• 実行ガードレール — コンフィグで設定した確定的な安全制約をエージェントごとにオーバーライドできます。
• 実行キュー — 並列上限を超えたタスクを SQLite バックの FIFO キューに積み、再起動後も保持します。
• 暴走防止 — max_turns パラメータでエージェントの実行深度を上限設定できます。

オーケストレーション（Orchestration）

• エージェント間通信 — 階層的な委任と細粒度のアクセス制御でエージェントが互いに呼び出し合えます。
• 並列タスク実行 — オーケストレーター/ワーカーパターン向けにステートレスな並列実行をサポートします。
• 共有フォルダ — Docker ボリューム経由でエージェント間のファイル共有を実現します。
• システムマニフェスト — 1 枚の YAML ファイルでマルチエージェントシステムを定義して一括デプロイできます。
• スケジューリング — cron ベースの自動実行。Redis 分散ロックで多重起動を防ぎます。
• MCP サーバー — 約 80 ツールを持つ Model Context Protocol サーバーで外部からエージェントを操作できます（実装 src/mcp-server/src/tools/*.ts で 80 ツール登録。README は 74、開発者向け CLAUDE.md は 62 と記載しており、ツール追加に伴い公称値は陳腐化している）。
• チャネルアダプター — Slack・Telegram・WhatsApp をメッセージングフロントエンドとして接続できます。
• 統合アクセス制御 — メール認証アローリストが Web・Slack・Telegram のすべてに横断適用されます。
• プロアクティブメッセージ — エージェントが自発的にユーザーへメッセージを送信できます。

運用管理（Operations）

• テンプレート展開 — ビルトインテンプレートまたは GitHub リポジトリからエージェントを作成できます。
• クレデンシャル管理 — ファイル直接注入と Git 暗号化ストレージ（.credentials.enc）で秘密情報を安全に扱います。
• プラットフォーム監査ログ — ライフサイクル・認証・MCP イベントの追記専用クロスカッティング証跡（admin のみ閲覧）。
• ロール階層 — 4 段階 RBAC（user < operator < creator < admin）を最初のログイン時のホワイトリストで制御します。
• ライブ実行ストリーミング — 実行ログを Web UI にリアルタイム配信します。
• エフェメラル SSH アクセス — 時間限定の SSH 資格情報でエージェントコンテナに直接ターミナル接続できます。
• 公開エージェントリンク — 未認証ユーザー向けに共有リンクを発行できます。セッション永続化と Slack 連携に対応しています。
• 課金対応（x402） — Nevermined x402 決済プロトコルでエージェントごとに有料アクセスを設定できます。
• モバイル管理 PWA — /m でアクセスできるモバイル向け管理画面をホーム画面にインストールできます。
• サブスクリプション管理 — Claude Max/Pro サブスクリプショントークンを複数エージェントで集中管理できます。

■構造

●システムコンテキスト図

システムコンテキスト図 — 要素説明

●コンテナ図

コンテナ図 — Platform Containers

コンテナ図 — Agent Network

●コンポーネント図

Backend（FastAPI）内部構成

Backend 内部構成 — Routers

Backend 内部構成 — Services

Backend 内部構成 — Channel Adapters

Backend 内部構成 — DB / Canary

Agent Container 内部構成

Agent Container 内部構成 — Runtimes

Agent Container 内部構成 — agent-server Routers

Agent Container 内部構成 — Services

Agent Container 内部構成 — Hooks（Guardrails）

ネットワーク構成図

■データ

●概念モデル

Trinity が扱うエンティティの所有関係と参照関係を示します。

●情報モデル

主要エンティティの属性・型・永続化先を示します。属性名・型・テーブル名は src/backend/db/schema.py（59 テーブルの CREATE TABLE IF NOT EXISTS 文）で裏取りしています。

永続化先サマリ

■構築方法

前提条件

• Docker および Docker Compose v2+
• Anthropic API キー（Claude ベースのエージェントを使う場合）または Google API キー（Gemini ベースの場合）

構築経路の概要

self-host — one-line install

curl -fsSL https://raw.githubusercontent.com/abilityai/trinity/main/install.sh | bash

• リポジトリのクローン、.env 生成（SECRET_KEY と ADMIN_PASSWORD を自動生成）、ベースイメージのビルド、サービス起動までを一括実行します。
• インストール先は ~/trinity です。

self-host — quickstart.sh（対話型セットアップ）

./quickstart.sh             # 対話形式で順を追ってセットアップ
./quickstart.sh --defaults  # シークレットを自動生成して非対話で起動

• 入力が不要なシナリオ（CI/CD など）では --defaults を使います。

self-host — manual install

# 1. リポジトリをクローン
git clone https://github.com/abilityai/trinity.git
cd trinity

# 2. 環境変数を設定
cp .env.example .env
# .env を開いて SECRET_KEY を設定（openssl rand -hex 32 で生成）

# 3. ベースイメージをビルド
./scripts/deploy/build-base-image.sh

# 4. サービスを起動
./scripts/deploy/start.sh

主要な環境変数は以下のとおりです。

First-time setup wizard（初回セットアップウィザード）

1. http://localhost にアクセスすると、セットアップウィザードにリダイレクトされます。
2. admin パスワード（8 文字以上）を設定します。
3. ユーザー名 admin と設定したパスワードでログインします。
4. Settings → API Keys で Anthropic API キーを登録します。

アクセス先

Trinity CLI — インストールと初期化

# インストール（pip または brew）
pip install trinity-cli
brew install abilityai/tap/trinity-cli

# インスタンスへの接続（初回のみ）
trinity init

• trinity init はインスタンス URL とメールアドレスを対話形式で入力し、確認コードを受け取ってログインします。
• 認証情報は ~/.trinity/config.json に保存されます（パーミッション 0600）。

abilities plugin（Claude Code プラグイン）— インストールと接続

# 1. マーケットプレイスを追加（一度のみ）
/plugin marketplace add abilityai/abilities

# 2. 必要なプラグインをインストール（一度のみ）
/plugin install trinity@abilityai
/plugin install create-agent@abilityai

# 3. Trinity インスタンスに接続（インスタンスごとに一度のみ）
/trinity:connect

• /trinity:connect を実行すると、インスタンス URL とメール確認コードを入力します。
• MCP API キーが自動プロビジョニングされ、.mcp.json が生成されます。

■利用方法

主要コマンドとツールの早見表

Trinity CLI コマンド

主要 MCP ツール

エージェント作成

Trinity は 3 つの方法でエージェントを作成できます。

Web UI から:

1. http://localhost を開きます。
2. Create Agent ボタンをクリックします。
3. テンプレートを選択します（blank、組み込みテンプレート、または github:org/repo@branch）。
4. 必要な認証情報を設定し、チャットを開始します。

abilities plugin から（Claude Code）:

# ウィザードでスキャフォールドしてデプロイ
/create-agent:create        # テンプレートを選択してスキャフォールド
/trinity:onboard            # Trinity への互換性チェックとデプロイ

MCP ツールから:

# テンプレートを指定してエージェントを作成
mcp__trinity__create_agent(name="my-agent", template="github:abilityai/agent-cornelius")

# ローカルディレクトリからデプロイ
mcp__trinity__deploy_local_agent(agent_name="my-agent", directory_path="./my-agent")

テンプレート構造

Trinity 互換エージェントのディレクトリ構成は以下のとおりです。

my-agent/
├── template.yaml              # Trinity メタデータ（名前・リソース・認証情報スキーマ）
├── CLAUDE.md                  # エージェント指示書（ドメインロジック）
├── .claude/
│   ├── agents/                # サブエージェント（任意）
│   ├── commands/              # スラッシュコマンド（任意）
│   └── skills/                # スキル（任意。プラットフォームライブラリに初回デプロイ時に投入）
├── .mcp.json.template         # ${VAR} プレースホルダー付き MCP 設定
└── .env.example               # 必要な環境変数のドキュメント

template.yaml の最小構成例は以下のとおりです。

name: my-agent
display_name: "My Agent"
description: "What this agent does"

resources:
  cpu: "2"
  memory: "4g"

credentials:
  mcp_servers:
    server-name:
      env_vars:
        - API_KEY
  env_file:
    - OTHER_VAR

MCP 統合の設定

.mcp.json を作成して Claude Code または任意の MCP クライアントから Trinity に接続します。

{
  "mcpServers": {
    "trinity": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

• YOUR_API_KEY は Settings → API Keys から取得した MCP API キー（trinity_mcp_... 形式）を使います。
• /trinity:connect を実行すると、このファイルが自動生成されます。

Multi-Agent System のデプロイ

複数エージェントを 1 つの YAML マニフェストでまとめてデプロイします。

マニフェストの構造:

name: content-production          # システム識別子
description: Autonomous content pipeline

prompt: |                         # 全エージェントに注入される指示（任意）
  All agents in this system collaborate on content production.

agents:
  orchestrator:                   # エージェントキー（システム内ユニーク）
    template: github:abilityai/agent-corbin
    resources:
      cpu: "2"
      memory: "4g"
    folders:
      expose: true
      consume: true
    schedules:
      - name: daily-review
        cron: "0 9 * * *"
        message: "Review today's content pipeline"
        timezone: "UTC"
        enabled: true

  writer:
    template: github:abilityai/agent-ruby
    folders:
      expose: true
      consume: true

permissions:
  preset: full-mesh               # 全エージェントが相互通信可能

permissions.preset の選択肢は以下のとおりです。

MCP ツールでデプロイ:

mcp__trinity__deploy_system(
    manifest="<YAML 文字列>",
    dry_run=False
)

REST API でデプロイ:

curl -X POST http://localhost:8000/api/systems/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"manifest": "name: my-system\nagents:\n  worker:\n    template: local:default"}'

エージェントとのチャットと操作

CLI:

# エージェントにメッセージを送信
trinity chat my-agent "What is the status of the project?"

# ログを確認
trinity logs my-agent

abilities plugin（Claude Code）:

# ローカルとリモートの変更を同期
/trinity:sync

# サーバーサイドでタスクをループ実行（bounded loop）
/trinity:loop @my-agent "work the backlog" 10 times

MCP ツール:

# 同期通信（60 秒以内に完了するタスク向け）
mcp__trinity__chat_with_agent(
    agent_name="my-agent",
    message="Process today's backlog"
)

# 非同期通信（60 秒を超えるタスク向け）
result = mcp__trinity__chat_with_agent(
    agent_name="my-agent",
    message="Process today's backlog",
    async_=True,
    parallel=True
)
# result.execution_id を使ってポーリング

# N 並列タスクをエージェントに送信して結果を集約
mcp__trinity__fan_out(
    agent_name="my-agent",
    tasks=["task1", "task2", "task3"]
)

MCP HTTP ツール呼び出しには Claude Code が 60 秒のタイムアウトを強制します。長時間タスクは async=true と parallel=true を組み合わせて execution_id を取得し、ポーリングで結果を確認します。

■運用

エージェントの起動・停止・状態確認

エージェントのライフサイクル操作は CLI・Web UI・MCP ツール・REST API のいずれかで実施します。

# CLI: 起動・停止 (agents サブグループ)
trinity agents start my-agent
trinity agents stop my-agent

# CLI: 状態一覧
trinity health fleet

# MCP ツール
mcp__trinity__start_agent(name="my-agent")
mcp__trinity__stop_agent(name="my-agent")
mcp__trinity__list_agents()

# REST API
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/agents
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/agents/my-agent/start
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/agents/my-agent/stop

ログ確認

Trinity は Vector でコンテナログを集約し、日付ローテーション付き JSON ファイルに保存します。

# docker compose 経由 (サービスログ)
docker compose logs -f backend
docker compose logs -f frontend

# エージェントコンテナ直接
docker logs agent-my-agent

# Vector 集約ログ (今日分)
TODAY=$(date +%Y-%m-%d)
docker exec trinity-vector sh -c "tail -100 /data/logs/platform-$TODAY.json" | jq .
docker exec trinity-vector sh -c "tail -100 /data/logs/agents-$TODAY.json" | jq .

# エラーのみ抽出
docker exec trinity-vector sh -c "cat /data/logs/platform-$TODAY.json | tail -100" | jq 'select(.level == "error")'

ログファイルのパス

ログエントリの構造

{
  "timestamp": "2026-01-23T12:00:00.000Z",
  "container_name": "trinity-backend",
  "message": "The log message",
  "level": "info",
  "is_agent": false,
  "is_platform": true,
  "service": "trinity-backend"
}

CLI からログを確認する場合は trinity logs my-agent を使います。

ライブ実行ストリーミング

実行中の処理をリアルタイムで確認します。

• Web UI: エージェント詳細ページ → Tasks タブ → 実行行をクリック → Execution Detail ページ（SSE で自動ストリーミング）
• MCP ツール: async=true + parallel=true で execution_id を取得し get_execution_result でポーリング

# 非同期実行 + ポーリングパターン
result=$(mcp__trinity__chat_with_agent \
  --agent_name worker \
  --message "長時間タスク" \
  --parallel true \
  --async true)
# → {"execution_id": "abc123"}

mcp__trinity__get_execution_result --agent_name worker --execution_id abc123
# （任意で --include_log true。引数は実装 src/mcp-server/src/tools/executions.ts 準拠）
# → {"status": "running" | "success" | "failed", "response": "..."}

実行の終了（SIGINT / SIGKILL）

# Web UI: 実行詳細ページの "Stop" ボタン
# API
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/agents/my-agent/executions/{id}/terminate

システムは SIGINT を先に送り、プロセスが終了しなければ SIGKILL を送ります。キューのスロットは自動で解放されます。

Continue as Chat（実行の会話継続）

失敗または完了した実行を、フルコンテキストを保持したままインタラクティブな会話として再開します。

• Web UI: Execution Detail ページ → "Continue as Chat" ボタン

観測性

Graph View / Timeline View

Web UI トップページ（http://localhost）から確認します。

ホストテレメトリ

ダッシュボードヘッダーでホスト全体の CPU / メモリ / ディスク使用量をリアルタイム表示します。

# API
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/telemetry/host

フリートヘルスモニタリング（多層チェック）

エージェントはハートビートを定期送信します。連続して欠落するとオペレーターアラートが発火します。

# MCP ツール
mcp__trinity__get_fleet_health()
mcp__trinity__get_agent_health(name="my-agent")
mcp__trinity__trigger_health_check(name="my-agent")

# REST API
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/monitoring/health

OpenTelemetry メトリクス・トレーシング

エージェントは Claude Code の OTel サポートを経由してメトリクスをエクスポートします。

.env で有効化:

OTEL_ENABLED=1
OTEL_COLLECTOR_ENDPOINT=http://trinity-otel-collector:4317

エクスポートされる主なメトリクス:

Grafana・Datadog へのエクスポートは config/otel-collector.yaml で設定します。

エージェントダッシュボード

各エージェントの dashboard.yaml で 11 種類のウィジェットと履歴トラッキング・スパークラインを定義します。

/trinity:create-dashboard

スケジューリング運用

Trinity はスケジューラーサービス（APScheduler + Redis 分散ロック）で cron 実行を管理します。

スケジュール操作

MCP ツールの引数名は実装 src/mcp-server/src/tools/schedules.ts 準拠（agent_name / schedule_id。toggle_agent_schedule は enabled 必須）。

自律モード（Autonomy Mode）

エージェントの全スケジュールを一括で有効 / 無効にするマスタートグルです。無効の場合、個別スケジュールの設定にかかわらず実行されません。

Misfire ハンドリング

スケジューラー再起動時、ミスしたジョブを misfire_grace_time（デフォルト 3600 秒、env MISFIRE_GRACE_TIME で変更可）の猶予内でキャッチアップします。スケジュール定義は schedule_reload_interval（デフォルト 60 秒）ごとにリロードされます。

Pre-Check Hook

各 cron ティックの前に実行するゲートスクリプト（~/.trinity/pre-check）で、作業が不要な場合は Claude 呼び出しをスキップしてコストをゼロにします。

リトライとタイムアウト

永続的非同期バックログ

SQLite バックド FIFO キューにより、並列キャパシティを超えたタスクを再起動後も保持します。

アップグレード

# 1. データベースバックアップ (必須)
docker run --rm -v trinity_trinity-data:/data -v ~/backups:/backup \
  alpine cp /data/trinity.db /backup/trinity-$(date +%Y%m%d-%H%M%S).db

# 2. コード取得
git pull origin main

# 3. プラットフォームサービスのみリビルド
docker compose build --no-cache backend frontend mcp-server scheduler

# 4. 再起動 (down ではなく restart を使う)
docker compose restart backend frontend mcp-server scheduler

# 5. 動作確認 (6 プローブ)
curl -s http://localhost:8000/health      # backend
docker exec trinity-scheduler curl -s http://localhost:8001/health  # scheduler (8001 は host 非公開・内部 health check のみ)
curl -s -o /dev/null -w '%{http_code}' http://localhost  # frontend
docker exec trinity-redis redis-cli ping  # redis
curl -s http://localhost:8080/health      # mcp-server
docker exec trinity-vector wget -q -O - http://localhost:8686/health  # vector

docker compose restart を使う理由: down は trinity-agent-network を削除し、実行中のエージェントコンテナがネットワーク孤立するためです。

ベースイメージ（docker/base-image/Dockerfile）が変更された場合のみ追加で実行します。

./scripts/deploy/build-base-image.sh

既存エージェントコンテナは次回再作成時に新しいベースイメージを使用します。自動ロールフォワードはありません。

ロールバック

git checkout <previous-sha>
docker compose build --no-cache backend frontend mcp-server scheduler
docker compose restart backend frontend mcp-server scheduler

データも戻す場合は、バックアップした DB ファイルを trinity.db に上書きコピーします。

本番デプロイ

本番環境では docker-compose.prod.yml または docker-compose.prod.enterprise.yml を使用します。

docker compose -f docker-compose.prod.yml build --no-cache backend frontend mcp-server scheduler
docker compose -f docker-compose.prod.yml restart backend frontend mcp-server scheduler

エフェメラル SSH アクセス

エージェントコンテナへの時間制限付き SSH アクセスを生成します。

# MCP ツール
mcp__trinity__get_agent_ssh_access(name="my-agent")

# Web UI: エージェント詳細ページ → Terminal タブ

ファイルマネージャー

Web UI のエージェント詳細ページ → Files タブで、エージェントワークスペースのファイルを閲覧・プレビュー・ダウンロードできます。

■ベストプラクティス

セキュリティ・ガバナンス

クレデンシャル暗号化

エージェントのクレデンシャルは .credentials.enc に暗号化されて Git 管理されます。プレーンテキストで値をコミットしてはいけません。

実行時のシークレットは Redis に保持されます。コードに直接記述しません。

Claude Max / Pro サブスクリプションの共有は Subscription Management 機能で集中管理します（macOS は Keychain から取得）。

CREDS=$(security find-generic-password -s "Claude Code-credentials" -a "$(whoami)" -w)
curl -X POST "http://localhost:8000/api/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"my-max\", \"credentials_json\": $(echo "$CREDS" | jq -Rs .), \"subscription_type\": \"max\"}"

監査ログ（AUDIT-SEC-001）

• 追記専用（append-only）: SQLite trigger によりデータベースレベルで全 UPDATE を禁止（audit_log_no_update）。DELETE は trigger audit_log_no_delete が WHEN OLD.timestamp > datetime('now','-365 days') 条件で保持期間内のみ禁止し、保持期間（365 日）を過ぎたエントリは下記プルーニングで削除できる
• 保存期間: デフォルト 365 日（毎日 04:15 UTC にプルーニング。時刻は env AUDIT_RETENTION_HOUR で変更可）
• 対象: エージェントライフサイクル / 認証 / 認可 / 設定変更 / クレデンシャル操作 / MCP ツール呼び出し / Git 操作

Web UI では Enterprise → Audit Log（管理者のみ）から確認します。

# API (管理者のみ)
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://localhost:8000/api/audit-log?hours=24&event_type=agent_lifecycle"

エクスポートは CSV または JSON 形式に対応します。

RBAC（4 階層）

ロールの大小関係は user < operator < creator < admin です。初回ログイン時のロールはホワイトリストで決定します（Settings → Email Whitelist）。

アクセス制御（require_email / open_access）

エージェントごとに require_email または open_access ポリシーを設定します。verify 済みメールアドレスの allow-list が Web / Slack / Telegram チャネルを横断して適用されます。

# 公開アクセスの制限設定例
curl -X PUT "http://localhost:8000/api/agents/my-agent/settings/access" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"require_email": true}'

ガードレール（GUARD-001）

インフラレベルの安全制御です。エージェントから迂回できません。

ブロックされるコマンドの例:

保護されるファイルパスの例:

• .env
• .mcp.json
• .credentials.enc
• クラウドプロバイダー認証情報
• プラットフォームガードレールファイル

ターン制限:

エージェントの Settings タブまたは API で max_turns を変更できます。

Read-Only モード / Full-Capabilities モード

• Read-Only モード: ソースコードの変更を禁止しつつ、指定ディレクトリへの出力は許可します。
• Full-Capabilities モード: apt-get / sudo などの高い権限が必要なエージェント向けに任意で有効化します。

本番セキュリティ推奨設定

• openssl rand -hex 32 で強力な SECRET_KEY を生成する
• Redis を外部に公開せず内部ネットワークに留める
• HTTPS + リバースプロキシを構成する
• Docker イメージと依存関係を定期的に更新する

セキュリティ報告先

脆弱性の報告は公開 Issue ではなく security@ability.ai に連絡します。

ペンテスト実績: UnderDefense による独立した Web アプリペネトレーションテスト（2026 年 4 月、Grade A — Excellent）。

コスト最適化

Gemini CLI ランタイムによる削減

Gemini CLI ランタイムを選択するとコストを大幅に削減できます。

推奨パターン: マルチランタイム構成

agents:
  orchestrator:
    runtime: claude-code   # 複雑な推論
    model: sonnet
    resources: {memory: "4g"}

  worker-1:
    runtime: gemini-cli    # データ処理 (無料枠)
    model: gemini-2.5-pro
    resources: {memory: "2g"}

複雑な推論はオーケストレーター（Claude）に集約し、定型処理は Gemini ワーカーに振ることでコストを抑えます。

モデル選択

スケジュールやタスクごとに Opus / Sonnet / Haiku を切り替えられます。複雑でないタスクには Haiku を使うことでコストを削減します。

pre-check フックによるゼロコストスキップ

作業がない場合は pre-check フックで Claude 呼び出しをスキップし、トークンコストをゼロにします（スケジューリング運用の節を参照）。

データ常駐と環境管理

• データ常駐: EU + US に対応。BYOC（Bring Your Own Cloud）も利用可能。カスタマーデータでのトレーニングなし。
• マルチ環境: Trinity CLI のプロファイル機能で複数インスタンスを管理します。

■トラブルシューティング

頻出問題と対処

調査コマンド集

# バックエンドログ確認
docker compose logs backend --tail=100

# 環境変数確認
docker compose exec backend env | grep -E "(BACKEND|GOOGLE|ANTHROPIC)"

# Vector ヘルスチェック
curl http://localhost:8686/health

# Docker ソケットアクセス確認 (Vector)
docker exec trinity-vector ls -la /var/run/docker.sock

■まとめ

Trinity は、Claude Code や Gemini CLI で書いたエージェントを Docker コンテナとして隔離実行し、スケジューリング・観測性・監査証跡・マルチエージェント連携を自社インフラ上で付与する自己ホスト型のオーケストレーション基盤です。本記事では C4 モデルによる構造、SQLite を中心としたデータモデル、構築・利用・運用の手順までを、README や src/backend/db/schema.py 等の実装ソースに基づいて整理しました。「エージェントを書く」フェーズと「本番で動かす」フェーズを分離したいときの設計の参考になれば幸いです。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

■参考リンク

概要 / 公式

• Trinity GitHub README（Abilityai/trinity）
• Trinity 公式サイト（Ability.ai）
• Trinity ドキュメントポータル（docs.ability.ai）
• Trinity CLAUDE.md（開発者向け）

構造 / アーキテクチャ

• architecture（archive memory, 2026-06-11）
• README Architecture / Project Structure 節

データ（実装ソース）

• src/backend/db/schema.py
• src/backend/db/migrations.py
• src/backend/db/audit.py
• src/backend/db/notifications.py

構築方法 / 利用方法

• CLI ドキュメント（docs/CLI.md）
• Multi-Agent System Guide
• Trinity Compatible Agent Guide
• install.sh
• abilities プラグインマーケットプレイス

運用 / トラブルシューティング

• Known Issues
• Querying Logs
• Versioning and Upgrades
• Deployment Guide
• Gemini Support Guide
• Timezone Handling

セキュリティ

• SECURITY.md
• Subscription Credentials