Python: Add Hyperlight CodeAct package and docs

.github/workflows/python-integration-tests.yml

@@ -131,7 +131,7 @@ jobs:
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
 
-  # Misc integration tests (Anthropic, Ollama, MCP)
+  # Misc integration tests (Anthropic, Hyperlight, Ollama, MCP)
   python-tests-misc-integration:
     name: Python Integration Tests - Misc
     runs-on: ubuntu-latest
@@ -162,10 +162,11 @@ jobs:
           fallback_url: ${{ env.LOCAL_MCP_URL }}
       - name: Prefer local MCP URL when available
         run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
           packages/anthropic/tests
+          packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
           -m integration

.github/workflows/python-merge-tests.yml

@@ -65,6 +65,7 @@ jobs:
               - 'python/samples/**/providers/azure/**'
             misc:
               - 'python/packages/anthropic/**'
+              - 'python/packages/hyperlight/**'
               - 'python/packages/ollama/**'
               - 'python/packages/core/agent_framework/_mcp.py'
               - 'python/packages/core/tests/core/test_mcp.py'
@@ -278,10 +279,11 @@ jobs:
           fallback_url: ${{ env.LOCAL_MCP_URL }}
       - name: Prefer local MCP URL when available
         run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
           packages/anthropic/tests
+          packages/hyperlight/tests
           packages/ollama/tests
           packages/core/tests/core/test_mcp.py
           -m integration

python/.cspell.json

@@ -30,6 +30,7 @@
         "azuredocs",
         "azurefunctions",
         "boto",
+        "codeact",
         "contentvector",
         "contoso",
         "datamodel",
@@ -45,6 +46,7 @@
         "hnsw",
         "httpx",
         "huggingface",
+        "hyperlight",
         "Instrumentor",
         "logit",
         "logprobs",

python/PACKAGE_STATUS.md

@@ -33,6 +33,7 @@ Status is grouped into these buckets:
 | `agent-framework-foundry-local` | `python/packages/foundry_local` | `beta` |
 | `agent-framework-gemini` | `python/packages/gemini` | `alpha` |
 | `agent-framework-github-copilot` | `python/packages/github_copilot` | `beta` |
+| `agent-framework-hyperlight` | `python/packages/hyperlight` | `alpha` |
 | `agent-framework-lab` | `python/packages/lab` | `beta` |
 | `agent-framework-mem0` | `python/packages/mem0` | `beta` |
 | `agent-framework-ollama` | `python/packages/ollama` | `beta` |

python/packages/core/agent_framework/_tools.py

@@ -89,6 +89,7 @@
 DEFAULT_MAX_ITERATIONS: Final[int] = 40
 DEFAULT_MAX_CONSECUTIVE_ERRORS_PER_REQUEST: Final[int] = 3
 SHELL_TOOL_KIND_VALUE: Final[str] = "shell"
+ApprovalMode: TypeAlias = Literal["always_require", "never_require"]
 ChatClientT = TypeVar("ChatClientT", bound="SupportsChatGetResponse[Any]")
 ResponseModelBoundT = TypeVar("ResponseModelBoundT", bound=BaseModel)
 
@@ -270,7 +271,7 @@ def __init__(
         *,
         name: str,
         description: str = "",
-        approval_mode: Literal["always_require", "never_require"] | None = None,
+        approval_mode: ApprovalMode | None = None,
         kind: str | None = None,
         max_invocations: int | None = None,
         max_invocation_exceptions: int | None = None,
@@ -1030,7 +1031,7 @@ def tool(
     name: str | None = None,
     description: str | None = None,
     schema: type[BaseModel] | Mapping[str, Any] | None = None,
-    approval_mode: Literal["always_require", "never_require"] | None = None,
+    approval_mode: ApprovalMode | None = None,
     kind: str | None = None,
     max_invocations: int | None = None,
     max_invocation_exceptions: int | None = None,
@@ -1046,7 +1047,7 @@ def tool(
     name: str | None = None,
     description: str | None = None,
     schema: type[BaseModel] | Mapping[str, Any] | None = None,
-    approval_mode: Literal["always_require", "never_require"] | None = None,
+    approval_mode: ApprovalMode | None = None,
     kind: str | None = None,
     max_invocations: int | None = None,
     max_invocation_exceptions: int | None = None,
@@ -1061,7 +1062,7 @@ def tool(
     name: str | None = None,
     description: str | None = None,
     schema: type[BaseModel] | Mapping[str, Any] | None = None,
-    approval_mode: Literal["always_require", "never_require"] | None = None,
+    approval_mode: ApprovalMode | None = None,
     kind: str | None = None,
     max_invocations: int | None = None,
     max_invocation_exceptions: int | None = None,

python/packages/hyperlight/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/hyperlight/README.md

@@ -0,0 +1,132 @@
+# agent-framework-hyperlight
+
+Alpha 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. If the backend is not published for
+your current platform yet, `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
+    ],
+)
+```
+
+## Notes
+
+- This package is intentionally separate from `agent-framework-core` so CodeAct
+  usage and installation remain optional.
+- Alpha-package samples live under `packages/hyperlight/samples/`.
+- `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.

python/packages/hyperlight/agent_framework_hyperlight/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from ._execute_code_tool import HyperlightExecuteCodeTool
+from ._provider import HyperlightCodeActProvider
+from ._types import AllowedDomain, AllowedDomainInput, FileMount, FileMountInput
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AllowedDomain",
+    "AllowedDomainInput",
+    "FileMount",
+    "FileMountInput",
+    "HyperlightCodeActProvider",
+    "HyperlightExecuteCodeTool",
+    "__version__",
+]