Hyperlight CodeAct

Empieza ahora

Próximamente.

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.

async def main() -> None:
    """Run the provider-owned Hyperlight CodeAct sample."""
    # 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],
        middleware=[log_function_calls],
    )

    # 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."
    )
    print(f"{_CYAN}{'=' * 60}")
    print("Hyperlight CodeAct provider sample")
    print(f"{'=' * 60}{_RESET}")
    print(f"{_CYAN}User: {query}{_RESET}")
    result = await agent.run(query)
    print(f"{_CYAN}Agent: {result.text}{_RESET}")

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

El ejemplo de prueba comparativa ejecuta la misma tarea con el mismo cliente, modelo, herramientas, solicitud y esquema de salida estructurado una vez a través de una llamada a herramientas tradicional y una vez a través de CodeAct respaldado por Hyperlight. La única diferencia es el cableado: herramientas directas frente a una sola execute_code herramienta respaldada por HyperlightCodeActProvider.

async def _run_traditional() -> tuple[float, AgentResponse]:
    agent = Agent(
        client=get_client(),
        name="TraditionalAgent",
        instructions=INSTRUCTIONS,
        tools=TOOLS,
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result


async def _run_codeact() -> tuple[float, AgentResponse]:
    codeact = HyperlightCodeActProvider(
        tools=TOOLS,
        approval_mode="never_require",
    )
    agent = Agent(
        client=get_client(),
        name="CodeActAgent",
        instructions=INSTRUCTIONS,
        context_providers=[codeact],
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result

En ese ejemplo, el agente calcula los totales generales en un conjunto de datos de usuarios y pedidos mediante la búsqueda repetida de datos y la realización de cálculos ligeros. Es exactamente el tipo de flujo de trabajo de varios pasos pequeños en el que CodeAct puede quitar la sobrecarga de orquestación. El ejemplo completo imprime el tiempo transcurrido y el uso de tokens para ambas ejecuciones para poder comparar la forma de ejecución 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. La documentación de .NET todavía estará disponible próximamente.
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.