--- title: "アーキテクチャ" description: "control plane、Agent Computer Worker、Actor Runtime、Brain、Background Agent Job が Ankole Agent Harness をどう構成するかを説明します。" url: "https://ankole.agentbull.com/ja-JP/docs/architecture/" lang: "ja-JP" --- > AI Agent 向けドキュメント索引: https://ankole.agentbull.com/ja-JP/llms.txt # アーキテクチャ Ankole は、Company Brain を備えた企業向け Agent Harness です。企業が管理する基盤で動作し、意思決定に必要なコンテキスト、権限、永続的な実行、フィードバックをモデルに提供します。 Agent は数時間にわたって作業し、共有の Company Brain を使い、ブラウザー、ターミナル、ファイル、外部システムで仕事を実行し、人が確認して後の結果で検証できる判断を提示します。 Harness は各行動主体を識別し、アクセス規則を適用し、長時間の仕事を復旧し、コンテキストを最新に保ち、修正を次の意思決定に引き継ぎます。 ## システム全体図 **Ankole システムアーキテクチャ** 企業チャット、外部イベント、アイデンティティプロバイダー、Console、AI Provider がコントロールプレーンに接続します。コントロールプレーンは RuntimeFabric を通じて 1 台以上の Agent Computer Worker をスケジュールし、永続状態を PostgreSQL と Agent Home に保存します。 - 企業と外部システム - チャットチャネルと外部イベント — メッセージ · Webhook · 計画タスク - Console と API — オペレーター · 企業アプリ - アイデンティティプロバイダー — SSO · ディレクトリ · 組織 - AI Provider — モデル · ベクトル · 画像 · Web - コントロールプレーン · 1 つの論理管理境界 - [SignalsGateway](https://ankole.agentbull.com/ja-JP/docs/signals-gateway/index.md) — シグナルルーティング · メッセージ送受信 - [主体と AuthZ](https://ankole.agentbull.com/ja-JP/docs/principal-authz/index.md) — アイデンティティ · 権限 · 設定 · プラグイン - [AIGateway](https://ankole.agentbull.com/ja-JP/docs/ai-gateway/index.md) — モデル選択 · セッション · 認証情報 - [Actor Runtime](https://ankole.agentbull.com/ja-JP/docs/actor-runtime/index.md) — 長時間セッション · 起床 · 復旧 - [Brain](https://ankole.agentbull.com/ja-JP/docs/brain/index.md) — ワールドモデル · 想起 · Dreaming - [バックグラウンド Agent タスク](https://ankole.agentbull.com/ja-JP/docs/background-jobs/index.md) — ノンブロッキング · 再開可能 · 通信可能 - RuntimeFabric · リアルタイム制御、事実は保存しない - 実行層 · 1 台以上の Worker - [Agent Computer Worker プール · 1…N](https://ankole.agentbull.com/ja-JP/docs/agent-computer-worker/index.md) — メイン Agent · バックグラウンドタスク · Automation Job · ツール · Skills · サンドボックス - 永続化境界 - PostgreSQL — アイデンティティ · セッション · メモリ · タスク · 監査 - Agent Home — ファイル · ワークスペース · 納品物 コントロールプレーンは状態を保存し、作業の進め方を決定します。Worker は実際の計算環境を提供します。両者を分離することで、Agent の作業は特定のプロセスやマシンに依存しなくなります。 1 つのプライベートな deployment instance は、1 つの論理 control plane と 1 台以上の Agent Computer Worker を持ちます。control plane は Identity、state、schedule を管理します。Worker は Agent が実際に働く compute 環境を提供します。 外部の chat、webhook、schedule は SignalsGateway から入ります。Identity Provider が人と組織ディレクトリを供給します。AIGateway は model、embedding、rerank、画像、web 能力に対する 1 つの境界を提供します。 ## Control plane と Agent Computer Worker ### control plane は state を保存し、決定を行います Elixir/OTP の control plane は、Console、Principal とアクセス、システム configuration、signal の routing、Actor session、Brain、Background Agent Job、AIGateway、Control Plane Plugin を担います。 これらの module はすべて同じ規則に従います。ユーザーに見える結果を変える state は、実行や外部への送信を駆動する前に PostgreSQL に書き込まれます。 process は再起動できますが、受け付け済みの message、Job state、memory、audit 記録は残らなければなりません。 OTP の supervision tree は、Agent、connection、Job それぞれに独立した failure domain を与えます。1 つの実行 branch がハングまたは crash しても、control plane は deployment instance 全体を失敗させることなく、その branch だけを復旧できます。 ### Worker は Agent の仕事用コンピュータです Agent Computer Worker は model loop、tool、Skill、browser、terminal、file 操作を実行し、automation job の script 実行も行います。Worker は自ら durable な domain state を作りません。control plane から仕事を受け取り、実行結果を control plane にコミットします。 1 台の Worker で複数の Agent を扱えますが、各 Agent は依然として独立した軽量 sandbox で実行されます。より強い分離が必要な Agent には、専用の Worker を割り当ててください。 同時実行性を高めたい場合や、セキュリティ要件の異なる仕事を分離したい場合は、Worker を追加します。 RuntimeFabric は ZeroMQ 経由で control plane と Worker を接続します。wakeup、steering、cancel、進捗、実行結果を運びます。 これは低遅延のライブ channel であり、database ではありません。connection が切れた後の復旧は、依然として PostgreSQL の state を使います。 ## 1 つの message が再開可能な仕事になるまで ### SignalsGateway は外部の世界を受け取ります chat adapter、webhook、schedule は、まず外部の event を共通の signal に変換します。signal routing rule が、reply を受け取る Agent、session、channel または thread を選択します。 group chat は、Agent に宛てた message だけを処理するか、宛てられていない message も記録するか、介入すべきタイミングを Agent に判断させることができます。利用できる mode は、chat platform と signal routing rule に依存します。 SignalsGateway は Agent を wake する前に、受信した message とその出所を保存します。また、adapter が reply を送信する前に、追跡可能な delivery state を作ります。 一時的な provider の障害によって、「Ankole が送信を決定した内容」と「provider が受け付けた内容」が混同されることはありません。 ### trigger は Agent を wake するか、script を実行できます Cron、Checkback、webhook endpoint が、1 つのシステムにおける 3 つの trigger です。各 trigger は既定で Agent の会話を wake しますが、代わりに automation job、つまり Agent が書く決定論的な script に bind することもできます。trigger event は変わりません。変わるのは consumer だけです。 script は機械的な検査を静かに完了し、実行のたびに検査可能な記録を残します。判断が必要なときは、`emitEvent` を通じて所有者の会話に event を送り返し、Agent が検証して行動します。したがって、model は polling loop で空転することがありません。[Automation Jobs](https://ankole.agentbull.com/ja-JP/docs/automation-jobs/index.md) を参照してください。 ### Actor Runtime は長時間の session を管理します 各 active session は、アドレス指定可能な Virtual Actor です。mailbox、lifecycle、recovery position を持ちます。新しい message や schedule で wake でき、実行中に追加の input、cancel、人による介入を受け取ることもできます。 Actor Runtime はこの長時間の work identity を所有します。各 turn に対して新しい activation と fence を生成します。Worker がコミットできるのは、現在自分が所有する turn だけです。古い Worker は、復旧や retry の後に新しい結果を上書きできません。 stream された content は進捗です。事実となるのは、control plane が確認して保存した message、tool の結果、state の遷移だけです。これにより「interface には作業中と表示されている」ことと「仕事が完了している」ことが区別されます。 ## Brain: 現在の状態を保つ世界モデル Brain はチャットの抜粋を詰め込んだベクトルデータベースではありません。変化し続ける世界の見取り図を維持します。新しい証拠は以前の Claim を補足、修正、または置換できます。証拠が矛盾する場合、Dreaming は人が確認できる記録を作り、関連する Claim を密かに書き換えません。 知識は、Agent との会話、対象となるグループ内で誰も Agent に宛てなかったメッセージ、登録済みのファイルまたは URL Source から得られます。 1 つのインスタンスに属するすべての Agent が、同じ知識空間を使います。保護された本文、Claim、Timeline イベントは、`world`、権限グループ、または 1 つの Principal の開示範囲を持ちます。Source と Channel は出所を記録しますが、学習した知識へのアクセス権を付与しません。 ターンの間、統合された想起が現在の仕事に必要な長期コンテキストを供給します。オフラインの Dreaming は新しい証拠を整理し、パターンを見つけ、以前の予測を採点し、確認が必要な矛盾を示します。 [Brain](https://ankole.agentbull.com/ja-JP/docs/brain/index.md) は「世界が今どのような状態か」を担います。[Skill Lessons](https://ankole.agentbull.com/ja-JP/docs/skill-lessons/index.md) は、繰り返し現れる作業証拠から Agent が学んだ手順上のガードレールを保存します。対応する Skill と共に提示されますが、Skill のソースは書き換えません。適用できなくなった Lesson は退役します。 この構造は、Agent が時間とともにチームの規則を学ぶというホームページ上の約束を実現します。蓄積は、より長い log を意味しません。次の Job がより良い知識とより良い方法から始まることを意味します。 ユーザーから見えるのはこの仕組みの長期記憶であり、保存、Dreaming、書き込み権限は Brain が担います。 ## Background Agent Job: メイン session をブロックしない長時間の仕事 メイン Agent は、調査、データ分析、file 作業、code 変更、Deep Research を Background Agent Job に委任できます。メイン session は利用可能なまま、ユーザーとの会話を続けられます。 control plane が Job lifecycle を保存し、Worker が Job を実行します。その Worker が停止しても、システムは Job を再ディスパッチし、durable な state から続行できます。process の終了で Job 全体が消えることはありません。 メイン Agent と Job は通信を続けられます。Job は input を求めたり、失敗や最終結果を返したり、要求されれば沈黙を保ったりできます。人を待つ間は実行 slot を解放し、回答が届いてから再開します。 Deep Research はこの architecture の高度な利用法です。Agent Plugin が workspace template を提供し、Skill が調査方法を提供し、Background Agent Job が durable な実行を提供します。 Agent Home は調査資料と成果物を保持します。 [Background Agent Jobs](https://ankole.agentbull.com/ja-JP/docs/background-jobs/index.md) と [Deep Research](https://ankole.agentbull.com/ja-JP/docs/deep-research-job/index.md) を参照してください。 ## AIGateway: AI 能力のための 1 つの境界 AIGateway は model の能力を Agent の実行から分離します。メイン Agent、Job、Brain、外部 API client は、LLM、embedding、rerank、画像、Web Search、Web Fetch Provider に対して同じ境界を使います。 Agent の model profile は Agent 実行用の model を選択します。Brain は AppConfigure のインスタンス全体に適用する 5 つの model 設定を使います。control plane は Provider の credential を暗号化して保存し、AIGateway は上流への request でそれらを使用します。 Agent と Worker が受け取るのは、使用できる model の選択と呼び出し結果だけです。 AIGateway は、履歴を保存しない呼び出しと、継続できる stateful な会話の両方をサポートします。request の変換、stream event、tool の結果、context の圧縮、使用量記録、最終結果のコミットを担います。 Worker は Provider ごとに個別の lifecycle を実装しません。 tool catalog が大きい場合、model は Tool Search で tool をオンデマンドに検索するか、制限された sandbox 内で多数の tool を呼び出して結果だけを返す 1 つの program を提出できます。ネイティブ対応の Provider は呼び出しをそのまま透過させ、AIGateway はそれ以外のすべての Provider に対して gateway 内で同じ能力を提供します。1 つの Provider は複数の credential を pool として保持することもでき、ChatGPT サブスクリプションのような account credential も含まれます。失敗の帰属、retry、使用量記録は credential 単位で残ります。 [AIGateway](https://ankole.agentbull.com/ja-JP/docs/ai-gateway/index.md) と [LLM Provider の追加](https://ankole.agentbull.com/ja-JP/docs/adding-a-provider/index.md) を参照してください。 ## エンタープライズ Identity、アクセス、拡張 Ankole は、人、Agent、システムサービスを Principal として表します。Identity Provider が Console の SSO を提供し、従業員、連絡先、組織ディレクトリを同期します。 chat channel が message を送受信します。これらの Provider は異なる platform を使えます。 AuthZ は実行時に、Principal、permission group、resource、action、condition から判定します。アクセスは prompt の中の 1 文ではなく、model が permission を持っていると宣言することもできません。 Control Plane Plugin が IdP、chat channel、その他の control plane 能力を接続します。Agent Plugin は tool と workspace template を追加します。 Skill は、ある種の仕事のやり方を説明し、メイン Agent または Background Agent Job に限定できます。 外部の MCP server は Skill を通じて入ります。Skill が接続を宣言し、Worker が実行ごとの configuration を生成して実行終了時に削除するため、model がすべての MCP tool の常駐リストに直面することはありません。 [Principal と permission group](https://ankole.agentbull.com/ja-JP/docs/principal-and-groups/index.md)、[signal routing rule](https://ankole.agentbull.com/ja-JP/docs/signal-bindings/index.md)、[Agent Library](https://ankole.agentbull.com/ja-JP/docs/skills/index.md)、[MCP server リファレンス](https://ankole.agentbull.com/ja-JP/docs/mcp/index.md) を参照してください。 ## Durability の境界 PostgreSQL は、identity、access、configuration、message、session、Job、memory、delivery state、audit 記録などの durable な domain 事実を保存します。システムが結果をコミットしたかどうかの判断には、これらの記録を使います。 Agent Home は workspace の file、tool の出力、最終成果物を保存します。シングルホストの deployment ではローカルまたは仮想ディスクを使用できます。複数の Worker を持つ Kubernetes deployment には、`ReadWriteMany` をサポートする NFS などの共有 volume が必要です。 RuntimeFabric、Worker の process state、stream preview は再構築できます。これらはライブ実行を支えますが、PostgreSQL や Agent Home の代わりにはなりません。 ## 3 つの deployment 形態 | 形態 | control plane と Worker | 永続化 | | --- | --- | --- | | **Docker Compose · 単一ホスト向け推奨** | 1 台の Linux、macOS、Windows ホストが control plane と 1 台の Worker を実行 | PostgreSQL と Agent Home はホスト上の persistent volume を使用 | | **Kubernetes · エンタープライズ deployment 向け推奨** | 1 つの control plane が 1 つ以上の Worker Pod に接続し、node またはセキュリティ要件に応じて schedule | PostgreSQL に加えて、共有の `ReadWriteMany` Agent Home storage | | **ソースインストール** | 開発環境が control plane と Worker を別々に実行 | 開発用に構成された PostgreSQL とローカル workspace | 論理的な境界はどの形態でも同じです。instance は control plane を 1 つ持ち、Worker を水平に追加できます。完全な手順は [クイックスタート](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#deployment) を参照してください。 ## 5 つの技術的判断 | 判断 | 解決する問題 | | --- | --- | | **Virtual Actor が AI の仕事を担う** | 各 session に address、mailbox、lifecycle、recovery position を与える | | **OTP supervision tree が failure domain を定義する** | instance 全体を失敗させずに、1 つの Agent または connection の branch を復旧する | | **ZeroMQ がライブ制御を運ぶ** | Agent の実行中に wakeup、steering、進捗、backpressure を運ぶ | | **Agent Computer Worker が実行を提供する** | model loop、tool、file、terminal、sandbox を workspace の近くに置く | | **PostgreSQL の ledger が事実を保存する** | message、Job、memory、決定、コミット済み操作を再開可能かつ audit 可能にする | これらの判断は 1 つの結果を支えます。Agent は数時間働き、実行中に新しい情報を受け取り、独立して失敗と復旧を行い、コミットされた各 action の痕跡を残せます。 より詳しい runtime の議論は、なぜ OTP はより良いマルチエージェント・オーケストレーションのランタイムなのか をお読みください。