CodeAct

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 つだけなので、削除するオーケストレーションのオーバーヘッドはほとんどありません
  • 各呼び出しには、モデルとユーザーに対して個別に表示される必要がある副作用があります
  • 実行全体に関する 1 つの承認決定ではなく、呼び出しごとの承認プロンプト execute_code 必要です

CodeAct がエージェント フレームワークにどのように適合するか

CodeAct コネクタは、通常、実行に対して次の 4 つの処理を行います。

  1. execute_code ツールをモデル向けツール サーフェスに追加します。
  2. 構成されたサンドボックス ランタイムの手順を提供します。
  3. 必要に応じて、 call_tool(...)を介してプロバイダー所有のツールを公開します。
  4. ファイルシステム アクセスや送信ネットワーク許可リストなどの機能制限を適用します。

コネクタはランタイム構成を所有しているため、正確なセットアップの詳細は、選択したバックエンドによって異なります。

現在の制限

CodeAct はツールの負荷の高いワークフローに適していますが、留意すべき現在の制約がいくつかあります。

  • 現在文書化されている Agent Framework コネクタは Hyperlight CodeAct であり、Pythonと.NET (プレビュー段階) の両方で使用できます。
  • 現在、承認は execute_code 呼び出し全体に適用されます。 個々の操作を 1 つずつ承認する必要がある場合は、 call_tool(...)に依存するのではなく、これらの操作を直接エージェント ツールとして保持します。
  • call_tool(...)経由で到達したツールは、引き続きホスト プロセスで実行されます。 サンドボックス アクセスを不必要に広げる代わりに、機密性の高い I/O に対して、レビュー対象の狭いホスト ツールを使用します。
  • CodeAct は、オーケストレーションのオーバーヘッドが大きな場合に最適に機能します。 1つまたは2つのツール呼び出しのみを使用する小さなタスクの場合、追加の抽象化があまり効果をもたらさないことがあります。
  • ツール名、パラメーター メタデータ、および戻り値の図形は、モデルが一度に 1 つの直接ツール呼び出しから選択するのではなく、そのコントラクトに対してコードを記述するため、ここでさらに重要です。

概要

.NETの場合、現在文書化されているコネクタは Hyperlight CodeAct であり、Microsoft.Agents.AI.Hyperlight パッケージとして出荷されています。

パッケージには次のものが用意されています。

  • HyperlightCodeActProvider — すべての実行で AIContextProvider と CodeAct ガイダンスを挿入する execute_code
  • HyperlightExecuteCodeFunction— サンドボックス構成が固定されている場合の静的/手動配線用のスタンドアロン AIFunction
  • を介してサンドボックス内で引き続き使用できるプロバイダー管理ツール call_tool(...)
  • 承認向けのCodeActApprovalModeおよびApprovalRequiredAIFunctionの統合
  • サンドボックス ランタイムのオプションのファイルシステム (FileMounts、 HostInputDirectory) と送信ネットワーク (AllowedDomains) の構成

Important

.NET パッケージはプレビュー段階であり、 NuGet に依存します。これは、nuget.org でまだ公開されていません。現在<インストールの注意事項とプラットフォーム要件については>Hyperlight CodeAct を参照してください。

インストール、例、ランタイム固有のガイダンスについては、 Hyperlight CodeAct を参照してください。

概要

Python の場合、現在文書化されているコネクタは Hyperlight CodeAct です。

Hyperlight パッケージには次のものが用意されています。

  • HyperlightCodeActProvider コンテキスト プロバイダー ベースの実行の場合
  • HyperlightExecuteCodeTool execute_codeを直接配線する場合
  • を介してサンドボックス内で引き続き使用できるプロバイダー管理ツール call_tool(...)
  • サンドボックス ランタイムのオプションのファイルシステムと送信ネットワーク構成

インストール、例、とprint(...)を使用する場合などのランタイム固有のガイダンス、および現在の Hyperlight 固有の制限事項については、/output/ を参照してください。

次のステップ

エージェントの安全性

関連するコンテンツ

  • Last updated on