Hyperlight CodeAct

Instalar o pacote

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

Microsoft.Agents.AI.Hyperlight é distribuído separadamente das abstrações centrais, portanto você só precisa do runtime de sandbox quando necessário.

Utilize HyperlightCodeActProvider

HyperlightCodeActProvider é o ponto de entrada recomendado quando você deseja que CodeAct seja adicionado automaticamente para cada execução. É um AIContextProvider que injeta instruções do CodeAct no escopo da execução, bem como a ferramenta execute_code, mantendo as ferramentas pertencentes ao provedor fora da superfície direta de ferramentas do agente. O provedor aplica snapshot e restauração a cada execução para que o sistema convidado inicie em um estado limpo e conhecido a cada invocação.

Use a fábrica HyperlightCodeActProviderOptions.CreateForWasm(modulePath) para direcionar o convidado de Python baseado em Wasm usado pelos exemplos; CreateForJavaScript() também está disponível para o 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?"));

Ferramentas, montagens de arquivos e entradas da lista de permissões de saída podem ser fornecidas antecipadamente via HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) ou gerenciadas em tempo de execução por meio de AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...), AddAllowedDomains(...) do provedor e dos acessadores Get* correspondentes.

Como as aprovações e as ferramentas de host funcionam

As ferramentas do Agent Framework têm metadados de aprovação que controlam se podem ser invocados automaticamente ou devem pausar para aprovação do usuário. Em .NET, a aprovação é aceita encapsulando um AIFunction em ApprovalRequiredAIFunction.

A principal diferença entre registrar uma ferramenta HyperlightCodeActProvider e registrá-la diretamente no agente é como a ferramenta é invocada, não onde a função é executada:

• As ferramentas registradas em HyperlightCodeActProviderOptions.Tools estão ocultas para o modelo como ferramentas diretas. O modelo os alcança escrevendo código que chama call_tool("name", ...) dentro execute_code.
• As ferramentas registradas diretamente no agente (por exemplo via AsAIAgent(tools: [...])) são exibidas no modelo como ferramentas de primeira classe e cada chamada direta respeita os metadados de aprovação da própria ferramenta.

call_tool(...) é uma ponte de volta para os retornos de chamada para o host; não é uma reimplementação da ferramenta no ambiente isolado. Isso significa que as ferramentas de propriedade do provedor ainda são executadas no processo de host, com qualquer sistema de arquivos, rede e credenciais que o próprio processo de host possa acessar.

O CodeActApprovalMode enum controla como a própria ferramenta execute_code é aprovada:

• CodeActApprovalMode.NeverRequire (padrão): a aprovação é propagada a partir das ferramentas registradas. Se alguma ferramenta no registro estiver encapsulada em ApprovalRequiredAIFunction, execute_code também requer aprovação; caso contrário, não requer.
• CodeActApprovalMode.AlwaysRequire: execute_code sempre requer aprovação do usuário antes da invocação.

Como regra geral:

• Coloque ferramentas baratas, determinísticas e seguras em cadeia no provedor para que o modelo possa compor muitas chamadas em uma única execute_code vez.
• Encapsule operações com efeitos colaterais ou sensíveis em ApprovalRequiredAIFunction (e considere mantê-las como ferramentas diretas do agente) para que cada invocação permaneça individualmente visível e passível de aprovação.

O exemplo a seguir registra duas ferramentas seguras (fetch_docs, query_data) mais uma ferramenta confidencial send_email encapsulada em ApprovalRequiredAIFunction. Como pelo menos uma ferramenta registrada requer aprovação, o modo padrão NeverRequire faz execute_code com que ela exija aprovação sempre que é invocada.

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

Como as ferramentas de host são executadas fora da área restrita, FileMounts e AllowedDomains restringem o código dentro da área restrita, não o callback do host por trás de call_tool(...). Quando você precisar de acesso controlado a um recurso confidencial, prefira uma ferramenta de host estreita em vez de ampliar as permissões de área restrita.

Utilize HyperlightExecuteCodeFunction para conexão direta

Quando precisar combinar execute_code com ferramentas de acesso direto apenas no mesmo agente, ou se a configuração da sandbox permanecer fixa durante toda a vida útil do agente, use HyperlightExecuteCodeFunction em vez do provedor. É um recurso autônomo AIFunction que captura um único instantâneo das opções fornecidas no momento da construção e o reutiliza para cada invocação.

Ao contrário de HyperlightCodeActProvider, a função autônoma não injeta automaticamente a orientação de prompt, portanto você é responsável por adicionar você mesmo a saída BuildInstructions(...) às instruções do agente. Passe toolsVisibleToModel: false quando as ferramentas registradas forem acessíveis somente por meio de call_tool(...), e true quando essas mesmas ferramentas também forem expostas diretamente ao modelo.

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 também implementa IDisposable. Quando a configuração requer aprovação (por ApprovalMode ou porque uma ferramenta configurada está encapsulada em ApprovalRequiredAIFunction), a instância expõe um proxy ApprovalRequiredAIFunction por meio de AITool.GetService(...), que é como o restante do framework detecta os requisitos de aprovação.

Configurar arquivos e acesso de saída

O Hyperlight pode expor uma árvore somente para leitura /input além de uma área gravável /output para artefatos gerados.

• Use HostInputDirectory para disponibilizar um diretório do host em /input/.
• Use FileMounts para mapear caminhos específicos do host no sandbox por meio de new FileMount(hostPath, mountPath).
• Use AllowedDomains para habilitar o acesso de saída apenas para destinos ou métodos específicos por meio de 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);

As mesmas coleções FileMounts e AllowedDomains, além das ferramentas, também podem ser modificadas em tempo de execução por meio de AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...) e RemoveAllowedDomains(...) em HyperlightCodeActProvider.

Diretrizes de saída

Para exibir o texto de execute_code, encerre o código convidado com print(...); O Hyperlight não retorna automaticamente o valor da última expressão.

Quando o acesso ao sistema de arquivos estiver habilitado, escreva artefatos maiores em /output/<filename> em vez disso. Os arquivos retornados são anexados ao resultado da ferramenta, enquanto os arquivos /input embaixo estão disponíveis para leitura dentro da área restrita.

Limitações atuais

Este pacote ainda está em versão prévia, e algumas limitações devem ser consideradas no planejamento:

1. O pacote depende de Hyperlight.HyperlightSandbox.Api, que ainda não foi publicado em nuget.org. Até que isso seja lançado, a restauração do projeto falhará.
2. O suporte à plataforma segue os pacotes de back-end do Hyperlight publicados: ambientes com suporte para Linux (KVM) e WINDOWS (WHP). Plataformas sem suporte ou a ausência de mecanismos de virtualização causarão falha na criação do sandbox.
3. O back-end wasm atual executa um módulo convidado Python especificado por HYPERLIGHT_PYTHON_GUEST_PATH. O backend JavaScript (CreateForJavaScript()) está disponível para código executado como convidado em JavaScript.
4. O estado do interpretador na memória não persiste entre chamadas separadas execute_code . Use arquivos e /output artefatos montados quando os dados precisarem sobreviver entre chamadas.
5. A aprovação se aplica à execute_code invocação como um todo, não a cada indivíduo call_tool(...) dentro do mesmo bloco de código.
6. Descrições de ferramenta, anotações de parâmetro e estruturas de retorno importam mais aqui porque o modelo está gerando código com base nesse contrato em vez de optar por chamadas diretas de ferramenta isoladas.
7. Ainda não há um exemplo de benchmark equivalente em .NET — consulte a aba Python para ver a infraestrutura de comparação publicada.

Instalar o pacote

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight é enviado separadamente de agent-framework-core, então você só assume o runtime da área restrita quando precisar.

Utilize HyperlightCodeActProvider

HyperlightCodeActProvider é o ponto de entrada recomendado quando você deseja que CodeAct seja adicionado automaticamente para cada execução. Ele injeta instruções CodeAct com escopo de execução, além da ferramenta execute_code, enquanto mantém as ferramentas de propriedade do provedor fora da superfície direta da ferramenta do agente.

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)

As ferramentas registradas no provedor estão disponíveis dentro da área restrita através de call_tool(...), mas não são expostas como ferramentas de agentes diretos. O provedor também expõe o gerenciamento de estilo CRUD para ferramentas, montagens de arquivo e entradas de lista de permissões de saída por meio de métodos como add_tools(...), remove_tool(...), add_file_mounts(...) e add_allowed_domains(...).

Como as aprovações e as ferramentas de host funcionam

As ferramentas do Agent Framework têm um approval_mode controle que controla se elas podem ser invocadas automaticamente ou devem pausar para aprovação do usuário.

A principal diferença entre registrar uma ferramenta HyperlightCodeActProvider e registrá-la diretamente Agent(tools=...) é como a ferramenta é invocada, não onde a função Python é executada:

• As ferramentas registradas em HyperlightCodeActProvider(tools=...) estão ocultas para o modelo como ferramentas diretas. O modelo os alcança escrevendo código que chama call_tool("name", ...) dentro execute_code.
• Ferramentas registradas no Agent(tools=...) são exibidas como ferramentas de primeira classe, e cada chamada direta respeita o approval_mode da própria ferramenta.

call_tool(...) é uma ponte de volta para os retornos de chamada para o host; não é uma reimplementação da ferramenta no ambiente isolado. Isso significa que as ferramentas de propriedade do provedor ainda são executadas no processo de host, com qualquer sistema de arquivos, rede e credenciais que o próprio processo de host possa acessar.

Como regra geral:

• Coloque ferramentas baratas, determinísticas e seguras em cadeia no provedor para que o modelo possa compor muitas chamadas em uma única execute_code vez.
• Mantenha operações que provocam efeitos colaterais ou que necessitam de aprovação como ferramentas diretas do agente, geralmente com approval_mode="always_require", para que cada invocação permaneça individualmente visível e aprovável.

Como as ferramentas de host são executadas fora da área restrita, file_mounts e allowed_domains restringem o código dentro da área restrita, não o callback do host por trás de call_tool(...). Quando você precisar de acesso controlado a um recurso confidencial, prefira uma ferramenta de host estreita em vez de ampliar as permissões de área restrita.

Utilize HyperlightExecuteCodeTool para conexão direta

Quando você precisar integrar execute_code a ferramentas de acesso direto no mesmo agente, use HyperlightExecuteCodeTool em vez do provedor. Para configurações fixas, você pode criar as instruções codeact uma vez e conectar a ferramenta diretamente:

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)

Esse padrão é útil quando a superfície CodeAct é fixa e você não precisa do ciclo de vida do provedor a cada execução. Ao contrário de HyperlightCodeActProvider, a ferramenta autônoma não injeta diretrizes de prompt automaticamente, portanto, você é responsável por adicionar a build_instructions(...) saída às instruções do agente você mesmo.

Configurar arquivos e acesso de saída

O Hyperlight pode expor uma árvore somente para leitura /input além de uma área gravável /output para artefatos gerados.

• Use workspace_root para disponibilizar um espaço de trabalho em /input/.
• Use file_mounts para mapear caminhos de host específicos para o sandbox.
• Use allowed_domains para habilitar o acesso de saída apenas para destinos ou métodos específicos.

file_mounts aceita uma cadeia de caracteres abreviada, um par explícito (host_path, mount_path) ou uma FileMount tupla nomeada. allowed_domains aceita uma string de destino, um par explícito (target, method-or-methods) ou uma tupla nomeada 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"),
    ],
)

Diretrizes de saída

Para exibir o texto de execute_code, encerre o código com print(...); O Hyperlight não retorna automaticamente o valor da última expressão.

Quando o acesso ao sistema de arquivos estiver habilitado, escreva artefatos maiores em /output/<filename> em vez disso. Os arquivos retornados são anexados ao resultado da ferramenta, enquanto os arquivos /input embaixo estão disponíveis para leitura dentro da área restrita.

Comparar CodeAct e chamada de ferramenta direta

A comparação conceitual é a mesma que a de qualquer backend do CodeAct: o mesmo cliente, modelo, ferramentas, prompt e esquema de saída estruturado pode ser integrado tanto por meio da chamada tradicional de ferramentas quanto por meio do CodeAct com suporte do Hyperlight. A única diferença é a superfície da ferramenta – ferramentas diretas versus uma única execute_code ferramenta apoiada por 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",
        ),
    ],
)

Para cargas de trabalho que calculam totais em um conjunto de dados consultando dados repetidamente e realizando cálculos simples — muitas etapas pequenas e encadeáveis — o CodeAct pode eliminar a sobrecarga de orquestração. Envolva as duas execuções com um cronômetro e inspecione o ChatResponse.usage retornado para comparar o tempo decorrido e o uso de tokens em seu próprio ambiente.

Limitações atuais

Este pacote ainda está na fase alfa, e algumas restrições valem a pena ser consideradas no planejamento.

1. O suporte à plataforma segue os pacotes de back-end do Hyperlight publicados. Hoje isso significa ambientes Linux e Windows com suporte; As plataformas sem suporte falharão ao criar a área restrita.
2. A integração atual executa o código convidado do Python.
3. O estado do interpretador na memória não persiste entre chamadas separadas execute_code . Use arquivos e /output artefatos montados quando os dados precisarem sobreviver entre chamadas.
4. A aprovação se aplica à execute_code invocação como um todo, não a cada indivíduo call_tool(...) dentro do mesmo bloco de código.
5. Descrições de ferramenta, anotações de parâmetro e estruturas de retorno importam mais aqui porque o modelo está gerando código com base nesse contrato em vez de optar por chamadas diretas de ferramenta isoladas.