Hyperlight CodeAct

Instalar el paquete

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

Microsoft.Agents.AI.Hyperlight se distribuye por separado de las abstracciones del núcleo, por lo que solo incorporas el entorno de ejecución de aislamiento cuando lo necesitas.

Utilice HyperlightCodeActProvider

HyperlightCodeActProvider es el punto de entrada recomendado cuando desea que CodeAct se agregue automáticamente para cada ejecución. Es un AIContextProvider que inyecta instrucciones CodeAct de alcance de ejecución junto con la herramienta execute_code, al tiempo que mantiene las herramientas del proveedor fuera de la interfaz directa de herramientas del agente. El proveedor aplica la creación y restauración de instantáneas en cada ejecución para que el sistema invitado comience a partir de un estado limpio conocido en cada invocación.

Use el generador de HyperlightCodeActProviderOptions.CreateForWasm(modulePath) para tener como destino el invitado de Python basado en Wasm usado por los ejemplos; CreateForJavaScript() también está disponible para el back-end de 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?"));

Las herramientas, los montajes de archivos y las entradas de la lista de permitidos de salida pueden proporcionarse por adelantado mediante HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) o gestionarse en tiempo de ejecución mediante AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...), AddAllowedDomains(...) y los descriptores de acceso Get* correspondientes del proveedor.

Funcionamiento de las aprobaciones y las herramientas de host

Las herramientas de Agent Framework llevan metadatos de aprobación que controlan si se pueden invocar automáticamente o deben pausar para la aprobación del usuario. En .NET, la aprobación es opcional encapsulando un AIFunction en ApprovalRequiredAIFunction.

La principal diferencia entre registrar una herramienta en HyperlightCodeActProvider y registrarla directamente en el agente es cómo se invoca la herramienta, no dónde se ejecuta la función en última instancia:

• Las herramientas registradas en HyperlightCodeActProviderOptions.Tools se ocultan del modelo como herramientas directas. El modelo los alcanza al escribir código que llama a call_tool("name", ...) dentro de execute_code.
• Las herramientas registradas directamente en el agente (por ejemplo, a través de AsAIAgent(tools: [...])) se presentan al modelo como herramientas de primera clase, y cada llamada directa respeta sus propios metadatos de aprobación.

call_tool(...) es un puente de vuelta a los callbacks del host; no es una reimplementación en sandbox de la herramienta. Esto significa que las herramientas propiedad del proveedor siguen ejecutándose en el proceso de host, con cualquier sistema de archivos, red y credenciales a las que pueda acceder el propio proceso de host.

La enumeración CodeActApprovalMode controla cómo se aprueba la herramienta execute_code en sí:

• CodeActApprovalMode.NeverRequire (valor predeterminado): la aprobación se propaga desde las herramientas registradas. Si alguna herramienta del registro está encapsulada en ApprovalRequiredAIFunction, execute_code también requiere aprobación; de lo contrario, no la requiere.
• CodeActApprovalMode.AlwaysRequire: execute_code siempre requiere la aprobación del usuario antes de la invocación.

Como regla general:

• Ponga herramientas baratas, deterministas y seguras para encadenar en el proveedor, de modo que el modelo pueda componer muchas llamadas en un solo turno execute_code.
• Envuelva las operaciones con efectos secundarios o sensibles en ApprovalRequiredAIFunction (y considere la posibilidad de mantenerlas en su lugar como herramientas directas del agente) para que cada invocación siga siendo visible y susceptible de aprobación de forma individual.

En el ejemplo siguiente se registran dos herramientas seguras (fetch_docs, query_data) más una herramienta confidencial send_email encapsulada en ApprovalRequiredAIFunction. Dado que al menos una herramienta registrada requiere aprobación, el modo predeterminado NeverRequire hace execute_code que se requiera aprobación siempre que se invoque.

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

Dado que las herramientas de host se ejecutan fuera del espacio aislado, FileMounts y AllowedDomains restringen el código del espacio aislado en sí mismo, no la devolución de llamada del host detrás de call_tool(...). Cuando necesite acceso controlado a un recurso confidencial, prefiera una herramienta de host acotada sobre la ampliación de los permisos de sandbox.

Uso HyperlightExecuteCodeFunction para cableado directo

Cuando necesite combinar execute_code con herramientas solo directas en el mismo agente, o la configuración del espacio aislado permanece fija durante toda la vida útil del agente, use HyperlightExecuteCodeFunction en lugar del proveedor. Es un AIFunction independiente que captura una única instantánea de las opciones proporcionadas en el momento de la construcción y la reutiliza para cada invocación.

A diferencia de HyperlightCodeActProvider, la función autónoma no incorpora automáticamente las indicaciones del prompt, por lo que debe agregar usted mismo la salida de BuildInstructions(...) a las instrucciones del agente. Use toolsVisibleToModel: false cuando solo se pueda acceder a las herramientas registradas a través de call_tool(...), y true cuando las mismas herramientas también estén expuestas directamente al 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 también implementa IDisposable. Cuando la configuración requiere aprobación (por ApprovalMode o porque una herramienta configurada está encapsulada en ApprovalRequiredAIFunction), la instancia expone un proxy ApprovalRequiredAIFunction a través de AITool.GetService(...), que es como el resto del framework detecta los requisitos de aprobación.

Configuración de archivos y acceso saliente

Hyperlight puede exponer un árbol de /input solo lectura más un área /output escribible para artefactos generados.

• Use HostInputDirectory para que un directorio host esté disponible en /input/.
• Utilice FileMounts para mapear rutas específicas del host en el espacio aislado mediante new FileMount(hostPath, mountPath).
• Use AllowedDomains para habilitar el acceso saliente solo para destinos o métodos específicos a través 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);

Las mismas colecciones FileMounts y AllowedDomains, además de las herramientas, también se pueden modificar en tiempo de ejecución a través de AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...) y RemoveAllowedDomains(...) en HyperlightCodeActProvider.

Guía para la gestión de resultados

Para exponer texto de execute_code, finalice el código invitado con print(...); Hyperlight no devuelve automáticamente el valor de la última expresión.

Cuando el acceso al sistema de archivos está habilitado, escriba en su lugar artefactos más grandes en /output/<filename>. Los archivos devueltos se adjuntan al resultado de la herramienta, mientras que los archivos en /input están disponibles para su lectura dentro del espacio aislado (sandbox).

Limitaciones actuales

Este paquete aún está en versión preliminar, y conviene tener en cuenta algunas limitaciones al planificar:

1. El paquete depende de Hyperlight.HyperlightSandbox.Api, que aún no se ha publicado en nuget.org. Hasta que eso se publique, la restauración del proyecto fallará.
2. La compatibilidad con la plataforma sigue los paquetes de back-end de Hyperlight publicados: entornos compatibles con Linux (KVM) y Windows (WHP). Las plataformas no admitidas o los backends de virtualización ausentes fallarán al crear el espacio aislado.
3. El back-end wasm actual ejecuta un módulo invitado Python especificado por HYPERLIGHT_PYTHON_GUEST_PATH. El backend de JavaScript (CreateForJavaScript()) está disponible para ejecutar código huésped en JavaScript.
4. El estado del intérprete en memoria no se conserva en llamadas independientes execute_code . Utilice archivos montados y /output artefactos cuando los datos deban persistir entre llamadas.
5. La aprobación se aplica a la execute_code invocación en su conjunto, no a cada individuo call_tool(...) dentro del mismo bloque de código.
6. Las descripciones de herramientas, las anotaciones de parámetros y los formatos de retorno son más importantes en este contexto porque el modelo está escribiendo código siguiendo ese contrato en lugar de elegir llamadas directas a herramientas aisladas.
7. Todavía no hay ningún equivalente .NET del ejemplo de pruebas comparativas de Python; consulte la pestaña Python del arnés de comparación publicado.

Instalar el paquete

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight se distribuye por separado de agent-framework-core, por lo que solo se toma el entorno de ejecución sandbox cuando lo necesita.

Utilice HyperlightCodeActProvider

HyperlightCodeActProvider es el punto de entrada recomendado cuando desea que CodeAct se agregue automáticamente para cada ejecución. Inserta instrucciones CodeAct con ámbito de ejecución, además de la herramienta execute_code, mientras mantiene las herramientas propiedad del proveedor fuera de la superficie de herramientas directamente accesibles por el 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)

Las herramientas registradas en el proveedor están disponibles dentro del espacio aislado a través de call_tool(...), pero no se exponen como herramientas de agentes directos. El proveedor también expone la administración de estilo CRUD para herramientas, montajes de archivos y entradas de lista de permitidos salientes a través de métodos como add_tools(...), remove_tool(...), add_file_mounts(...)y add_allowed_domains(...).

Funcionamiento de las aprobaciones y las herramientas de host

Las herramientas de Agent Framework llevan un approval_mode que controla si se pueden invocar automáticamente o deben pausar para la aprobación del usuario.

La principal diferencia entre registrar una herramienta HyperlightCodeActProvider en y registrarla directamente en Agent(tools=...) es cómo se invoca la herramienta, no dónde se ejecuta la función de Python en última instancia:

• Las herramientas registradas en HyperlightCodeActProvider(tools=...) se ocultan del modelo como herramientas directas. El modelo los alcanza al escribir código que llama a call_tool("name", ...) dentro de execute_code.
• Las herramientas registradas en Agent(tools=...) se muestran en el modelo como herramientas de primera clase y cada llamada directa respeta la propiedad approval_modede esa herramienta.

call_tool(...) es un puente de vuelta a los callbacks del host; no es una reimplementación en sandbox de la herramienta. Esto significa que las herramientas propiedad del proveedor siguen ejecutándose en el proceso de host, con cualquier sistema de archivos, red y credenciales a las que pueda acceder el propio proceso de host.

Como regla general:

• Ponga herramientas baratas, deterministas y seguras para encadenar en el proveedor, de modo que el modelo pueda componer muchas llamadas en un solo turno execute_code.
• Mantenga las operaciones de efecto secundario o de aprobación condicionada como herramientas directas del agente, a menudo con approval_mode="always_require", por lo que cada invocación permanece visible y aprobable individualmente.

Dado que las herramientas de host se ejecutan fuera del espacio aislado, file_mounts y allowed_domains restringen el código del espacio aislado en sí mismo, no la devolución de llamada del host detrás de call_tool(...). Cuando necesite acceso controlado a un recurso confidencial, prefiera una herramienta de host acotada sobre la ampliación de los permisos de sandbox.

Uso HyperlightExecuteCodeTool para cableado directo

Cuando necesite mezclar execute_code con herramientas de solo acceso directo en el mismo agente, use HyperlightExecuteCodeTool en lugar del proveedor. Para configuraciones fijas, puede compilar las instrucciones de CodeAct una vez y conectar la herramienta directamente:

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)

Este patrón es útil cuando la interfaz de CodeAct es fija y no necesita el ciclo de vida del proveedor en cada ejecución. A diferencia de HyperlightCodeActProvider, la herramienta independiente no inserta automáticamente instrucciones de solicitud, así que usted es responsable de agregar la salida de build_instructions(...) a las instrucciones del agente por su cuenta.

Configuración de archivos y acceso saliente

Hyperlight puede exponer un árbol de /input solo lectura más un área /output escribible para artefactos generados.

• Use workspace_root para que un área de trabajo esté disponible en /input/.
• Use file_mounts para asignar rutas de acceso de host específicas al espacio aislado.
• Use allowed_domains para habilitar el acceso saliente solo para destinos o métodos específicos.

file_mounts acepta una cadena abreviada, un par explícito (host_path, mount_path) o una FileMount tupla con nombre. allowed_domains acepta una cadena de destino, un par explícito (target, method-or-methods) o una AllowedDomain tupla nombrada.

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

Guía para la gestión de resultados

Para exponer texto de execute_code, finalice el código con print(...); Hyperlight no devuelve automáticamente el valor de la última expresión.

Cuando el acceso al sistema de archivos está habilitado, escriba en su lugar artefactos más grandes en /output/<filename>. Los archivos devueltos se adjuntan al resultado de la herramienta, mientras que los archivos en /input están disponibles para su lectura dentro del espacio aislado (sandbox).

Comparación de CodeAct y llamadas directas a herramientas

La comparación conceptual es la misma que para cualquier backend de CodeAct: el mismo cliente, modelo, herramientas, instrucción y esquema de salida estructurada pueden conectarse tanto mediante la llamada tradicional a herramientas como mediante CodeAct respaldado por Hyperlight. La única diferencia es la superficie de herramientas: herramientas directas frente a una sola execute_code herramienta respaldada 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",
        ),
    ],
)

En el caso de las cargas de trabajo que calculan los totales en un conjunto de datos mediante la búsqueda repetida de datos y la realización de cálculos ligeros (muchos pasos pequeños y encadenables), CodeAct puede quitar la sobrecarga de orquestación. Cronometre ambas ejecuciones e inspeccione el valor devuelto ChatResponse.usage para comparar el tiempo transcurrido y el uso de tokens en su propio entorno.

Limitaciones actuales

Este paquete sigue siendo alfa y merece la pena planear algunas restricciones:

1. La compatibilidad con la plataforma sigue los paquetes de back-end de Hyperlight publicados. Hoy en día, esto implica entornos de Linux y Windows compatibles; se producirá un error en las plataformas no compatibles al crear el entorno aislado.
2. La integración actual ejecuta código invitado de Python.
3. El estado del intérprete en memoria no se conserva en llamadas independientes execute_code . Utilice archivos montados y /output artefactos cuando los datos deban persistir entre llamadas.
4. La aprobación se aplica a la execute_code invocación en su conjunto, no a cada individuo call_tool(...) dentro del mismo bloque de código.
5. Las descripciones de herramientas, las anotaciones de parámetros y los formatos de retorno son más importantes en este contexto porque el modelo está escribiendo código siguiendo ese contrato en lugar de elegir llamadas directas a herramientas aisladas.