AIチュートリアル

Unreal Agentで非同期かつ永続的なAIエージェントワークフローを構築

このチュートリアルでは、Unreal Agentの非同期優先アーキテクチャ、リポジトリ構成、主要コンポーネント、イベントフローについて説明します。入力が永続化されたセッション履歴になる仕組み、ツール呼び出しが非同期処理に変換される流れ、セットアップと利用の進め方、シリアライズとイベントループの不変条件に違反せずにハーネスを拡張する方法を学びます。

2026年9月22日約15分で読了

Unreal Agentとは？

Unreal Agentは、Unreal Labsが提供する非同期処理を第一に設計したエージェント・ハーネスです。入力の受け付け、セッション履歴の維持、モデルコンテキストの準備、LLMターンの調整、ツール呼び出しの変換、永続的な非同期処理のディスパッチに利用できる、組み合わせ可能な基盤を提供します。

このプロジェクトでは、同期的な調整と非同期的な実行を分離しています。ツール変換器はモデルが生成したリクエストを検証し、I/Oを実行せずにシリアライズ可能な操作記述を生成します。その後、操作マネージャーが調整役のイベントループ外で、確定した操作を実行します。

リポジトリ構成

リポジトリは、主に次の3つの領域で構成されています。

harness/：再利用可能なエージェント・ハーネス・ライブラリ。
cmd/：このライブラリを使用して構築された実行可能ファイル。
benchmarks/：プロジェクトを評価するためのベンチマーク実行環境。

このフレームワークを別のアプリケーションに統合する場合は、まずharness/を確認してください。具体的な実行可能ファイルのエントリーポイントはcmd/で確認し、実行時の動作を調査または測定する必要がある場合はbenchmarks/を使用します。

基本概念

入力とインボックス

入力とは、呼び出し元から提供されたグローバルに一意な識別子を持つイベントです。イベントが再配信された場合も、その識別子は変更してはいけません。

セッションのインボックスは、これらの識別子を使用して、外部入力、制御入力、クラッシュ入力をメモリ上で重複排除します。この冪等性はセッション単位で、かつ揮発性のものです。そのため、呼び出し元は引き続き一貫したIDを指定する必要があります。

{
  "id": "globally-unique-and-stable-id",
  "type": "external-input",
  "payload": "Example request"
}

この形式は概念的なものであり、Unreal Agentが文書化しているAPI型ではありません。重要なのは、安定したグローバル一意の入力IDです。

セッション

セッションは、追記専用で永続化される履歴です。セッションは再開およびフォークが可能で、元のシーケンスを書き換えずに既存の作業を継続したり、過去の履歴から分岐したりできます。

セッションストアは、正規の履歴と操作状態を管理します。また、ツール呼び出しの変換ステータスと、その変換によって生成された操作をアトミックに記録します。

LLMターン

LLMターンとは、1回の論理的なモデルリクエストを取り巻く、コーディネーターが管理する一連の処理です。コーディネーターは、受け付けた入力を永続化し、ターンを準備し、ツール変換器を解決し、生成された作業を記録して、確定した操作をディスパッチします。

ツール、変換器、操作

ツールは、スキーマと変換器を組み合わせたものです。モデルがツール呼び出しを生成すると、変換器がそれを検証し、1つ以上の操作に変換します。

ツール変換器は、コーディネーターのイベントループ上で同期的に実行されます。I/Oを実行したり、ループを中断したりしてはいけません。

変換結果はツール呼び出しステータスと呼ばれます。これには、検証エラーまたは送信された操作への参照のいずれかが含まれます。このステータスは、それらの操作の実行状態とは別のものです。

操作とは、非同期処理を記述する、シリアライズ可能でバージョン管理されたデータです。変換器は作業を記述し、操作マネージャーがそれを実行します。

主要コンポーネント

セッションインボックス：揮発性でセッション単位の入力冪等性を提供します。
コーディネーター：受け付けた入力を永続化し、LLMターンを管理し、ツール変換器を解決して、確定した操作をディスパッチします。
セッションストア：正規のセッション履歴と操作状態を永続化し、復旧とフォークをサポートし、ツール呼び出しステータスと操作をアトミックに記録します。
コンテキストビルダー：メモリ上でモデル入力を組み立て、省略、切り詰め、圧縮されたコンテンツを報告します。I/Oは実行せず、永続化への依存もありません。
LLMアダプター：準備された入力をモデルプロバイダーに送信し、正規化された完了済みレスポンスを返します。認証、キャンセル、プロバイダーエラーを管理します。
ツールレジストリ： Bash、ViewImage、skill-useツールの定義と変換器を管理し、ホストが選択したツール群を公開します。
ツール変換器：呼び出しを検証し、ステータスと操作を生成して、記録されたステータスと準備済みの操作出力をモデル向けに整形します。
操作マネージャー：永続的な操作を実行するアクターランタイムを提供します。ローカル実装は置き換え可能です。

インストールとセットアップ

READMEには、パッケージマネージャー、言語固有のインストールコマンド、安定した公開APIが記載されていません。そのため、セットアップは想定したパッケージコマンドではなく、リポジトリのローカルチェックアウトとビルドメタデータから始める必要があります。

Unreal Agentリポジトリをクローンまたはダウンロードします。
リポジトリのルートを開き、サポートされているツールチェーンを確認するために、ビルドファイルと依存関係ファイルを調べます。
リポジトリで設定されているツールを使用して、harness/のライブラリをビルドまたはインストールします。
ハーネスのコンポーネントを組み合わせている実行可能ファイルの例をcmd/で確認します。
コアプロジェクトのビルドが正常に完了してから、benchmarks/を使用します。

cd <unreal-agent-repository>

# ライブラリ、実行可能ファイル、ベンチマークのディレクトリを確認します。
ls harness
ls cmd
ls benchmarks

ホストアプリケーションでは、選択したプロバイダー用に設定されたLLMアダプターも必要になります。認証、キャンセルの動作、プロバイダー固有のエラー処理は、そのアダプターに実装します。

基本的な使用方法：1つのエージェントリクエストを追跡する

READMEには具体的なコンストラクター名やメソッド名が公開されていないため、使用方法を理解するには、文書化されているコンポーネントの処理フローを追うのが最も安全です。

セッションを作成または再開します。 セッションストアは、永続化された履歴と復旧機能を提供します。
安定したIDを付けて入力を送信します。 同じ論理イベントを再配信する場合は、同じIDを再利用します。
セッションの受信ボックスで重複排除します。 受信ボックスは、実装の動作に従い、アクティブなセッション内で重複した入力を拒否または無視します。
受け付けた入力を永続化します。 コーディネーターは、正規の追記専用セッション履歴に入力を記録します。
モデルコンテキストを構築します。 コンテキストビルダーは、メモリ上のモデル入力を組み立て、省略、切り詰め、または圧縮したコンテンツがあれば報告します。
LLMターンを実行します。 LLMアダプターは、準備した入力をプロバイダーに送信し、正規化された完了済みレスポンスを返します。
ツール呼び出しを解決します。 コーディネーターは、レジストリを通じて許可された各ツールを検索します。
同期的に変換します。 選択されたトランスレーターは呼び出しを検証し、検証エラーまたはシリアライズ可能な操作を生成します。
アトミックにコミットします。 セッションストアは、ツール呼び出しのステータスと操作をまとめて記録します。
非同期にディスパッチします。 操作マネージャーは、コミット済みの操作を実行し、その実行状態を変換ステータスとは別に追跡します。
モデル向けに結果を整形します。 トランスレーターは、記録された呼び出しステータスと準備済みの操作出力を組み合わせ、モデル向けの結果を生成します。

ツール呼び出しのライフサイクル例

安定したID付きの入力
  -> 受信ボックスでの重複排除
  -> 永続化されたセッションイベント
  -> コンテキスト構築
  -> 正規化されたLLMレスポンス
  -> ツールレジストリ検索
  -> 同期的な検証と変換
  -> ステータスと操作のアトミックなコミット
  -> 非同期の操作実行
  -> モデル向けの結果整形

検証に失敗した場合、トランスレーターは操作を生成せず、検証エラーを記録します。検証に成功した場合、ステータスは送信された操作を参照し、操作マネージャーは、それらの操作が保留中、実行中、完了、または実装上その他の状態で処理されたかを独立して追跡します。

ツールの選択

ツールレジストリは、Bash、ViewImage、スキル使用の定義とトランスレーターを管理します。ホストは、これらのツールのうちどれを公開するかを選択します。

特定のデプロイメントに必要な機能だけを公開してください。READMEでは認可やサンドボックス化のポリシーを定義していないため、これらの懸念事項はホスト環境と操作実行層で処理する必要があります。

ハーネスの拡張

Unreal Agentのコンポーネントは、組み合わせて使用できるように設計されています。インターフェースに基づくコンポーネントは、文書化された責務と不変条件を維持する限り、別の実装に置き換えられます。

ツールトランスレーターの実装

カスタムトランスレーターは、次の手順に従う必要があります。

ツールのスキーマに対して、モデルが生成した引数を検証します。
リクエストが無効な場合は、検証エラーを返します。
有効な場合は、シリアライズ可能でバージョン管理された操作記述を1つ以上作成します。
送信された操作を参照するステータスを返します。
記録されたステータスと準備済みの操作出力をモデル向けの結果に変換する整形ロジックを提供します。

変換は決定的かつ高速に保ってください。トランスレーター内でネットワーク要求の送信、ファイルへのアクセス、サブプロセスの待機、その他のI/Oを実行しないでください。

操作マネージャーの置き換え

ローカル操作マネージャーは交換可能です。文書化されている拡張の1つに、操作をシリアライズし、リモートのサンドボックスプロセス内で実行されている別のローカル操作マネージャーへ送信するプロキシマネージャーがあります。

この設計により、コーディネーターとトランスレーターは検証と永続的な意図に集中しながら、分離された環境で実行できます。

ストレージの実装

代替セッションストアは、シリアライズ可能性、バージョン管理、復旧動作、およびツール呼び出しステータスと生成された操作のアトミックな関係を維持する必要があります。

このプロジェクトは、セッションの後方互換性の維持を目指しています。セッションのバージョンがサポートされていない場合、データを黙って誤読するのではなく、明示的なエラーで再開に失敗しなければなりません。

高度なヒント

入力 ID は呼び出し元の境界で生成する。 ID を元のイベントと一緒に保存し、再試行や再配信でも同じ識別情報が維持されるようにします。
インボックスの重複排除と永続的な履歴を混同しない。 インボックスは揮発性でセッション単位ですが、セッションストアは正規イベントを永続化します。
トランスレーターは純粋かつ同期的に保つ。 リクエストを操作に変換し、処理自体を直接実行しないようにします。
すべての操作形式をバージョン管理する。 操作は作成元のプロセスより長く存続したり、プロセス間やサンドボックス境界を越えたりする可能性があります。
アトミックなコミットを維持する。 ツール呼び出しの成功ステータスだけを記録し、操作を記録しないと、クラッシュ後にセッションが不整合になる可能性があります。
変換と実行を独立して追跡する。 有効な呼び出しによって、まだ完了していないコミット済みの操作が生成される場合があります。
コンテキストビルダーのメタデータを使用する。 何が省略、切り詰め、圧縮されたかを監視し、モデルの動作を診断できるようにします。
プロバイダーに関する処理を集約する。 認証情報、キャンセル、プロバイダーのエラーは LLM アダプター内で処理します。
実験にはセッションをフォークする。 フォークを使えば、元のセッションの追記専用履歴を維持したまま、別の継続処理を試せます。
分離にはプロキシ操作マネージャーを使用する。 シリアライズされた操作を、同期的な変換処理を移動させることなく、リモートサンドボックス内のランタイムへ転送できます。

重要な不変条件

拡張機能では、次の保証を維持する必要があります。

セッションストアの項目はシリアライズ可能である。
ストレージ形式はバージョン管理されている。
サポートされていないセッションバージョンでは、明示的な再開エラーが発生する。
操作はシリアライズ可能で、バージョン管理されている。
コンテキストの構築では I/O を実行せず、永続化の依存関係を受け取らない。
ツールの変換では I/O を実行せず、コーディネーターのイベントループを一時停止しない。

まとめ

Unreal Agent は、永続セッション、重複排除された入力、調整された LLM ターン、検証済みのツール呼び出し、永続的な非同期処理を必要とするエージェント向けに、モジュール式の基盤を提供します。その中心的な設計原則は、同期的な変換と非同期的な実行を明確に分離することです。既存の実行可能ファイルから始め、文書化されたイベントフローに従い、コンポーネントを置き換えたり拡張したりする際は、シリアライズ、バージョン管理、アトミック性を維持してください。