0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Microsoft Agent Framework CodeAct入門 — ツール連鎖をコードで束ねる実行パターン

0
Last updated at Posted at 2026-06-28

CodeActのコンセプト：エージェントが1本のコードを書き、サンドボックス（micro-VM）で実行する

はじめに

AIエージェントを実装していると、モデルがツールを「1つ呼んで → 結果を受け取って → 次のツールを選んで…」と何往復もするうちに、レイテンシとトークン消費が膨らんでいくことに気づきます。Microsoftは Build 2026（2026年6月2〜3日）で、この課題に正面から答える CodeAct を Microsoft Agent Framework の新機能として発表しました。

CodeActは「ツールを1つずつ選ばせる」のではなく、モデルに短いプログラムを1本書かせ、サンドボックス内で一度だけ実行させる という実行パターンです。この記事では、公式ドキュメントをもとにCodeActの仕組みと、PythonでのHyperlightサンドボックス連携の使い方を解説します。

この記事で学べること

  • CodeActが従来のツール呼び出しと何が違うのか
  • なぜレイテンシとトークン消費を削減できるのか
  • agent-framework-hyperlight を使った実装手順
  • call_tool(...) とホストツール・承認の仕組み
  • 本番投入前に押さえるべき制約（alpha/preview）

対象読者

  • AIエージェント・マルチエージェントを実装するエンジニア
  • ツール呼び出しのレイテンシ／コストを下げたい方
  • Microsoft Agent Framework（旧 Semantic Kernel + AutoGen）に関心がある方

前提知識

  • Pythonの基本
  • LLMの「ツール呼び出し（function calling）」の概念

なお、Microsoft Agent Frameworkは 2026年4月2日に1.0がGA しており（公式ブログに "MAF reached 1.0 GA on April 2, 2026" と記載）、CodeActはそのうえに乗る追加機能です。

TL;DR

  • CodeAct は「ツールを1つずつ選ぶ」代わりに、モデルが書いた1本のプログラムをサンドボックスで一度だけ実行する実行パターン。
  • ツール群はそのまま、execute_code というツール1つだけをモデルに見せ、内部から call_tool(...) で呼び出す。
  • 公式が示す代表的なツール多用ワークロードのベンチマーク例では、レイテンシ約半減・トークン消費6割超削減。
  • Python実装は pip install agent-framework-hyperlight --pre、入口は HyperlightCodeActProvider。
  • 現状は alpha/preview。Hyperlightは KVM（Linux）/ WHP（Windows）のハードウェア仮想化が必要。

CodeActとは — 「ツールを1つずつ選ぶ」から「コードで束ねる」へ

従来のツール呼び出し（direct tool calling）では、エージェントは1ターンごとに「どのツールを使うか」を1つだけ選びます。データを読み、軽い計算をし、結果を組み立てる——たったこれだけのタスクでも、model → tool → model → tool … という往復の連鎖になりがちです。各ステップが新たなモデル呼び出しを必要とするため、レイテンシもトークン消費も積み上がっていきます。

CodeActはこのループを畳み込みます。公式ドキュメントの表現を借りると、次のとおりです。

Instead of choosing a tool, waiting, and choosing the next one, the model writes a single short Python program that calls your tools via call_tool(…), runs it once in a sandbox, and returns a consolidated result.
— Microsoft Agent Framework at BUILD 2026

つまりモデルには execute_code というツールを1つだけ見せ、モデルは 計画全体を短いプログラムとして表現 します。ツールもモデルも変わりません。変わるのは「計画が複数のツール呼び出しターンに散らばる」のではなく「サンドボックス内で一度だけ実行される」という点だけです。

従来のツール呼び出し（model⇄toolの往復ループ）とCodeAct（execute_codeで一括実行）の比較

なぜ速く・安くなるのか

現代のエージェントはモデルの賢さよりも オーケストレーションのオーバーヘッド で律速されることが多い、というのがCodeActの問題意識です。多数の小さなツール呼び出しを連鎖させると、各ステップが追加のモデルターンを要求し、レイテンシとトークンの両方を押し上げます。

CodeActはこの model → tool → model ループを1回の実行に集約します。公式の発表ブログ が示す代表的なツール多用ワークロードのベンチマーク例では、次の改善が報告されています。

指標 従来のツール呼び出し CodeAct 改善
実行時間 27.81秒 13.23秒 約52.4%短縮
トークン消費 6,890 2,489 約63.9%削減

この数値は公式が示す代表的なワークロードの例です。効果は「小さなツール呼び出しを多数連鎖させる」ようなオーケストレーション過多のケースで大きくなります。ツール呼び出しが1〜2回で済むタスクでは恩恵は小さい点に注意してください。

Hyperlightサンドボックス — micro-VMによる分離

モデルが生成したコードを実行する以上、分離（アイソレーション）が重要です。Agent FrameworkのCodeActは現状、Hyperlight というバックエンドで execute_code を実装しています。Hyperlightは、モデル生成コードを 呼び出しごとに新しい、ローカル分離された micro-VM で実行します。これにより、ツール呼び出し1回という細かい粒度でも強い分離をほぼコストなしで得られる、というのが設計の狙いです。

実行環境の要件は以下のとおりです（Hyperlight CodeAct より）。

  • ハードウェア仮想化が必要: Linuxは KVM、Windowsは Windows Hypervisor Platform（WHP）
  • 対応していないプラットフォーム・仮想化バックエンドではサンドボックス生成時に失敗する
  • 現行のPython連携はPythonゲストコードを実行する

HyperlightCodeActProvider は実行ごとにスナップショット／リストアを適用するため、毎回クリーンな状態からゲストが起動します。

実装：HyperlightCodeActProvider をPythonで使う

インストール

agent-framework-hyperlight はコア（agent-framework-core）とは別パッケージとして提供されます。サンドボックスランタイムが必要なときだけ依存に加える設計です。

pip install agent-framework-hyperlight --pre

基本的な使い方

推奨される入口は HyperlightCodeActProvider です。実行ごとにCodeActの指示と execute_code ツールを注入しつつ、プロバイダに登録したツールは「直接ツール」としてはモデルに見せず、サンドボックス内の call_tool(...) からのみ到達できるようにします。

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.hyperlight import HyperlightCodeActProvider
from azure.identity import AzureCliCredential


# サンドボックス内から call_tool("fetch_data", ...) で呼ばれるツール
def fetch_data(kind: str) -> list[dict]:
    """サンプルデータを取得する（実際はDB/API呼び出しを想定）"""
    if kind == "users":
        return [{"name": "alice", "admin": True}, {"name": "bob", "admin": False}]
    return []


def compute(a: float, b: float) -> float:
    """2つの数値を掛け合わせる"""
    return a * b


# 1. Hyperlightバックエンドのプロバイダを作り、サンドボックス用ツールを登録
codeact = HyperlightCodeActProvider(
    tools=[compute, fetch_data],
    approval_mode="never_require",
)

# 2. クライアントとエージェントを構築
agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    name="HyperlightCodeActProviderAgent",
    instructions="You are a helpful assistant.",
    context_providers=[codeact],
)

# 3. execute_code と call_tool(...) を使わせるリクエスト
query = (
    "Fetch all users, find admins, multiply 7*(3*2), and print the users, "
    "admins, and multiplication result. Use execute_code and call_tool(...) "
    "inside the sandbox."
)
result = await agent.run(query)
print(result.text)

ポイントは tools=[compute, fetch_data] で渡したツールが 直接ツールとしては見えず、モデルが書いたコードの中で call_tool("fetch_data", "users") のように呼び出される点です。モデルは「どのツールを選ぶか」ではなく「これらのツールをどう組み合わせるプログラムを書くか」を考えます。

出力の受け取り方

Hyperlightは 最後の式の値を自動的には返しません。execute_code からテキストを返したいときは、ゲストコードの末尾で print(...) を呼びます。大きな成果物を出力したいときは、ファイルシステムを有効にしたうえで /output/<filename> に書き出すと、ツール結果に添付されます。

call_tool とホストツール・承認の仕組み

ここが設計上もっとも重要なポイントです。call_tool(...) は ホスト側コールバックへの橋渡し であり、サンドボックス内でツールを再実装しているわけではありません。つまり、プロバイダに登録したツールは ホストプロセス側で実行 され、ホストプロセスが持つファイルシステム・ネットワーク・認証情報にアクセスできます。

登録先による違いは「どこで関数が動くか」ではなく「どう呼び出されるか」です。

登録先 モデルからの見え方 呼び出し方
HyperlightCodeActProvider(tools=...) 直接ツールとしては隠す コード内の call_tool("name", ...)
Agent(tools=...) 一級ツールとして提示 各呼び出しが個別に承認メタデータを尊重

承認（approval）は approval_mode で制御します。

  • approval_mode="never_require"（既定）: 承認は登録ツール側から伝播する。承認必須のツールが1つでも混ざっていれば execute_code 全体が承認を要求する。
  • approval_mode="always_require": execute_code の呼び出し前に常に承認を要求する。

設計の指針はシンプルです。

  • 安価・確定的で連鎖しても安全なツール はプロバイダに載せ、1回の execute_code で多数を合成させる。
  • 副作用のある・機微な操作 は直接ツールとして残し、approval_mode="always_require" で1回ずつ可視化・承認できるようにする。

承認は execute_code の呼び出し 全体 に対して適用され、コードブロック内の個々の call_tool(...) 単位ではかかりません。1操作ごとに承認したいものは、CodeActのサンドボックス経由ではなく直接ツールとして扱ってください。

ファイルとアウトバウンドアクセスの制御

Hyperlightは読み取り専用の /input ツリーと、生成物用の書き込み可能な /output 領域を公開できます。サンドボックス内のコードに対する制約は次の引数で設定します。

from agent_framework.hyperlight import HyperlightCodeActProvider

codeact = HyperlightCodeActProvider(
    tools=[compute],
    file_mounts=[
        "/host/data",                    # /input 配下にマウント
        ("/host/models", "/sandbox/models"),
    ],
    allowed_domains=[
        "api.github.com",                # 特定ドメインのみ外部アクセス許可
        ("internal.api.example.com", "GET"),  # メソッドも制限可能
    ],
)

注意点として、file_mounts と allowed_domains は サンドボックス内のコード を制約するもので、call_tool(...) の裏で動く ホストコールバックには効きません。機微なリソースへのアクセスが必要なときは、サンドボックスの権限を広げるより、狭く絞ったホストツール を用意するのが推奨です。

CodeActを使うべきとき・避けるべきとき

公式は適材適所を明確にしています。

CodeActが向くケース:

  • 複数のツール呼び出しをループ・分岐・フィルタ・集約と組み合わせる
  • ツール結果を最終回答の前に変換・加工する
  • 多数の小さな参照や軽量な計算を1回の実行にまとめる

直接ツール呼び出しのままが良いケース:

  • ツール呼び出しが1〜2回で済み、削減すべきオーケストレーションがほとんどない
  • 各呼び出しに副作用があり、個別にモデル・ユーザーへ可視化したい
  • 操作ごとに承認プロンプトを出したい

現時点の制約（alpha / preview）

本番投入前に押さえておきたい制約です（公式ドキュメント より）。

  1. パッケージは alpha（.NETの Microsoft.Agents.AI.Hyperlight は preview）。
  2. プラットフォーム対応はHyperlightバックエンドに従い、対応する Linux / Windows 環境のみ。仮想化非対応環境ではサンドボックス生成時に失敗する。
  3. インメモリのインタプリタ状態は execute_code 呼び出しをまたいで保持されない。データを次の呼び出しに引き継ぐなら、マウントしたファイルや /output 成果物を使う。
  4. 承認は execute_code 単位で、個々の call_tool(...) 単位ではない。
  5. モデルが「契約」に対してコードを書くため、ツール名・引数の説明・戻り値の形 がこれまで以上に重要になる。

まとめ

  • CodeActは「ツールを1つずつ選ぶ」から「1本のコードに束ねてサンドボックスで一度実行する」への実行パターンの転換。
  • ツールもモデルも変えずに、オーケストレーション過多のワークロードで レイテンシ・トークンを大きく削減 できる。
  • Pythonでは pip install agent-framework-hyperlight --pre → HyperlightCodeActProvider が入口。call_tool(...) でホストツールへ橋渡しする。
  • ホストツールはサンドボックス外で動くため、file_mounts / allowed_domains の制約範囲と承認粒度を正しく理解して設計することが重要。
  • まだ alpha/preview。ハードウェア仮想化要件と状態非永続の制約を踏まえて検証から始めるのが現実的です。

ツール呼び出しの往復がボトルネックになっているエージェントを運用しているなら、CodeActは試す価値のあるパターンです。

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?