CodeAct を使用すると、エージェントはコードを記述し、 execute_code ツールを使用してタスクを実行することでタスクを解決できます。 CodeAct では、モデルに一度に 1 つのツール呼び出しを出力するように求める代わりに、単一の実行ステップ内で制御フロー、データ変換、およびツール オーケストレーションを組み合わせるサンドボックス化された場所が提供されます。
Agent Framework では、CodeAct は、単一の組み込みコア型ではなく、バックエンド固有のパッケージを介して公開されます。 コネクタは、 execute_code ツールを追加し、ランタイム ガイダンスを挿入し、必要に応じてサンドボックス内から呼び出し可能なプロバイダー所有のツールを公開できます。
CodeAct の理由
最新の AI エージェントは、多くの場合、モデルの品質ではなく、オーケストレーションのオーバーヘッドによってボトルネックになっています。 エージェントが多数の小さなツール呼び出しを連結する場合、通常、各ステップには別のモデル ターンが必要であり、待機時間とトークン使用量の両方が増加します。
CodeAct は、そのモデル -> ツール -> モデル ループを折りたたみます。 Agent Framework では、一度に 1 つのツールを選択するようにモデルに依頼するのではなく、1 つの execute_code ツールを公開し、モデルが完全なプランを短いプログラムとして表現できるようにすることができます。 ツールは同じままであり、モデルは同じままであり、主な変更は、複数のツール呼び出しターンに分散されるのではなく、サンドボックス内でプランが 1 回実行されることです。
ツール負荷の高いワークロードの場合、この変更により、プランを 1 つのコード ブロックでコンパクトで監査可能な状態に保ちながら、エンド ツー エンドの待機時間とトークンの使用を大幅に削減できます。 並列配線の比較については、 Hyperlight CodeAct の統合 を参照してください。
CodeAct が適切な場合
タスクで次の利点がある場合は、CodeAct を使用します。
- 複数のツール呼び出しとループ、分岐、フィルター処理、または集計の組み合わせ
- 最終的な回答を返す前にツールの結果を変換する
- 実行の一部として、より大きな構造化された出力または成果物を生成する
- 制御された実行環境内でのみ一部のツールを使用できるようにする
- 多数の小さな連結可能なルックアップや軽量計算を1回の実行ステップで集約する
次の状況では、直接ツール呼び出しを使用し続けてください。
- タスクに必要なツール呼び出しは 1 つまたは 2 つだけなので、削除するオーケストレーションのオーバーヘッドはほとんどありません
- 各呼び出しには、モデルとユーザーに対して個別に表示される必要がある副作用があります
-
execute_code実行全体に関する 1 つの承認決定ではなく、呼び出しごとの承認プロンプトが必要です
CodeAct がエージェント フレームワークにどのように適合するか
CodeAct コネクタは、通常、実行に対して次の 4 つの処理を行います。
-
execute_codeツールをモデル向けツール サーフェスに追加します。 - 構成されたサンドボックス ランタイムの手順を提供します。
- 必要に応じて、
call_tool(...)を介してプロバイダー所有のツールを公開します。 - ファイルシステム アクセスや送信ネットワーク許可リストなどの機能制限を適用します。
コネクタはランタイム構成を所有しているため、正確なセットアップの詳細は、選択したバックエンドによって異なります。
現在の制限
Warning
FIDES と現在の CodeAct プロバイダーの組み合わせはサポートされていません。 FIDES は現在Python専用であり、.NET CodeAct プロバイダーでは使用できません。
生成されたコード内のプロバイダーマネージド ホスト ツール呼び出しは、エージェントの関数ごとのミドルウェア パイプラインを通過しません。 直接エージェント ツールまたは外部 execute_code 呼び出しのチェックでは、入れ子になった呼び出しまたはコード内部の中間値に対する FIDES の適用は確立されません。 また、ファイルやネットワークの機能にも対応していません。
ホストツールは、独自の認証と送信先制御を確実に実施する必要があります。 FIDES に依存するツールは、CodeAct で管理されるツールではなく、直接エージェント ツールとして保持するか、これらの保証を必要とするワークフローでは CodeAct を無効のままにします。 この互換性境界は現在の統合の制限であり、CodeAct パターン固有の制限ではありません。 FIDES を使用したエージェントのセキュリティを参照してください。
CodeAct はツールの負荷の高いワークフローに適していますが、次の制約に注意してください。
- Hyperlight CodeAct では、Pythonと.NETがサポートされます。 Monty はPython専用です。ローカル CodeAct は.NET専用です。
- 現在、承認は
execute_code呼び出し全体に適用されます。 個々の操作を 1 つずつ承認する必要がある場合は、call_tool(...)に依存するのではなく、これらの操作を直接エージェント ツールとして保持します。 -
call_tool(...)経由で到達したツールは、引き続きホスト プロセスで実行されます。 サンドボックス アクセスを不必要に広げる代わりに、機密性の高い I/O に対して、レビュー対象の狭いホスト ツールを使用します。 - CodeAct は、オーケストレーションのオーバーヘッドが大きな場合に最適に機能します。 1 つまたは 2 つのツール呼び出しのみを使用する小規模なタスクの場合、追加された抽象化は価値がない可能性があります。
- ツール名、パラメーター メタデータ、および戻り値の図形は、モデルが一度に 1 つの直接ツール呼び出しから選択するのではなく、そのコントラクトに対してコードを記述するため、ここでさらに重要です。
概要
.NETの場合、Hyperlight CodeAct は Microsoft.Agents.AI.Hyperlight パッケージとして提供されます。
Local CodeAct は、生成された Python コードをサブプロセスで実行し、外部による隔離に依存しています。
Hyperlight パッケージには次のものが用意されています。
-
HyperlightCodeActProvider— すべての実行でexecute_codeと CodeAct ガイダンスを挿入するAIContextProvider -
HyperlightExecuteCodeFunction— サンドボックス構成が固定されている場合の静的/手動配線用のスタンドアロンAIFunction - を介してサンドボックス内で引き続き使用できるプロバイダー管理ツール
call_tool(...) - 承認向けの
CodeActApprovalModeおよびApprovalRequiredAIFunctionの統合 - サンドボックス ランタイムのオプションのファイルシステム (
FileMounts、HostInputDirectory) と送信ネットワーク (AllowedDomains) の構成
Important
.NET パッケージはプレビュー段階であり、まだ nuget.org で公開されていないHyperlight.HyperlightSandbox.Api NuGet に依存します。 現在のインストールに関する注意事項とプラットフォームの要件については、 Hyperlight CodeAct を参照してください。
インストール、例、ランタイム固有のガイダンスについては、 Hyperlight CodeAct を参照してください。
概要
Pythonの場合は、分離サンドボックスには Hyperlight CodeAct を使用し、クロスプラットフォームの制限付きインタープリターには Monty を使用します。
Hyperlight パッケージには次のものが用意されています。
-
HyperlightCodeActProviderコンテキスト プロバイダー ベースの実行の場合 -
HyperlightExecuteCodeToolexecute_codeを直接配線する場合 - を介してサンドボックス内で引き続き使用できるプロバイダー管理ツール
call_tool(...) - サンドボックス ランタイムのオプションのファイルシステムと送信ネットワーク構成
インストール、例、とprint(...)を使用する場合などのランタイム固有のガイダンス、および現在の Hyperlight 固有の制限事項については、/output/ を参照してください。
Note
この機能の Go サポートは近日公開予定です。 最新の状態については、 Agent Framework Go リポジトリ を参照してください。