Hyperlight CodeAct

Installare il pacchetto

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

Microsoft.Agents.AI.Hyperlight è distribuito separatamente dalle astrazioni di base, quindi si include il runtime della sandbox solo quando serve.

Utilizzare HyperlightCodeActProvider.

HyperlightCodeActProvider è il punto di ingresso consigliato quando si vuole aggiungere automaticamente CodeAct per ogni esecuzione. Si tratta di un elemento AIContextProvider che inietta istruzioni CodeAct limitate all’ambito di esecuzione e lo strumento execute_code, mantenendo gli strumenti di proprietà del provider fuori dal set di strumenti direttamente esposto all’agente. Il fornitore applica uno snapshot e il ripristino a ogni esecuzione, in modo che il guest venga avviato da uno stato pulito e noto a ogni invocazione.

Usare la factory HyperlightCodeActProviderOptions.CreateForWasm(modulePath) per specificare come destinazione il guest Python basato su Wasm usato dagli esempi; CreateForJavaScript() è disponibile anche per il back-end JavaScript.

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

Gli strumenti, i punti di montaggio dei file e le voci dell'allow-list in uscita possono essere forniti preventivamente tramite HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) oppure gestiti in fase di esecuzione tramite AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...) e AddAllowedDomains(...) del provider e i corrispondenti Get* di accesso.

Funzionamento delle approvazioni e degli strumenti host

Gli strumenti di Agent Framework contengono metadati di approvazione che controllano se possono essere richiamati automaticamente o devono essere sospesi per l'approvazione dell'utente. In .NET, l'approvazione è facoltativa racchiudendo un AIFunction in ApprovalRequiredAIFunction.

La differenza principale tra la registrazione di uno strumento HyperlightCodeActProvider in e la registrazione diretta nell'agente è il modo in cui viene richiamato lo strumento, non dove la funzione viene eseguita in definitiva:

• Gli strumenti registrati in HyperlightCodeActProviderOptions.Tools sono nascosti dal modello come strumenti diretti. Il modello li raggiunge scrivendo codice che chiama call_tool("name", ...) all'interno di execute_code.
• Gli strumenti registrati direttamente nell'agente (ad esempio tramite AsAIAgent(tools: [...])) vengono visualizzati nel modello come strumenti di prima classe e ogni chiamata diretta rispetta i metadati di approvazione dello strumento.

call_tool(...) è un ponte verso i callback dell'host; non è una reimplementazione dello strumento nell'ambiente sandbox. Ciò significa che gli strumenti di proprietà del provider vengono ancora eseguiti nel processo host, con qualsiasi file system, rete e credenziali a cui può accedere il processo host stesso.

L'enum CodeActApprovalMode determina come lo strumento execute_code stesso viene approvato:

• CodeActApprovalMode.NeverRequire (impostazione predefinita): l'approvazione viene propagata dagli strumenti registrati. Se uno qualsiasi strumento nel registro è racchiuso in ApprovalRequiredAIFunction, anche execute_code richiede l'approvazione; altrimenti non la richiede.
• CodeActApprovalMode.AlwaysRequire: execute_code richiede sempre l'approvazione dell'utente prima della chiamata.

Come regola generale:

• Inserire strumenti economici, deterministici e sicuri nel provider in modo che il modello possa comporre molte chiamate all'interno di un turno execute_code .
• Racchiudere le operazioni con effetti collaterali o sensibili in ApprovalRequiredAIFunction (e valutare invece di mantenerle come strumenti diretti dell’agente) in modo che ogni invocazione rimanga visibile e approvabile singolarmente.

Nell'esempio seguente vengono registrati due strumenti sicuri (fetch_docs, query_data), oltre a uno strumento sensibile send_email racchiuso in ApprovalRequiredAIFunction. Poiché almeno uno strumento registrato richiede l'approvazione, la modalità predefinita NeverRequire richiede execute_code l'approvazione ogni volta che viene richiamata.

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

Poiché gli strumenti host vengono eseguiti all'esterno della sandbox, FileMounts e AllowedDomains vincolano il codice in modalità sandbox e non il callback host gestito dietro call_tool(...). Quando è necessario un accesso controllato a una risorsa sensibile, è preferibile utilizzare uno strumento host dalle capacità limitate rispetto all'estensione delle autorizzazioni nella sandbox.

Uso HyperlightExecuteCodeFunction per il cablaggio diretto

Quando è necessario utilizzare execute_code insieme a strumenti utilizzabili solo direttamente sullo stesso agente, oppure la configurazione della sandbox rimane fissa per l'intera durata dell'agente, usare HyperlightExecuteCodeFunction anziché il provider. Si tratta di un'istanza autonoma AIFunction che acquisisce un singolo snapshot delle opzioni fornite in fase di costruzione e la riutilizza per ogni chiamata.

A differenza di HyperlightCodeActProvider, la funzione autonoma non inserisce automaticamente le indicazioni per il prompt, quindi sei tu responsabile di aggiungere manualmente l'output BuildInstructions(...) alle istruzioni dell'agente. Passare toolsVisibleToModel: false quando gli strumenti registrati sono raggiungibili solo tramite call_tool(...)e true quando gli stessi strumenti vengono esposti direttamente al modello.

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 implementa anche IDisposable. Quando la configurazione richiede l'approvazione (per ApprovalMode o perché viene eseguito il wrapping di uno strumento configurato in ApprovalRequiredAIFunction), l'istanza visualizza un ApprovalRequiredAIFunction proxy tramite AITool.GetService(...), che è il modo in cui il resto del framework individua i requisiti di approvazione.

Configurare i file e l'accesso in uscita

Hyperlight può esporre un albero /input di sola lettura e un'area /output scrivibile per gli artefatti generati.

• Usare HostInputDirectory per rendere accessibile una directory host sotto /input/.
• Usare FileMounts per eseguire il mapping di percorsi host specifici nella sandbox tramite new FileMount(hostPath, mountPath).
• Usare AllowedDomains per abilitare l'accesso in uscita solo per destinazioni o metodi specifici tramite 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);

Le stesse raccolte FileMounts e AllowedDomains, oltre agli strumenti, possono anche essere modificate in fase di esecuzione tramite AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...) e RemoveAllowedDomains(...) su HyperlightCodeActProvider.

Indicazioni per l'output

Per visualizzare il testo da execute_code, terminare il codice guest con print(...); Hyperlight non restituisce automaticamente il valore dell'ultima espressione.

Quando l'accesso al file system è abilitato, scrivere invece su /output/<filename> contenuti di dimensioni maggiori. I file restituiti vengono allegati al risultato dello strumento, mentre i file all'interno di /input sono disponibili per la lettura nella sandbox.

Limitazioni correnti

Questo pacchetto è ancora in anteprima e vale la pena tenere conto di alcuni vincoli nella pianificazione:

1. Il pacchetto dipende da Hyperlight.HyperlightSandbox.Api, che non è ancora pubblicato su nuget.org. Finché non verrà pubblicato, il ripristino del progetto avrà esito negativo.
2. Il supporto della piattaforma segue i pacchetti back-end Hyperlight pubblicati: ambienti Linux (KVM) supportati e Windows (WHP). Le piattaforme non supportate o i back-end di virtualizzazione mancanti avranno esito negativo durante la creazione della sandbox.
3. Il backend Wasm attuale esegue un modulo guest di Python indicato da HYPERLIGHT_PYTHON_GUEST_PATH. Il backend JavaScript (CreateForJavaScript()) è disponibile per il codice ospite in JavaScript.
4. Lo stato dell'interprete in memoria non persiste tra diverse chiamate execute_code. Usare i file montati e gli artefatti /output quando i dati devono sopravvivere tra le chiamate.
5. L'approvazione si applica all'intera execute_code chiamata, non a ogni individuo call_tool(...) all'interno dello stesso blocco di codice.
6. Le descrizioni degli strumenti, le annotazioni dei parametri e i formati di ritorno sono molto più importanti perché il modello scrive codice in conformità con quel contratto anziché scegliere chiamate dirette isolate.
7. Non esiste ancora un equivalente .NET dell'esempio di benchmark Python — consulta la scheda Python per il test di confronto pubblicato.

Installare il pacchetto

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight viene fornito separatamente da agent-framework-core, quindi il runtime sandbox viene utilizzato solo quando necessario.

Utilizzare HyperlightCodeActProvider.

HyperlightCodeActProvider è il punto di ingresso consigliato quando si vuole aggiungere automaticamente CodeAct per ogni esecuzione. Inserisce le istruzioni CodeAct con ambito di esecuzione e lo strumento execute_code, mentre mantiene gli strumenti di proprietà del provider al di fuori della superficie degli strumenti dell'agente diretto.

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)

Gli strumenti registrati nel provider sono disponibili all'interno della sandbox tramite call_tool(...), ma non vengono esposti come strumenti dell'agente diretto. Il provider espone anche la gestione in stile CRUD per strumenti, montaggi di file e voci di elenco elementi consentiti in uscita tramite metodi come add_tools(...), remove_tool(...), add_file_mounts(...)e add_allowed_domains(...).

Funzionamento delle approvazioni e degli strumenti host

Gli strumenti di Agent Framework contengono un oggetto approval_mode che controlla se possono essere richiamati automaticamente o devono essere sospesi per l'approvazione dell'utente.

La differenza principale tra la registrazione di uno strumento HyperlightCodeActProvider in e la registrazione diretta Agent(tools=...) è il modo in cui viene richiamato lo strumento, non dove viene eseguita la funzione Python:

• Gli strumenti registrati in HyperlightCodeActProvider(tools=...) sono nascosti dal modello come strumenti diretti. Il modello li raggiunge scrivendo codice che chiama call_tool("name", ...) all'interno di execute_code.
• Gli strumenti registrati in Agent(tools=...) vengono visualizzati nel modello come strumenti di prima classe e ogni chiamata diretta rispetta il proprio approval_modestrumento.

call_tool(...) è un ponte verso i callback dell'host; non è una reimplementazione dello strumento nell'ambiente sandbox. Ciò significa che gli strumenti di proprietà del provider vengono ancora eseguiti nel processo host, con qualsiasi file system, rete e credenziali a cui può accedere il processo host stesso.

Come regola generale:

• Inserire strumenti economici, deterministici e sicuri nel provider in modo che il modello possa comporre molte chiamate all'interno di un turno execute_code .
• Mantenere le operazioni con effetti collaterali o fornite di approvazione come strumenti di agente diretto, spesso con approval_mode="always_require", in modo che ogni invocazione rimanga visibile e approvabile singolarmente.

Poiché gli strumenti host vengono eseguiti all'esterno della sandbox, file_mounts e allowed_domains vincolano il codice in modalità sandbox e non il callback host gestito dietro call_tool(...). Quando è necessario un accesso controllato a una risorsa sensibile, è preferibile utilizzare uno strumento host dalle capacità limitate rispetto all'estensione delle autorizzazioni nella sandbox.

Uso HyperlightExecuteCodeTool per il cablaggio diretto

Quando è necessario mescolare execute_code con strumenti che funzionano solo direttamente sullo stesso agente, utilizzare HyperlightExecuteCodeTool anziché il provider. Per le configurazioni fisse, è possibile compilare le istruzioni codeAct una sola volta e collegare direttamente lo strumento:

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)

Questo modello è utile quando la superficie CodeAct è fissa e non è necessario il ciclo di vita del provider in ogni esecuzione. A differenza di HyperlightCodeActProvider, lo strumento autonomo non inserisce automaticamente istruzioni di suggerimento, quindi sei responsabile di aggiungere manualmente l'output build_instructions(...) alle istruzioni dell'agente.

Configurare i file e l'accesso in uscita

Hyperlight può esporre un albero /input di sola lettura e un'area /output scrivibile per gli artefatti generati.

• Usare workspace_root per rendere disponibile un'area di lavoro in /input/.
• Usare file_mounts per eseguire il mapping di percorsi host specifici nella sandbox.
• Usare allowed_domains per abilitare l'accesso in uscita solo per destinazioni o metodi specifici.

file_mounts accetta una stringa abbreviata, una coppia di valori esplicita (host_path, mount_path) o una FileMount tupla con nome. allowed_domains accetta una stringa di destinazione, una coppia esplicita (target, method-or-methods) o una AllowedDomain tupla nominata.

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

Indicazioni per l'output

Per visualizzare il testo da execute_code, terminare il codice con print(...); Hyperlight non restituisce automaticamente il valore dell'ultima espressione.

Quando l'accesso al file system è abilitato, scrivere invece su /output/<filename> contenuti di dimensioni maggiori. I file restituiti vengono allegati al risultato dello strumento, mentre i file all'interno di /input sono disponibili per la lettura nella sandbox.

Confrontare CodeAct e le chiamate dirette agli strumenti

Il confronto concettuale è identico a quello di qualsiasi back-end CodeAct: lo stesso client, modello, strumenti, prompt e schema di output strutturato può essere cablato tramite chiamate di strumenti tradizionali o tramite CodeAct basato su Hyperlight. L'unica differenza è l'interfaccia dello strumento: strumenti diretti rispetto a un unico strumento execute_code supportato da 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",
        ),
    ],
)

Per i carichi di lavoro che calcolano i totali su un set di dati cercando ripetutamente i dati ed eseguendo calcoli leggeri — molti piccoli passaggi concatenabili — CodeAct può eliminare il sovraccarico di orchestrazione. Misura entrambe le esecuzioni con un cronometro ed esamina il valore restituito ChatResponse.usage per confrontare il tempo trascorso e l'utilizzo dei token nel tuo ambiente.

Limitazioni correnti

Questo pacchetto è ancora in fase alfa, e vale la pena tenere in considerazione alcuni vincoli durante la pianificazione:

1. Il supporto della piattaforma segue i pacchetti back-end Hyperlight pubblicati. Oggi significa ambienti Linux e Windows supportati; le piattaforme non supportate avranno esito negativo durante la creazione della sandbox.
2. L'integrazione corrente esegue il codice guest Python.
3. Lo stato dell'interprete in memoria non persiste tra diverse chiamate execute_code. Usare i file montati e gli artefatti /output quando i dati devono sopravvivere tra le chiamate.
4. L'approvazione si applica all'intera execute_code chiamata, non a ogni individuo call_tool(...) all'interno dello stesso blocco di codice.
5. Le descrizioni degli strumenti, le annotazioni dei parametri e i formati di ritorno sono molto più importanti perché il modello scrive codice in conformità con quel contratto anziché scegliere chiamate dirette isolate.