agent-framework-hyperlight

Hyperlight-backed CodeAct integrations for Microsoft Agent Framework.

Installation

pip install agent-framework-hyperlight --pre

This package depends on hyperlight-sandbox, the packaged Python guest, and the Wasm backend package on supported platforms. The backend is currently installed for Python 3.10 through 3.14. If a compatible backend is not published for your current platform and Python version, execute_code will fail at runtime when it tries to create the sandbox.

Quick start

Context provider (recommended)

Use HyperlightCodeActProvider to automatically inject the execute_code tool and CodeAct instructions into every agent run. Tools registered on the provider are available inside the sandbox via call_tool(...) but are not exposed as direct agent tools.

from agent_framework import Agent, tool
from agent_framework_hyperlight import HyperlightCodeActProvider

@tool
def compute(operation: str, a: float, b: float) -> float:
    """Perform a math operation."""
    ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b}
    return ops[operation]

codeact = HyperlightCodeActProvider(
    tools=[compute],
    approval_mode="never_require",
)

agent = Agent(
    client=client,
    name="CodeActAgent",
    instructions="You are a helpful assistant.",
    context_providers=[codeact],
)

result = await agent.run("Multiply 6 by 7 using execute_code.")

Standalone tool

Use HyperlightExecuteCodeTool directly when you want full control over how the tool is added to the agent. This is useful when mixing sandbox tools with direct-only tools on the same agent.

from agent_framework import Agent, tool
from agent_framework_hyperlight import HyperlightExecuteCodeTool

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email (direct-only, not available inside the sandbox)."""
    return f"Email sent to {to}"

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    approval_mode="never_require",
)

agent = Agent(
    client=client,
    name="MixedToolsAgent",
    instructions="You are a helpful assistant.",
    tools=[send_email, execute_code],
)

Manual static wiring

For fixed configurations where provider lifecycle overhead is unnecessary, build the CodeAct instructions once and pass them to the agent at construction time:

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    approval_mode="never_require",
)

codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)

agent = Agent(
    client=client,
    name="StaticWiringAgent",
    instructions=f"You are a helpful assistant.\n\n{codeact_instructions}",
    tools=[execute_code],
)

File mounts and network access

Mount host directories into the sandbox and allow outbound HTTP to specific domains:

from agent_framework_hyperlight import HyperlightCodeActProvider, FileMount

codeact = HyperlightCodeActProvider(
    tools=[compute],
    file_mounts=[
        "/host/data",                                 # shorthand — same path in sandbox
        ("/host/models", "/sandbox/models"),           # explicit host → sandbox mapping
        FileMount("/host/config", "/sandbox/config"),  # named tuple
    ],
    allowed_domains=[
        "api.github.com",                             # all methods
        ("internal.api.example.com", "GET"),           # GET only
    ],
)

Sandbox tool parameter descriptions

Both HyperlightExecuteCodeTool and HyperlightCodeActProvider accept the keyword-only tool_description_format option. The default, "compact", includes each parameter's scalar type, required/optional status, description, enum values, and default when present. Use "json" to include the complete JSON Schema:

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    tool_description_format="json",
)

codeact = HyperlightCodeActProvider(
    tools=[compute],
    tool_description_format={"compute": "json", "send_email": "compact"},
)

A string applies to every registered tool. A mapping selects formats by exact, case-sensitive tool name; missing names use "compact". Mappings are copied at construction and when creating run-scoped tools, and entries for unregistered tools are retained for later registration.

Compact mode automatically falls back to full JSON Schema, with an explanatory note, when a schema cannot be represented faithfully (for example, nested objects, arrays, references, or additional constraints). No schema details are discarded. Only "compact" and "json" are accepted; None is not supported.

Tool parameter schemas are model-visible metadata, just as they are for direct function calling. Do not put credentials, tenant identifiers, or other secrets in parameter descriptions, enum values, defaults, or custom schema fields.

This option affects HyperlightExecuteCodeTool.description, or the injected run tool's .description when using HyperlightCodeActProvider. It does not change the short CodeAct instructions, the execute_code input schema, sandbox execution, or runtime caching.

Output attachment limits

Files written under /output are returned as inline data attachments. Hyperlight limits each invocation to 20 files, 5 MiB per file, and 20 MiB of cumulative raw file data by default. Oversized output is returned as a structured execution error without partial data attachments. Output discovery also has finite internal entry and nesting-depth safeguards; directory-heavy output that exceeds them is rejected as an execution error.

Trusted applications can raise these limits with positive integers on either HyperlightExecuteCodeTool or HyperlightCodeActProvider:

codeact = HyperlightCodeActProvider(
    workspace_root="./workspace",
    max_output_files=40,
    max_output_file_bytes=10 * 1024 * 1024,
    max_output_total_bytes=50 * 1024 * 1024,
)

Limits are always finite. Increasing them also increases host memory use because file data is encoded as inline base64, and may increase model context cost when attachments are included in subsequent requests.

Nested output paths require secure directory-relative file opening. On platforms without that capability, nested attachments fail closed; write attachment files directly under /output for portable behavior.

Notes

• This package is intentionally separate from agent-framework-core so CodeAct usage and installation remain optional. With agent-framework-core[all] (or the meta agent-framework) installed it is also reachable through the lazy-loading namespace agent_framework.hyperlight.
• file_mounts accepts a single string shorthand, an explicit (host_path, mount_path) pair, or a FileMount named tuple. The host-side path in the explicit forms may be a str or Path. Use the explicit two-value form when the host path differs from the sandbox path.
• allowed_domains accepts a single string target such as "github.com" to allow all backend-supported methods, an explicit (target, method_or_methods) tuple such as ("github.com", "GET"), or an AllowedDomain named tuple.
• Tools registered with the sandbox return their native Python value (dict, list, primitives, or custom objects) directly to the guest via the Hyperlight FFI. Any result_parser configured on a FunctionTool is intended for LLM-facing consumers and does not run on the sandbox path — apply formatting inside the tool function itself if you need it for in-sandbox consumers.