Hyperlight CodeAct

概要

もうすぐです。

パッケージをインストールする

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight は agent-framework-coreとは別に提供されるため、サンドボックス ランタイムは必要なときにのみ実行されます。

HyperlightCodeActProvider を使用する

HyperlightCodeActProvider は、実行ごとに CodeAct を自動的に追加する場合に推奨されるエントリ ポイントです。 実行範囲に限定された CodeAct 命令と execute_code ツールを挿入し、プロバイダー所有のツールがエージェント ツールサーフェスから除外されます。

async def main() -> None:
    """Run the provider-owned Hyperlight CodeAct sample."""
    # 1. Create the Hyperlight-backed provider and register sandbox tools on it.
    codeact = HyperlightCodeActProvider(
        tools=[compute, fetch_data],
        approval_mode="never_require",
    )

    # 2. Create the client and the agent.
    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],
        middleware=[log_function_calls],
    )

    # 3. Run a request that should use execute_code plus provider-owned tools.
    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."
    )
    print(f"{_CYAN}{'=' * 60}")
    print("Hyperlight CodeAct provider sample")
    print(f"{'=' * 60}{_RESET}")
    print(f"{_CYAN}User: {query}{_RESET}")
    result = await agent.run(query)
    print(f"{_CYAN}Agent: {result.text}{_RESET}")

プロバイダーに登録されているツールは、 call_tool(...)を介してサンドボックス内で使用できますが、直接エージェント ツールとして公開されません。 また、プロバイダーは、ツール、ファイル マウント、および送信許可リスト エントリの CRUD スタイルの管理を、 add_tools(...)、 remove_tool(...)、 add_file_mounts(...)、 add_allowed_domains(...)などのメソッドを使用して公開します。

承認とホスト ツールのしくみ

Agent Framework ツールには、自動呼び出しが可能か、ユーザーの承認のために一時停止する必要があるかを制御する approval_mode が含まれています。

HyperlightCodeActProviderにツールを登録し、Agent(tools=...)に直接登録する主な違いは、Python 関数が最終的に実行される場所ではなく、ツールがどのように呼び出されるかです。

• HyperlightCodeActProvider(tools=...)に登録されたツールは、直接ツールとしてモデルに表示されません。 モデルは、call_tool("name", ...)内でexecute_codeを呼び出すコードを記述することによってそれらに到達します。
• Agent(tools=...)に登録されたツールは、最上位クラスのツールとしてモデルに表示され、各直接呼び出しでは、そのツール独自のapproval_modeが受け入れられます。

call_tool(...) は、ホスト コールバックへのブリッジ バックです。これは、ツールのサンドボックス内の再実装ではありません。 つまり、プロバイダー所有のツールは、ホスト プロセス自体がアクセスできるファイルシステム、ネットワーク、資格情報を使用して、ホスト プロセスで引き続き実行されます。

経験則として:

• 安価で確定的で安全なチェーンツールをプロバイダーに配置して、モデルが 1 回のターン内で多くの呼び出しを作成できるように execute_code します。
• 副作用や承認が必要な操作は、approval_mode="always_require" を使用してエージェント内の直接ツールとして利用し、各呼び出しを個別に表示して承認できるようにします。

ホスト ツールはサンドボックスの外部で実行されるため、file_mountsallowed_domains、call_tool(...)の背後にあるホスト コールバックではなく、サンドボックス コード自体を制約します。 機密性の高いリソースへのアクセスを制御する必要がある場合は、サンドボックスのアクセス許可を広げるよりも狭いホスト ツールを使用します。

直接配線に HyperlightExecuteCodeTool を使用する

execute_codeを同じエージェント上の直接専用ツールと混在させる必要がある場合は、プロバイダーではなくHyperlightExecuteCodeToolを使用します。 固定構成の場合は、CodeAct 命令を 1 回ビルドし、ツールを直接接続できます。

from agent_framework_hyperlight import HyperlightExecuteCodeTool

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    approval_mode="never_require",
)

codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)

このパターンは、CodeAct サーフェスが固定されていて、実行ごとにプロバイダーのライフサイクルが必要ない場合に便利です。 HyperlightCodeActProviderとは異なり、スタンドアロン ツールはプロンプト ガイダンスを自動的に挿入しないため、build_instructions(...)出力をエージェントの指示に自分で追加する必要があります。

ファイルと送信アクセスを構成する

Hyperlight では、読み取り専用の /input ツリーと、生成された成果物の書き込み可能な /output 領域を公開できます。

• workspace_rootを使用して、/input/でワークスペースを使用できるようにします。
• file_mountsを使用して、特定のホスト パスをサンドボックスにマップします。
• 特定のターゲットまたはメソッドに対してのみ送信アクセスを有効にするには、 allowed_domains を使用します。

file_mounts は、短縮文字列、明示的な (host_path, mount_path) ペア、または FileMount 名前付きタプルを受け取ります。 allowed_domains は、文字列ターゲット、明示的な (target, method-or-methods) ペア、または AllowedDomain 名前付きタプルを受け取ります。

from agent_framework_hyperlight import HyperlightCodeActProvider

codeact = HyperlightCodeActProvider(
    tools=[compute],
    file_mounts=[
        "/host/data",
        ("/host/models", "/sandbox/models"),
    ],
    allowed_domains=[
        "api.github.com",
        ("internal.api.example.com", "GET"),
    ],
)

出力ガイダンス

execute_codeからテキストを表示するには、print(...)でコードを終了します。Hyperlight は、最後の式の値を自動的に返しません。

ファイルシステムアクセスが有効になっている場合は、代わりに /output/<filename> に大きなアーティファクトを書き込みます。 返されたファイルはツールの結果に添付されますが、 /input の下のファイルはサンドボックス内で読み取るために使用できます。

CodeAct と直接ツール呼び出しの比較

ベンチマーク サンプルでは、同じクライアント、モデル、ツール、プロンプト、および構造化された出力スキーマを使用して、従来のツール呼び出しと Hyperlight に基づく CodeAct を使用して同じタスクを 1 回実行します。 唯一の違いは配線です:ダイレクトツールとexecute_codeで支えられた単一のHyperlightCodeActProviderツール。

async def _run_traditional() -> tuple[float, AgentResponse]:
    agent = Agent(
        client=get_client(),
        name="TraditionalAgent",
        instructions=INSTRUCTIONS,
        tools=TOOLS,
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result


async def _run_codeact() -> tuple[float, AgentResponse]:
    codeact = HyperlightCodeActProvider(
        tools=TOOLS,
        approval_mode="never_require",
    )
    agent = Agent(
        client=get_client(),
        name="CodeActAgent",
        instructions=INSTRUCTIONS,
        context_providers=[codeact],
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result

このサンプルでは、エージェントは、データを繰り返し調べ、軽い計算を実行することで、ユーザーと注文のデータセット全体の総計を計算します。 これは、CodeAct がオーケストレーションのオーバーヘッドを取り除くことができる、多くの小さな手順のワークフローの一種です。 完全なサンプルでは、両方の実行の経過時間とトークンの使用状況が出力されるため、独自の環境で実行の形状を比較できます。

現在の制限

このパッケージはまだアルファであり、いくつかの制約を考慮する必要があります。

1. プラットフォームのサポートは、公開されている Hyperlight バックエンド パッケージに従います。 現在は、サポートされている Linux 環境と Windows 環境を意味します。サンドボックスを作成すると、サポートされていないプラットフォームが失敗します。
2. 現在の統合では、Python ゲスト コードが実行されます。 .NET のドキュメントはまだ近日公開予定です。
3. インメモリ インタープリターの状態は、個別の execute_code 呼び出し間で保持されません。 データが呼び出し間で存続する必要がある場合は、マウントされたファイルと /output 成果物を使用します。
4. 承認は、同じコード ブロック内の個々のexecute_codeではなく、call_tool(...)呼び出し全体に適用されます。
5. ツールの説明、パラメーター注釈、および戻り値の図形は、分離された直接ツール呼び出しを選択するのではなく、モデルがそのコントラクトに対してコードを記述しているため、ここで重要です。