Hyperlight CodeAct

Installeer het pakket

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

Microsoft.Agents.AI.Hyperlight wordt los van de kernabstracties geleverd, dus u neemt alleen de sandbox-runtime op wanneer u deze nodig hebt.

Gebruik HyperlightCodeActProvider

HyperlightCodeActProvider is het aanbevolen toegangspunt wanneer u CodeAct automatisch wilt toevoegen voor elke uitvoering. Het is een AIContextProvider dat tot een run beperkte CodeAct-instructies en de execute_code-tool injecteert, terwijl tools van de provider buiten de directe toolinterface van de agent worden gehouden. De provider past momentopname/herstel per uitvoering toe, zodat de gast begint met een bekende schone status bij elke aanroep.

Gebruik de HyperlightCodeActProviderOptions.CreateForWasm(modulePath) factory om de op Wasm gebaseerde Python-gastomgeving te gebruiken die in de voorbeelden wordt gebruikt; CreateForJavaScript() is ook beschikbaar voor de JavaScript-backend.

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?"));

Hulpprogramma's, bestandskoppelingen en uitgaande vermeldingen op de allow-list kunnen vooraf worden opgegeven via HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) of tijdens runtime worden beheerd via de AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...) en AddAllowedDomains(...) van de provider, en de overeenkomende Get*-accessors.

Hoe goedkeuringen en hosthulpprogramma's werken

Agent Framework-hulpprogramma's bevatten goedkeuringsmetagegevens die bepalen of ze automatisch kunnen worden aangeroepen of moeten worden onderbroken voor goedkeuring van de gebruiker. In .NET moet goedkeuring expliciet worden ingeschakeld door een AIFunction in een ApprovalRequiredAIFunction te plaatsen.

Het belangrijkste verschil tussen het registreren van een hulpprogramma HyperlightCodeActProvider en het rechtstreeks registreren op de agent is de manier waarop het hulpprogramma wordt aangeroepen, niet waar de functie uiteindelijk wordt uitgevoerd:

• Geregistreerde hulpprogramma's op HyperlightCodeActProviderOptions.Tools zijn verborgen voor het model als directe tools. Het model bereikt ze door code te schrijven die call_tool("name", ...) aanroept binnen execute_code.
• Hulpprogramma's die rechtstreeks op de agent zijn geregistreerd (bijvoorbeeld via AsAIAgent(tools: [...])) worden weergegeven in het model als eersteklas hulpprogramma's en elke directe aanroep eert de eigen goedkeuringsmetagegevens van dat hulpprogramma.

call_tool(...) is een brug terug naar host-callbacks; het is geen in-sandbox herimplementatie van het hulpprogramma. Dit betekent dat hulpprogramma's die eigendom zijn van de provider nog steeds worden uitgevoerd in het hostproces, met elk bestandssysteem, netwerk en referenties waartoe het hostproces zelf toegang heeft.

De CodeActApprovalMode opsomming bepaalt hoe het execute_code hulpprogramma zelf wordt goedgekeurd:

• CodeActApprovalMode.NeverRequire (standaard): goedkeuring wordt doorgegeven vanuit de geregistreerde hulpprogramma's. Als een hulpprogramma in het register is ingesloten in ApprovalRequiredAIFunction, vereist execute_code ook goedkeuring; anders niet.
• CodeActApprovalMode.AlwaysRequire: execute_code vereist altijd goedkeuring van de gebruiker voordat u aanroept.

Vuistregel:

• Plaats goedkope, deterministische, veilig te koppelen hulpprogramma's op de provider, zodat het model veel aanroepen binnen één execute_code cyclus kan samenstellen.
• Plaats bewerkingen met neveneffecten of gevoelige bewerkingen in ApprovalRequiredAIFunction (en overweeg om ze in plaats daarvan direct als agenttools te houden), zodat elke aanroep afzonderlijk zichtbaar en goed te keuren blijft.

Het volgende voorbeeld registreert twee veilige hulpprogramma's (fetch_docs, query_data) plus een gevoelig send_email hulpmiddel dat is verpakt in ApprovalRequiredAIFunction. Omdat ten minste één geregistreerde tool goedkeuring vereist, zorgt de standaardmodus NeverRequire ervoor dat execute_code zelf goedkeuring vereist wanneer deze wordt aangeroepen.

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],
    });

Omdat hosthulpprogramma's buiten de sandbox worden uitgevoerd, beperken FileMounts en AllowedDomains de code in de sandbox zelf, niet de callback van de host achter call_tool(...). Wanneer u gecontroleerde toegang tot een gevoelige resource nodig hebt, geeft u de voorkeur aan een beperkte hosttool boven het verruimen van sandbox-machtigingen.

Gebruiken HyperlightExecuteCodeFunction voor directe bedrading

Wanneer u execute_code moet combineren met hulpprogramma's die alleen direct werken op dezelfde agent, of als de sandbox-configuratie vastligt gedurende de levensduur van de agent, gebruikt u HyperlightExecuteCodeFunction in plaats van de provider. Het is een zelfstandige versie AIFunction die één momentopname van de opgegeven opties tijdens de bouw vastlegt en opnieuw gebruikt voor elke aanroep.

Anders dan bij HyperlightCodeActProvider injecteert de losstaande functie niet automatisch promptinstructies, dus moet u zelf de uitvoer van BuildInstructions(...) aan de agentinstructies toevoegen. Geef door toolsVisibleToModel: false wanneer de geregistreerde hulpprogramma's alleen bereikbaar zijn via call_tool(...)en true wanneer dezelfde hulpprogramma's ook rechtstreeks aan het model worden blootgesteld.

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 implementeert ook IDisposable. Wanneer de configuratie goedkeuring vereist (volgens ApprovalMode of omdat een geconfigureerd hulpprogramma zelf in ApprovalRequiredAIFunction is verpakt), stelt het exemplaar via ApprovalRequiredAIFunction een AITool.GetService(...)-proxy beschikbaar; zo stelt de rest van het framework vast dat goedkeuring is vereist.

Configureer bestanden en uitgaande toegang

Hyperlight kan een structuur met het kenmerk Alleen-lezen /input weergeven plus een beschrijfbaar /output gebied voor gegenereerde artefacten.

• Gebruik HostInputDirectory om een map op de host beschikbaar te maken onder /input/.
• Gebruik FileMounts om specifieke hostpaden in de sandbox te koppelen via new FileMount(hostPath, mountPath).
• Gebruik AllowedDomains om uitgaande toegang alleen voor specifieke doelen of methoden via new AllowedDomain(target, methods) in te schakelen.

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);

Dezelfde FileMounts verzamelingen en AllowedDomains verzamelingen, plus hulpprogramma's, kunnen ook tijdens runtime worden gewijzigd via AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...)en RemoveAllowedDomains(...) aan HyperlightCodeActProvider.

Richtlijnen voor uitvoer

Als u tekst wilt weergeven van execute_code, beëindigt u de gastcode met print(...); Hyperlight retourneert niet automatisch de waarde van de laatste expressie.

Wanneer de toegang tot het bestandssysteem is ingeschakeld, sla dan grotere objecten op in /output/<filename>. Geretourneerde bestanden worden gekoppeld aan het resultaat van het hulpprogramma, terwijl bestanden onder /input beschikbaar zijn om te lezen in de sandbox.

Huidige beperkingen

Dit pakket is nog in preview en er zijn een paar beperkingen waar u bij de planning rekening mee moet houden:

1. Het pakket is afhankelijk van Hyperlight.HyperlightSandbox.Api, dat nog niet is gepubliceerd op nuget.org. Totdat dat gebeurt, mislukt het herstellen van het project.
2. Platformondersteuning volgt de gepubliceerde Hyperlight-back-endpakketten: ondersteunde Linux-omgevingen (KVM) en Windows (WHP). Niet-ondersteunde platforms of ontbrekende back-ends voor virtualisatie mislukken bij het maken van de sandbox.
3. De huidige Wasm-back-end voert een Python gastmodule uit die is opgegeven door HYPERLIGHT_PYTHON_GUEST_PATH. De JavaScript-back-end (CreateForJavaScript()) is beschikbaar voor gastcode in JavaScript.
4. De toestand van de in-memory interpreter blijft niet behouden bij aparte execute_code aanroepen. Gebruik gekoppelde bestanden en /output artefacten wanneer gegevens moeten blijven bestaan tussen aanroepen.
5. Goedkeuring is van toepassing op de execute_code aanroep als geheel, niet op elke persoon call_tool(...) in hetzelfde codeblok.
6. Beschrijvingen van hulpprogramma's, parameteraantekeningen en de vorm van retourwaarden zijn hier belangrijker omdat het model code schrijft op basis van dat contract in plaats van voor geïsoleerde directe hulpprogramma-oproepen te kiezen.
7. Er is nog geen .NET equivalent van het Python benchmark-voorbeeld. Zie het tabblad Python voor het gepubliceerde vergelijkingsharnas.

Installeer het pakket

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight wordt afzonderlijk geleverd van agent-framework-core, zodat u alleen de sandbox-runtime opneemt wanneer u deze nodig hebt.

Gebruik HyperlightCodeActProvider

HyperlightCodeActProvider is het aanbevolen toegangspunt wanneer u CodeAct automatisch wilt toevoegen voor elke uitvoering. Het injecteert run-scoped CodeAct-instructies plus execute_code tool, terwijl de provider-eigen tools buiten het directe bereik van de agent houden.

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)

Hulpprogramma's geregistreerd op de provider zijn beschikbaar in de sandbox via call_tool(...), maar worden niet weergegeven als direct beschikbare agenthulpprogramma's. De provider maakt ook CRUD-stijlbeheer beschikbaar voor tools, bestandkoppelingen en uitgaande allow-list-vermeldingen via methoden zoals add_tools(...), remove_tool(...), add_file_mounts(...) en add_allowed_domains(...).

Hoe goedkeuringen en hosthulpprogramma's werken

Agent Framework-hulpprogramma's bevatten een approval_mode die bepaalt of ze automatisch kunnen worden aangeroepen of moeten worden onderbroken voor goedkeuring van de gebruiker.

Het belangrijkste verschil tussen het registreren van een hulpprogramma HyperlightCodeActProvider en het rechtstreeks Agent(tools=...) registreren ervan is hoe het hulpprogramma wordt aangeroepen, niet waar de Python-functie uiteindelijk wordt uitgevoerd:

• Geregistreerde hulpprogramma's op HyperlightCodeActProvider(tools=...) zijn verborgen voor het model als directe tools. Het model bereikt ze door code te schrijven die call_tool("name", ...) aanroept binnen execute_code.
• Hulpprogramma's die zijn geregistreerd op Agent(tools=...), worden als eersteklas hulpprogramma's weergegeven aan het model en bij elke directe aanroep wordt de eigen approval_mode gerespecteerd.

call_tool(...) is een brug terug naar host-callbacks; het is geen in-sandbox herimplementatie van het hulpprogramma. Dit betekent dat hulpprogramma's die eigendom zijn van de provider nog steeds worden uitgevoerd in het hostproces, met elk bestandssysteem, netwerk en referenties waartoe het hostproces zelf toegang heeft.

Vuistregel:

• Plaats goedkope, deterministische, veilig te koppelen hulpprogramma's op de provider, zodat het model veel aanroepen binnen één execute_code cyclus kan samenstellen.
• Houd side-effect-inducerende of goedkeuringsgebonden bewerkingen als directe agenttools en vaak met approval_mode="always_require", zodat elke aanroep afzonderlijk zichtbaar en keurbaar blijft.

Omdat hosthulpprogramma's buiten de sandbox worden uitgevoerd, beperken file_mounts en allowed_domains de code in de sandbox zelf, niet de callback van de host achter call_tool(...). Wanneer u gecontroleerde toegang tot een gevoelige resource nodig hebt, geeft u de voorkeur aan een beperkte hosttool boven het verruimen van sandbox-machtigingen.

Gebruiken HyperlightExecuteCodeTool voor directe bedrading

Gebruik execute_code in plaats van de provider wanneer u HyperlightExecuteCodeTool moet combineren met hulpprogramma's voor direct-only op dezelfde agent. Voor vaste configuraties kunt u de CodeAct-instructies eenmaal compileren en het hulpprogramma rechtstreeks bedraden:

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)

Dit patroon is handig wanneer het CodeAct-oppervlak gefixeerd is en de levenscyclus van de provider niet bij elke uitvoering nodig is. In tegenstelling tot HyperlightCodeActProvider injecteert het zelfstandige hulpprogramma promptrichtlijnen niet automatisch, dus u bent zelf verantwoordelijk voor het toevoegen van de build_instructions(...) uitvoer aan de agentinstructies.

Configureer bestanden en uitgaande toegang

Hyperlight kan een structuur met het kenmerk Alleen-lezen /input weergeven plus een beschrijfbaar /output gebied voor gegenereerde artefacten.

• Gebruik workspace_root dit om een werkruimte beschikbaar te maken onder /input/.
• Gebruik file_mounts om specifieke hostpaden naar de sandbox te mappen.
• Gebruik allowed_domains dit om uitgaande toegang alleen in te schakelen voor specifieke doelen of methoden.

file_mounts accepteert een verkorte notatie, een expliciet (host_path, mount_path) paar of een FileMount genoemde tuple. allowed_domains accepteert een doelstring, een expliciet (target, method-or-methods) paar of een AllowedDomain tuple met naam.

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

Richtlijnen voor uitvoer

Om tekst uit execute_code weer te geven, beëindig de code met print(...); Hyperlight retourneert de waarde van de laatste expressie niet automatisch.

Wanneer de toegang tot het bestandssysteem is ingeschakeld, sla dan grotere objecten op in /output/<filename>. Geretourneerde bestanden worden gekoppeld aan het resultaat van het hulpprogramma, terwijl bestanden onder /input beschikbaar zijn om te lezen in de sandbox.

CodeAct en directe hulpprogramma-aanroepen vergelijken

De conceptuele vergelijking komt overeen met die voor elke CodeAct-backend: dezelfde client, hetzelfde model, tools, prompt en hetzelfde schema voor gestructureerde uitvoer kunnen worden gekoppeld via traditionele tool-calling of via door Hyperlight ondersteunde CodeAct. Het enige verschil is het gereedschapoppervlak : directe hulpmiddelen versus één execute_code gereedschap dat wordt ondersteund door 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",
        ),
    ],
)

Voor workloads die totalen over een dataset berekenen door herhaaldelijk gegevens op te zoeken en beperkte berekeningen uit te voeren — veel kleine, aaneenschakelbare stappen — kan CodeAct orkestratie-overhead wegnemen. Verpakt beide uitvoeringen met een stopwatch en inspecteer de geretourneerde ChatResponse.usage waarden om het verstreken tijd- en tokengebruik in uw eigen omgeving te vergelijken.

Huidige beperkingen

Dit pakket bevindt zich nog steeds in de alfafase en het is verstandig om met een paar beperkingen rekening te houden.

1. Platformondersteuning volgt de gepubliceerde Hyperlight-back-endpakketten. Tegenwoordig betekent dit ondersteunde Linux- en Windows-omgevingen; niet-ondersteunde platforms mislukken bij het maken van de sandbox.
2. De huidige integratie voert Python-gastcode uit.
3. De toestand van de in-memory interpreter blijft niet behouden bij aparte execute_code aanroepen. Gebruik gekoppelde bestanden en /output artefacten wanneer gegevens moeten blijven bestaan tussen aanroepen.
4. Goedkeuring is van toepassing op de execute_code aanroep als geheel, niet op elke persoon call_tool(...) in hetzelfde codeblok.
5. Beschrijvingen van hulpprogramma's, parameteraantekeningen en de vorm van retourwaarden zijn hier belangrijker omdat het model code schrijft op basis van dat contract in plaats van voor geïsoleerde directe hulpprogramma-oproepen te kiezen.