アーキテクチャ
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/architecture/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Ankole は、Meta Ankole の Company Brain を中核に据えたオープンソースのデジタル本社およびエンタープライズ Agent Harness です。自社管理のインフラ上で稼働し、共同作業用の Pod ワークスペースとパーソナルアシスタント・専門 AI 同僚を統合して、継続的な企業業務に不可欠な組織コンテキスト、権限境界、永続実行、フィードバックループを提供します。
Harness 内で人と Agent は数時間にわたる業務を協働で進め、共有 Company Brain を参照しながら、ブラウザー、ターミナル、統合 Drive ファイル、Applet、接続済み業務システムを操作し、根拠を検証できる成果物を届けます。すべての段階で Ankole が行動主体(Principal)を識別し、実行時のアクセス制御を強制し、中断した処理を PostgreSQL から復旧し、修正内容を次の意思決定へ引き継ぎます。
システム全体図
ワークスペースと外部システム
コントロールプレーン · 1 つの論理管理境界
実行層 · Agent 専用 Worker と Function Runtime
永続化境界
1 つのプライベートデプロイインスタンスは、1 つの論理コントロールプレーン、ステートレスな Function Runtime(ankole-function-runtime)サービス、そして Agent ごとに 1 台割り当てられる Agent Computer Worker で構成されます。コントロールプレーンは ID・永続状態・統合 Connectors・スケジューリングを統括して Pod ワークスペースを運用し、Pod Applet バックエンド・公開済み Applet Action・ホスト MCP 呼び出し・決定論的 TypeScript プログラムのために Function Runtime の isolate を起動し、WorkerProviders を通じて各 Agent に専用の計算環境をプロビジョニングします。
ワークスペース全体で、Pod(階層型 Docs、物理シャード上の 2 層 Base テーブル、React + TypeScript Applet、統合 Drive、マルチプレイヤー Pod Chat)と外部チャネルアダプターが会話メッセージを記録します。Ankole.Signals がメッセージ、Connector トリガー、Webhook、定期イベントを受け付け、Agent 実行用の Ankole.Sessions または決定論的な Applet Action 用の Ankole.AutomationJobs へディスパッチします。統合認証と Identity Provider がパスワードレス Email OTP(SiteCredential)・エンタープライズ SSO・ディレクトリ同期を担い、AIGateway がモデル・embedding・rerank・画像・Web 機能の単一境界を提供します。
コントロールプレーン、Function Runtime、Agent Computer Worker
コントロールプレーンは状態を保存し、意思決定を確定する
Elixir/OTP 製のコントロールプレーンは、Pod(Docs、Base テーブルと物理シャード、Applet、統合 Drive、Pod Chat)、Meta Ankole(Brain、Skills、AGENTS.md / DESIGN.md 契約)、統合 Connectors(Ankole.Connectors)、Console、Principal と AuthZ、システム設定、シグナルルーティング、Sessions、Workflow、Automation Jobs、Background Agent Jobs、AIGateway、Control Plane Plugin を所有します。すべてのモジュールが「ユーザーに見える結果を変える状態変更は、実行や外部配信の前に必ず PostgreSQL へコミットする」という原則に従うため、プロセスがいつ再起動しても受付済みメッセージ、Job 状態、知識、監査証跡は失われません。
実行時には OTP の supervision tree が Agent・外部接続・Job を個別の障害ドメイン(failure domain)に分離し、1 つの実行ブランチがハングやクラッシュを起こしてもインスタンス全体を止めずにそのブランチだけを復旧します。さらに中核コードと主要ステートマシンには形式検証を適用し、リトライ・再起動・並行入力のもとでも状態遷移と境界の不変条件を維持します。
Worker は Agent 専用の仕事用コンピュータ
メインの Agent ループはコントロールプレーン内で動作し、環境ツールや Codex が必要になった時点で Agent Computer Worker がオンデマンド起動されます。Worker 内ではシェルツール、Skills、ヘッドレスブラウザー、ファイル操作、MCPorter ツール呼び出し、Git 認証ヘルパー、Codex Job を実行し、決定論的な自動化処理は公開済み Applet Action として Function Runtime 上で実行されます。
各 Agent は固有の Worker ID を持ち、同時に接続できる有効な Worker インスタンスは最大 1 台です。Agent 間で Worker・キャッシュディスク・認証情報を共有することはありません。Worker コンテナ(または Pod)内では信頼された supervisor が FUSE で /drive をマウントし、モデル主導の子プロセスを Linux ケーパビリティなし・sudo なしの uid 1000 で起動します(Kubernetes では Pod テンプレートの RuntimeClass で gVisor も併用できます)。選択した WorkerProvider(Docker、Kubernetes、Cloudflare、Vercel、AWS Lambda MicroVMs、Alibaba Function Compute)に応じて、コントロールプレーンは永続 Agent Home を /workspace に、再構築可能なキャッシュを /var/cache/ankole にマウントし、/drive 配下に Public・MyDrive・AgentDrive・ChatDrive と読み取り専用の Brain・Skills・AGENTS.md・DESIGN.md を FUSE 投影します。
RuntimeFabric は Worker ごとに 1 本の Phoenix Channel を張り、wakeup、steering、キャンセル、/drive キャッシュの部分無効化通知、進捗、実行結果を低遅延で運びます。RuntimeFabric はデータベースではなくライブ転送路であるため、切断後の復旧は常に PostgreSQL のコミット済み状態から再開します。
WorkerProviders がプラットフォームと構成を定義する
運用者は Console → Worker Providers でサイト単位の WorkerProviders を構成します。各プロバイダーはプラットフォーム種別、YAML 設定、暗号化されたプラットフォーム認証情報を保持します。複数の Agent が同じ WorkerProvider を共有してもコンピュータと永続 /workspace Home は Agent ごとに完全に分離され、異なる基盤やインスタンスサイズが必要な場合は別のプロバイダーを作成します。
Agent 作成時に WorkerProvider を明示選択するかサイト既定値を使うと、その紐付けは恒久的に固定されます。以降、コントロールプレーンは必要に応じて Worker を起動し、アイドル時に一時停止または解放し、設定更新時には /workspace を保ったまま古いインスタンスを置換して /var/cache/ankole を個別に再構築します。詳しくは WorkerProviders と Workers を参照してください。
各 Worker は環境ワークスペースと Codex ターンの同時実行枠を管理しますが、メイン会話ターン・Workflow・公開済み Applet Action は Worker の外で動くため Worker 枠を消費しません。
1 つのメッセージが再開可能な仕事になるまで
会話は参加者の発言を保存する
会話(Conversation)は人と Agent が共有するやり取りの場であり、Ankole.Conversations が DM・グループルーム・Agent 間委譲用の分離された agent_peer スレッドの参加者とメッセージを保持します。Pod ネイティブの発言は直接 PostgreSQL に書き込まれ、外部チャットの会話はチャネルアダプターが観測して記録します(外部会話の正本は外部プラットフォーム側です)。
会話の発言と Agent 内部の実行状態は明確に分離されます。発言は参加者に属し、モデル呼び出し・ツール結果・コンテキスト圧縮は AIGateway 上の Session モデルチェーンに属します。Session が会話をまたぐことはないため、ある会話の内部作業が別の会話へ漏れることはありません。
Signals がすべての刺激を受け付ける
Agent 宛てのメッセージ、スケジュール発火、Connector トリガーや Webhook の到着、check-back タイマー、バックグラウンドタスク完了が起きると、Ankole.Signals が発生元・イベント ID・宛先・帰属・認可情報を記録してから Session を起こすか Automation Job Run をキューに入れます。
Pod ネイティブ発言とその Signal は単一トランザクションでコミットされ、受付時に (target, source, id) で重複排除を行います。下流のアクションはそれぞれの冪等性キーと attempt fence で二重実行を防ぎます。
Signal は宛先 Session を直接指定できるほか、会話の参加関係や Signal Routing Rule から宛先を解決します。チャットホスト型アダプターは発言の観測と返信配送の両方を担い、イベントソース型アダプターは Signal の発行のみを行います。決定論的なスケジュール・Webhook・Connector イベントについては、Ankole.AutomationJobs が LLM 不要の公開済み Applet Action を Function Runtime 上で実行し、モデルの判断が必要な場合のみ Agent Session へ Signal を送ります(Automation Jobs を参照)。
Sessions が作業を実行・復旧する
Ankole.Sessions は待機キュー、Admission、Driver、Run、ツール、コールドウェイク時の会話ローテーション、障害復旧を管理します。各 Session は同時に 1 つの Run だけを実行し、開始のたびに Admission がテナント・Agent 状態・人間の作業権限・認可を検証します。トークンクォータは AIGateway がモデル呼び出しの直前に毎回確認します。
各 Agent は会話内で固有の Session を持ち、Agent のサブタイプに応じて権限モデルが分かれます。
- パーソナルアシスタント(
personal_assistant): 社内 Human メンバーと 1 対 1 で紐付き、Drive・Pod・グループなどの共同作業リソースではPrincipals.authority_uid/1を通じて所有者本人の権限を投影します(site_console:**およびtenant_console:**管理権限は除外)。監査証跡と Worker ストレージにはアシスタント自身の Principal ID を維持します。 - AI 同僚(
ai_colleague): Drive・Pod・Workflow・スケジュール・Background Agent Job にわたり、Agent 自身の Principal 権限で実行します。保護された知識オブジェクトの作成・更新など自身の書き込み権限を超える操作が必要な場合は、Pod 会話でpropose_action_cardを呼び出し、権限を持つ人間の承認を仰ぎます。知識参照では、Brain が依頼者と Agent の閲覧権限の積集合(strictグループルームでは参加者全員の積集合)を強制します。
共有ルームでの Agent の通常発言が他の Agent を自動起動することはないため、無限ループは起きません。専門 AI 同僚に作業を頼む場合は send_to_agent で明示的に委譲し、分離された agent_peer 会話を開いて内部ツール履歴を混ぜずに非同期で結果を受け取ります。cron スケジュールやバックグラウンドタスクも専用 Session で実行され、完了メッセージだけを対象会話へ投稿します。
AIGateway がモデルセッション状態を永続化・継続し、ランタイムが入力・指示・ツール・継続地点・コールドウェイク回転(sessions.wake_recycle)・圧縮を制御します。Driver の単調増加 epoch が古い書き込みを遮断し、障害復旧ではコミット済み地点から再開します(未完了のモデル呼び出しは再実行可能、記録済みツール結果は再利用、結果不明の Worker ツール呼び出しは interrupted として表面化します)。
Presentation と Delivery が可視結果をコミットする
ターン終了時に Presentation が可視返信を 1 回だけ確定します。サイレントターンは発言を作らず、Pod ネイティブ返信や対話型 Action Card は完了トランザクションでコミットされ、外部チャネル向け返信は永続 Delivery インテントを書き込んでアダプターに送信させます。
外部プラットフォームが送信成功を確認すると、配信完了マークと同一トランザクションで会話メッセージをコミットし、後から届く同じ外部メッセージ ID のエコーはその行へ統合されます。失敗・期限切れ・結果不明の Delivery はメッセージを作らず、結果不明の送信を盲目的に再送することもありません。
ライブのトークンストリーミングは途中経過のプレビューであり、最終メッセージがコミットされた時点で初めて会話履歴に入ります。詳しくは 会話、シグナル、実行セッション を参照してください。
Meta Ankole と Brain:進化し続ける世界モデル
Meta Ankole の Brain はチャット断片の単純なベクトル DB ではなく、独立した Brain ルート配下にインストール済みオントロジーカテゴリごとに整理される :knowledge ページと、構造化された Facts・Takes・タイムライン・型付き brain_links エッジからなる世界モデルを維持します。知識は Agent との会話、対象グループ発言、登録済み URL Source、そして事実抽出を有効化した Space ページ(metadata.extract_facts: true)から取り込まれます。新しい根拠が入れば既存の Claim を拡張・改訂・置換し、矛盾する根拠が見つかった場合はオフラインの Dreaming が勝手に上書きせず人間レビュー用に記録します。
同一テナントの Agent はテナント分離された単一の知識グラフを共有し、ライブの Pod ページ ACL アンカーグラフで権限制御されます。共有エンティティに紐づく非公開 Claim も元の出所の公開範囲を保ち、出所ページの権限を剥奪すれば派生 Claim やチャンクも次回読み取りから即座に除外されます。
実行ターン中は BM25 とベクトルのハイブリッド recall が長期文脈を供給し、オフラインでは Dreaming が根拠の統合、出所スコープ付き分析ページの作成、期限到来した Take の採点、矛盾検出を行います。Brain が組織知識を担う一方、Meta Ankole は共有 Skills と継承可能な AGENTS.md / DESIGN.md 契約を管理し、Skill Lessons が Background Agent Job の実行履歴から 7 日間リースの Agent 別注意事項を自動抽出して共有 SKILL.md を汚さずに適用します。
Background Agent Jobs:メインセッションを止めない長時間実行
フォアグラウンドの Agent は、長時間の調査、データ分析、ファイル生成、コード変更、Deep Research を Background Agent Job に委譲し、メイン Session を空けてユーザーとの対話を続けられます。
コントロールプレーンが Job のライフサイクルを PostgreSQL に永続化し、Worker インスタンスが置換されても /workspace 内の Job ワークスペースと Codex スレッドファイルから処理を再開します。実行中もメイン Agent と Job は双方向通信でき、Job が人間の判断を求める間は Worker の実行枠を解放し、回答が届き次第そのまま再開します。
Deep Research はこの基盤の上に構築されており、Agent Plugin が workspace-template を、Skills が調査方法論を、Background Agent Job が永続実行を提供します。作業用ワークスペースは /workspace に置かれ、外部から参照させる成果物は統合 Drive へ公開されます。詳しくは Background Agent Jobs と Deep Research を参照してください。
AIGateway:AI 能力のための単一境界
AIGateway は上流 AI プロバイダーと実行主体を切り離し、パーソナルアシスタント、AI 同僚、Background Agent Jobs、Brain、Pod Applet、外部 OIDC クライアントに対して LLM・embedding・rerank・画像生成・Web Search・Web Fetch の統一境界を提供します。
Ankole.AIGateway.ModelProfiles は 3 層のスパース継承(Site -> Pod -> Agent/System)とスロット間フォールバック(heavy -> primary、light -> primary)でモデルを解決します。登録済みの system Principal はフォアグラウンド Agent のトークンクォータを一切消費せずに内部処理を実行します。ankole_brain は Brain の抽出(light)・Dreaming と教訓レビュー(heavy、未設定時は primary)・URL Source 取得(web_fetch)・想起時の再ランキング(rerank)を担い、サイト設定 brain.embedding_model が共有ベクトルインデックスを司ります。Pod Applet のステートレスな ctx.ai 呼び出しは、選択された実行 Principal を使用します。Human は Pod/Site の言語モデル既定値を、Agent はその Agent の有効な言語モデルプロファイルを解決します。これらの呼び出しは対話型 Agent のトークンクォータを消費しません。運用者は Console → Model Profiles で Site・Pod・system Principal のプロファイルを管理し、Provider 認証情報はすべてコントロールプレーン内で暗号化保管されます。
AIGateway は単発のステートレス呼び出しと継続可能な WebSocket モデルセッションの両方を扱い、リクエスト変換、ストリーム正規化、ツール結果、コンテキスト圧縮、使用量記録、最終コミットを担います。ツール数が多い場合は Tool Search や Programmatic Tool Calling(PTC)を利用でき、AIGateway と Workflow はステートレスな ankole-function-runtime の isolate(POST /v1/program/run)で決定論的 TypeScript プログラムを実行します。ChatGPT サブスクリプションなどの OAuth プールを含む複数認証情報プールにも対応し、クールダウン・リトライ・使用量は個々の認証情報単位で管理されます。詳しくは AIGateway と LLM Provider の追加 を参照してください。
エンタープライズ ID、統合 Connectors、拡張機能
Ankole は人・Agent・内部サービス(system、ankole_brain)を監査付きテナント内リネームに対応した (tenant_id, uid) の Principal として統一表現します。パスワードレス認証は Pod と Console にまたがり、個人の SiteCredential Email OTP とテナントのエンタープライズ Identity Provider(OIDC/OAuth SSO とディレクトリ同期)でパスワードを保存せずに認証します。
Ankole.AuthZ は Elixir コントロールプレーンと Rust カーネルで、Principal(パーソナルアシスタントの共同作業リソース操作では Human 所有者)、権限グループ、Drive の 5 ビット ACL アンカー、アクション、CEL 条件を実行時に評価します。
コンパイル時に組み込まれるサイトスコープの Control Plane Plugin は、6 種類のサブシステムアダプター契約(Signals アダプター、Webhook ハンドラー、Identity Provider、AIGateway プロバイダー、WorkerProvider 種別、および connectors.connector 統合 Connectors)、監視対象 OTP プロセス、外側 HTTP plug、デュアルスコープ /api/v2 JSON:API ルート、ドメイントランザクションフック、AppConfigure 項目、型付き UI スロットを提供します。Agent Plugin はメンバー Skills・Codex Hooks・workspace-template をパッケージ化し、Ankole.Connectors はコントロールプレーン MCP ゲートウェイ(/api/internal/mcp/toolkits/:toolkit と /api/internal/mcp/skills/:skill/:server)を運用して、テナントアプリ認証情報(authConfigId)と個人 OAuth トークンを PostgreSQL に保護したまま Worker(MCPorter 経由)と Function Runtime Applet(ホストブリッジ経由)へ明示的な Toolkit 契約を公開します。詳しくは Principal と permission group、Control Plane Plugins、Agent Library、MCP の利用 を参照してください。
永続化の境界
PostgreSQL 18+ のコントロールプレーン DB は、ID、AuthZ 権限、設定、Connector 認証情報とトリガー、Pod ページツリーと XML 本文、Meta Ankole の Skills(skills、skill_files)と AGENTS.md / DESIGN.md 契約(agent_contracts)、メッセージ、Sessions、Automation Jobs、Background Agent Jobs、Brain の Claim とオントロジーリンク、配信状態、監査証跡を永続保持し、物理 Base シャード DB(BASE_DB_URLS) がテナントの Base テーブル行を保持します。ポイントインタイムリカバリ(PITR)では、すべての Base シャードの復旧目標時刻をコントロールプレーン DB 以上(>=)に揃えます。
オブジェクトストア(コントロールプレーンファイルストアの file_objects)は統合 Drive の不変ファイル実体、Pod・会話の添付ファイル、Skill 同梱ファイル、コンパイル済み Applet バンドルを保持し、永続 Agent Home(/workspace)は Session・Job の作業ディレクトリ、追加パッケージ、Codex スレッドを保持します。バックアップではコントロールプレーン PostgreSQL DB、全物理 Base シャード DB、オブジェクトストア、全 Agent Home、暗号化キーを必ず一括で保護してください。
RuntimeFabric 接続、ankole-function-runtime isolate、稼働中 Worker プロセス、/drive FUSE キャッシュ、ストリームプレビュー、/var/cache/ankole はステートレスまたは再構築可能ですが、/workspace Home はインスタンス置換後も維持される永続領域です(バックアップとリストア を参照)。
3 つのデプロイ形態
| 形態 | コントロールプレーン、Function Runtime、Worker | 永続化 |
|---|---|---|
| Docker Compose · 単一ホスト推奨 | 1 台の Linux / macOS / Windows ホストでコントロールプレーンと ankole-function-runtime を動かし、Docker ソケット経由で Agent ごとに Worker コンテナを作成 |
PostgreSQL 18+(および BASE_DB_URLS シャード)、オブジェクトストア、Agent ごとの専用 /workspace Home ボリューム |
| Kubernetes · エンタープライズ推奨 | Helm でコントロールプレーンと ankole-function-runtime を稼働させ、Kubernetes API 経由で Agent ごとに /drive 用 /dev/fuse を備えた Worker Pod を作成 |
PostgreSQL 18+ と物理 Base シャード DB、オブジェクトストア、永続 Home PVC または共有ストレージ(キャッシュは別ボリューム) |
| ソースインストール | bun run services:start で PostgreSQL 18 と ankole-function-runtime を起動し、bun dev でコントロールプレーンと watch モードの Docker Worker を起動 |
PostgreSQL 18、var/ankole-dev/files、専用 Docker 永続 Home ボリューム |
どの形態でも、1 つの論理コントロールプレーンが WorkerProviders を通じて Agent ごとに分離された Worker を用意します。構築手順は クイックスタート を参照してください。
5 つの技術的判断
| 判断 | 解決する課題 |
|---|---|
| Virtual Actor が AI の仕事を担う | 各 Session に固有アドレス、メールボックス、ライフサイクル、正確な復旧地点を与える |
| OTP supervision tree が障害ドメインを分離する | インスタンス全体を止めずに個別の Agent・Connector 接続・Job ブランチだけを復旧する |
| Phoenix Channel がライブ制御を運ぶ | 実行中の wakeup、steering、/drive キャッシュ無効化、進捗、バックプレッシャーを低遅延で伝える |
| Worker と Function Runtime で実行を分担する | 各 Agent に /drive FUSE と /workspace を備えた専用コンピュータを与え、Applet Action や PTC/Workflow はステートレス isolate で動かす |
| PostgreSQL 台帳が確定事実を保持する | Pod ページ、Connectors、メッセージ、Job、Brain Claim、コミット済み操作を再開・監査可能にする |
これら 5 つの選択により、パーソナルアシスタントと AI 同僚は Pod とチャットを横断して長時間稼働し、途中で新しい文脈を取り込み、障害から個別に復旧し、すべての確定アクションに監査可能な記録を残せます。
ランタイム設計の背景については、なぜ OTP はより良いマルチエージェント・オーケストレーションのランタイムなのかをお読みください。