Metadata-Version: 2.4
Name: agent-framework-hyperlight
Version: 1.0.0b260918
Summary: Hyperlight CodeAct integrations for Microsoft Agent Framework.
Author-email: Microsoft <af-support@microsoft.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: agent-framework-core>=1.19.0,<2
Requires-Dist: hyperlight-sandbox>=0.7.0,<0.8
Requires-Dist: hyperlight-sandbox-backend-wasm>=0.7.0,<0.8 ; python_version < '3.15' and ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
Requires-Dist: hyperlight-sandbox-python-guest>=0.7.0,<0.8
Project-URL: homepage, https://aka.ms/agent-framework
Project-URL: issues, https://github.com/microsoft/agent-framework/issues
Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python

# agent-framework-hyperlight

Hyperlight-backed CodeAct integrations for Microsoft Agent Framework.

## Installation

```bash
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.

```python
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.

```python
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:

```python
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:

```python
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:

```python
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`:

```python
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.

