Hyperlight CodeAct

Nainstalujte balíček

dotnet add package Microsoft.Agents.AI.Hyperlight --prerelease

Microsoft.Agents.AI.Hyperlight se dodává odděleně od základních abstrakcí, takže modul runtime sandboxu použijete jenom v případě, že ho potřebujete.

Použijte HyperlightCodeActProvider

HyperlightCodeActProvider je doporučený vstupní bod, pokud chcete, aby byl CodeAct automaticky přidán pro každé spuštění. Jde o AIContextProvider, který vkládá instrukce CodeAct s platností pro dané spuštění a nástroj execute_code, přičemž nástroje vlastněné poskytovatelem ponechává mimo přímé rozhraní nástrojů agenta. Poskytovatel při každém spuštění použije snapshot/restore, takže hostovaný systém při každém spuštění začíná ze známého čistého stavu.

Pomocí factory HyperlightCodeActProviderOptions.CreateForWasm(modulePath) můžete cílit na guest Pythonu založený na Wasm, který se používá v ukázkách; CreateForJavaScript() je k dispozici také pro backend JavaScriptu.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hyperlight;
using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH")
    ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");

using var codeAct = new HyperlightCodeActProvider(
    HyperlightCodeActProviderOptions.CreateForWasm(guestPath));

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions()
    {
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. When the user asks something quantitative, "
                + "write Python and call `execute_code` instead of guessing.",
        },
        AIContextProviders = [codeAct],
    });

Console.WriteLine(await agent.RunAsync("What is the 20th Fibonacci number?"));

Nástroje, připojení souborů a položky seznamu povolených odchozích přenosů lze zadat předem prostřednictvím HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) nebo spravovat za běhu prostřednictvím poskytovatele AddTools(...), , RemoveTools(...), , ClearTools()AddFileMounts(...), AddAllowedDomains(...), a odpovídajících Get* přístupových objektů.

Jak fungují schválení a hostitelské nástroje

Nástroje frameworku Agent obsahují metadata schvalování, která určují, zda je lze automaticky spouštět, nebo zda se musí pozastavit a čekat na schválení uživatelem. V .NET je schválení volitelné a aktivuje se obalením AIFunction prvkem ApprovalRequiredAIFunction.

Hlavním rozdílem mezi registrací nástroje v HyperlightCodeActProvider a jeho registrací přímo na agentovi je způsob, jakým je nástroj vyvolán, nikoli to, kde se funkce nakonec spouští:

• Nástroje zaregistrované v HyperlightCodeActProviderOptions.Tools modelu jsou skryté jako přímé nástroje. Model je dosáhne napsáním kódu, který volá call_tool("name", ...) uvnitř execute_code.
• Nástroje zaregistrované přímo na agentovi (například prostřednictvím AsAIAgent(tools: [...])) se v modelu zobrazí jako prvotřídní nástroje a každé přímé volání respektuje vlastní metadata schválení daného nástroje.

call_tool(...) je most zpět k hostitelským zpětným voláním; nejedná se o reimplementaci nástroje v sandboxu. To znamená, že nástroje vlastněné poskytovatelem se stále spouštějí v hostitelském procesu s jakýmkoli systémem souborů, sítí a přihlašovacími údaji, ke kterým má samotný hostitelský proces přístup.

Enumerace CodeActApprovalMode určuje, jak se schvaluje samotný nástroj execute_code:

• CodeActApprovalMode.NeverRequire (výchozí): schválení se přenáší z registrovaných nástrojů. Pokud je některý nástroj v registru uzavřen v ApprovalRequiredAIFunction, execute_code rovněž vyžaduje schválení; jinak ne.
• CodeActApprovalMode.AlwaysRequire: execute_code Před vyvoláním vždy vyžaduje schválení uživatele.

Obecně platí, že:

• Umístěte levné, deterministické a bezpečné nástroje pro provázání volaní u poskytovatele, aby model mohl provést mnoho volání během jednoho cyklu execute_code.
• Zabalte operace s vedlejšími účinky nebo citlivé operace do ApprovalRequiredAIFunction (a zvažte, zda je neponechat jako přímé nástroje agenta), aby každé volání zůstalo jednotlivě viditelné a schvalitelné.

Následující ukázka registruje dva bezpečné nástroje (fetch_docs, query_data) a citlivý nástroj send_email obalený v ApprovalRequiredAIFunction. Vzhledem k tomu, že alespoň jeden registrovaný nástroj vyžaduje schválení, výchozí NeverRequire režim vyžaduje execute_code schválení při každém vyvolání.

AIFunction fetchDocs = AIFunctionFactory.Create(
    (string topic) => $"Docs for {topic}: (...)",
    name: "fetch_docs",
    description: "Fetch documentation for a given topic.");

AIFunction queryData = AIFunctionFactory.Create(
    (string query) => $"Rows for `{query}`: []",
    name: "query_data",
    description: "Run a read-only SQL-like query against the sample store.");

AIFunction sendEmail = new ApprovalRequiredAIFunction(
    AIFunctionFactory.Create(
        (string to, string subject) => $"Sent '{subject}' to {to}.",
        name: "send_email",
        description: "Send an email on behalf of the user."));

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [fetchDocs, queryData, sendEmail];

using var codeAct = new HyperlightCodeActProvider(options);

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions()
    {
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. Prefer orchestrating your work in a single "
                + "`execute_code` block using `call_tool(...)` over issuing many direct tool calls.",
        },
        AIContextProviders = [codeAct],
    });

FileMounts Vzhledem k tomu, že nástroje hostitele běží mimo izolované prostředí sandbox, AllowedDomains omezují samotný kód v tomto izolovaném prostoru, nikoli zpětná volání hostitele za call_tool(...). Pokud potřebujete řízený přístup k citlivému prostředku, upřednostněte přednost úzkému hostitelskému nástroji před rozšířením oprávnění sandboxu.

Použití HyperlightExecuteCodeFunction pro přímé zapojení

Pokud potřebujete kombinovat execute_code s nástroji určenými pouze pro přímý přístup u téhož agenta nebo je konfigurace sandboxu neměnná po celou dobu životnosti agenta, použijte namísto poskytovatele HyperlightExecuteCodeFunction. Jedná se o samostatnou AIFunction službu, která zachytí jeden snímek zadaných možností v době výstavby a znovu ho použije pro každé vyvolání.

Na rozdíl od HyperlightCodeActProvider samostatná funkce nevkládá automaticky instrukce pro prompt, takže výstup BuildInstructions(...) musíte do instrukcí pro agenta přidat sami. Předejte toolsVisibleToModel: false, pokud jsou registrované nástroje dostupné pouze prostřednictvím call_tool(...), a true, pokud jsou tytéž nástroje také zpřístupněny přímo modelu.

AIFunction calculate = AIFunctionFactory.Create(
    (double a, double b) => a * b,
    name: "multiply",
    description: "Multiply two numbers.");

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [calculate];

using var executeCode = new HyperlightExecuteCodeFunction(options);

var instructions =
    "You are a helpful assistant. When math is involved, solve it by writing Python "
    + "and calling `execute_code` instead of computing values yourself.\n\n"
    + executeCode.BuildInstructions(toolsVisibleToModel: false);

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(instructions: instructions, tools: [executeCode]);

HyperlightExecuteCodeFunction implementuje IDisposabletaké . Pokud konfigurace vyžaduje schválení (podle ApprovalMode nebo proto, že je nakonfigurovaný nástroj sám zabalen do ApprovalRequiredAIFunction), instance zpřístupní proxy ApprovalRequiredAIFunction prostřednictvím AITool.GetService(...), což je způsob, jakým zbytek frameworku zjišťuje požadavky na schválení.

Konfigurace souborů a odchozího přístupu

Hyperlight může vystavit strom /input pro čtení a zapisovatelnou /output oblast pro generované artefakty.

• Použijte HostInputDirectory, aby byl adresář hostitele dostupný v rámci /input/.
• Slouží FileMounts k mapování konkrétních cest hostitele do sandboxu prostřednictvím new FileMount(hostPath, mountPath).
• Použijte AllowedDomains, abyste povolili odchozí přístup pouze pro konkrétní cíle nebo metody pomocí new AllowedDomain(target, methods).

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [compute];
options.FileMounts =
[
    new FileMount("/host/data", "/input/data"),
    new FileMount("/host/models", "/sandbox/models"),
];
options.AllowedDomains =
[
    new AllowedDomain("https://api.github.com"),
    new AllowedDomain("https://internal.api.example.com", ["GET"]),
];

using var codeAct = new HyperlightCodeActProvider(options);

Stejné kolekce FileMounts a AllowedDomains a také nástroje lze za běhu upravovat prostřednictvím AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...) a RemoveAllowedDomains(...) u HyperlightCodeActProvider.

Doprovodné materiály k výstupu

Pro zobrazení textu z execute_code, ukončete kód hosta pomocí print(...); Hyperlight nevrací hodnotu posledního výrazu automaticky.

Pokud je povolen přístup k systému souborů, místo toho zapište větší objekty do /output/<filename>. Vrácené soubory jsou připojené k výsledku nástroje, zatímco soubory v rámci /input sandboxu jsou k dispozici pro čtení.

Aktuální omezení

Tento balíček je stále ve verzi Preview a několik omezení stojí za to naplánovat:

1. Balíček závisí na Hyperlight.HyperlightSandbox.Api, což zatím není publikováno na NuGet.org. Dokud k tomu nedojde, obnovení projektu selže.
2. Podpora platformy se řídí publikovanými back-endovými balíčky Hyperlight: podporovanými prostředími Linuxu (KVM) a Windows (WHP). Při vytváření sandboxu selžou nepodporované platformy nebo chybějící back-endy virtualizace.
3. Aktuální backend Wasm spustí hostovaný modul Pythonu určený pomocí HYPERLIGHT_PYTHON_GUEST_PATH. Backend JavaScriptu (CreateForJavaScript()) je k dispozici pro hostovaný kód v JavaScriptu.
4. Stav interpreta v paměti se neuchovává napříč samostatnými voláními execute_code . Použijte namontované soubory a /output artefakty, když je potřeba, aby data byla uchována mezi jednotlivými voláními.
5. Schválení se vztahuje na execute_code vyvolání jako celek, ne na každého jednotlivce call_tool(...) uvnitř stejného bloku kódu.
6. Popisy nástrojů, poznámky k parametrům a návratové typy jsou zde důležité, protože model píše kód podle daného kontraktu, spíše než izolovaným přímým voláním nástrojů.
7. Pro ukázku benchmarku v Pythonu zatím neexistuje ekvivalent v .NETu — viz kartu Python u publikovaného testovacího nástroje pro porovnání.

Nainstalujte balíček

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight je doručován odděleně od agent-framework-core modulu runtime sandboxu, takže ho použijete pouze tehdy, když ho potřebujete.

Použijte HyperlightCodeActProvider

HyperlightCodeActProvider je doporučený vstupní bod, pokud chcete, aby byl CodeAct automaticky přidán pro každé spuštění. Vloží instrukce CodeAct s rozsahem spuštění a execute_code nástroj a přitom zachová nástroje vlastněné poskytovatelem mimo plochu nástroje přímého agenta.

import os

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

# 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],
)

# 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."
)
result = await agent.run(query)
print(result.text)

Nástroje zaregistrované na poskytovateli jsou dostupné v sandboxu prostřednictvím call_tool(...), ale nejsou zveřejněné jako nástroje přímého agenta. Zprostředkovatel také zprostředkovává správu ve stylu CRUD pro nástroje, připojení souborů a odchozí položky seznamu povolených prostřednictvím metod, jako jsou add_tools(...), remove_tool(...), add_file_mounts(...) a add_allowed_domains(...).

Jak fungují schválení a hostitelské nástroje

Nástroje Framework agenta obsahují approval_mode regulátory, které určují, zda mohou být automaticky spuštěny, nebo se musí pozastavit pro schválení od uživatele.

Hlavní rozdíl mezi registrací nástroje HyperlightCodeActProvider a jeho registrací přímo na Agent(tools=...) je způsob , jakým se nástroj vyvolá, nikoli tam, kde se funkce Pythonu nakonec spustí:

• Nástroje zaregistrované v HyperlightCodeActProvider(tools=...) modelu jsou skryté jako přímé nástroje. Model je dosáhne napsáním kódu, který volá call_tool("name", ...) uvnitř execute_code.
• Nástroje zaregistrované na Agent(tools=...) se modelu zobrazují jako prvotřídní nástroje a každé přímé volání respektuje daný nástroj v approval_mode.

call_tool(...) je most zpět k hostitelským zpětným voláním; nejedná se o reimplementaci nástroje v sandboxu. To znamená, že nástroje vlastněné poskytovatelem se stále spouštějí v hostitelském procesu s jakýmkoli systémem souborů, sítí a přihlašovacími údaji, ke kterým má samotný hostitelský proces přístup.

Obecně platí, že:

• Umístěte levné, deterministické a bezpečné nástroje pro provázání volaní u poskytovatele, aby model mohl provést mnoho volání během jednoho cyklu execute_code.
• Udržujte operace s vedlejšími účinky nebo podléhající schválení jako nástroje přímého agenta, často s approval_mode="always_require", takže každé vyvolání zůstává jednotlivě viditelné a schválitelné.

file_mounts Vzhledem k tomu, že nástroje hostitele běží mimo izolované prostředí sandbox, allowed_domains omezují samotný kód v tomto izolovaném prostoru, nikoli zpětná volání hostitele za call_tool(...). Pokud potřebujete řízený přístup k citlivému prostředku, upřednostněte přednost úzkému hostitelskému nástroji před rozšířením oprávnění sandboxu.

Použití HyperlightExecuteCodeTool pro přímé zapojení

Pokud potřebujete kombinovat execute_code nástroje pouze s přímým přístupem na stejném agentu, použijte HyperlightExecuteCodeTool místo poskytovatele. Pro pevné konfigurace můžete sestavit instrukce CodeAct jednou a připojit nástroj přímo:

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)

Tento vzor je užitečný, když je plocha CodeAct pevná a při každém spuštění nepotřebujete životní cyklus poskytovatele. Na rozdíl od HyperlightCodeActProvider samostatný nástroj nezajišťuje pokyny pro výzvy automaticky, takže zodpovídáte za přidání výstupu build_instructions(...) do pokynů agenta sami.

Konfigurace souborů a odchozího přístupu

Hyperlight může vystavit strom /input pro čtení a zapisovatelnou /output oblast pro generované artefakty.

• Použijte workspace_root ke zpřístupnění pracovního prostoru pod /input/.
• Slouží file_mounts k mapování konkrétních cest hostitelů do sandboxu.
• Umožňuje allowed_domains povolit odchozí přístup pouze pro konkrétní cíle nebo metody.

file_mounts přijímá zkrácený řetězec, explicitní (host_path, mount_path) dvojici nebo pojmenovanou FileMount n-tici. allowed_domains přijímá cíl řetězce, explicitní (target, method-or-methods) dvojici nebo pojmenovanou řazenou kolekci AllowedDomain členů.

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"),
    ],
)

Doprovodné materiály k výstupu

Pro zobrazení textu z execute_code, ukončete kód s print(...); Hyperlight nevrací hodnotu posledního výrazu automaticky.

Pokud je povolen přístup k systému souborů, místo toho zapište větší objekty do /output/<filename>. Vrácené soubory jsou připojené k výsledku nástroje, zatímco soubory v rámci /input sandboxu jsou k dispozici pro čtení.

Porovnání codeAct a přímého volání nástrojů

Koncepční porovnání je stejné jako u jakéhokoli backendu CodeAct: stejného klienta, model, nástroje, prompt a schéma strukturovaného výstupu lze zapojit buď prostřednictvím tradičního volání nástrojů, nebo prostřednictvím CodeAct postaveného na Hyperlightu. Jediný rozdíl je v rozhraní nástroje – samostatné nástroje oproti jedinému nástroji execute_code, který využívá HyperlightCodeActProvider:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.hyperlight import HyperlightCodeActProvider

# Direct tool calling: the model picks one tool at a time per turn.
direct = Agent(
    client=FoundryChatClient(...),
    instructions="...",
    tools=[fetch_data, compute],
)

# Hyperlight-backed CodeAct: the model writes one program per turn that
# orchestrates the same tools through call_tool(...).
codeact = Agent(
    client=FoundryChatClient(...),
    instructions="...",
    context_providers=[
        HyperlightCodeActProvider(
            tools=[fetch_data, compute],
            approval_mode="never_require",
        ),
    ],
)

U úloh, které počítají součty v rámci datové sady opakovaným vyhledáváním dat a prováděním nenáročných výpočtů – mnoha malých kroků, které na sebe navazují – může CodeAct odstranit režijní náklady na orchestraci. Změřte oba běhy stopkami a zkontrolujte vrácenou hodnotu ChatResponse.usage, abyste mohli ve vlastním prostředí porovnat uplynulý čas a využití tokenů.

Aktuální omezení

Tento balíček je stále ve fázi alfa a stojí za to zvážit několik omezení při plánování:

1. Podpora platformy se řídí publikovanými balíčky backendu Hyperlight. Dnes to znamená podporovaná prostředí Linuxu a Windows; Nepodporované platformy selžou při vytváření sandboxu.
2. Aktuální integrace spouští kód hosta Pythonu.
3. Stav interpreta v paměti se neuchovává napříč samostatnými voláními execute_code . Použijte namontované soubory a /output artefakty, když je potřeba, aby data byla uchována mezi jednotlivými voláními.
4. Schválení se vztahuje na execute_code vyvolání jako celek, ne na každého jednotlivce call_tool(...) uvnitř stejného bloku kódu.
5. Popisy nástrojů, poznámky k parametrům a návratové typy jsou zde důležité, protože model píše kód podle daného kontraktu, spíše než izolovaným přímým voláním nástrojů.