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

docs/features/code_act/dotnet-implementation.md

@@ -0,0 +1,6 @@
+# CodeAct .NET implementation
+
+This document will describe the .NET realization of the CodeAct design in
+[`docs/decisions/0024-codeact-integration.md`](../../decisions/0024-codeact-integration.md).
+
+Coming soon.

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

@@ -32,6 +32,7 @@ Status is grouped into these buckets:
 | `agent-framework-foundry` | `python/packages/foundry` | `released` |
 | `agent-framework-foundry-local` | `python/packages/foundry_local` | `beta` |
 | `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/_agents.py

@@ -1191,11 +1191,14 @@ async def _prepare_run_context(
             options=opts,
             service_stores_history=bool(store_),
         )
+        provider_options = dict(opts)
+        if tools_ is not None:
+            provider_options["tools"] = tools_
 
         session_context, chat_options = await self._prepare_session_and_messages(
             session=active_session,
             input_messages=input_messages,
-            options=opts,
+            options=provider_options,
         )
         default_additional_args = chat_options.pop("additional_function_arguments", None)
         if isinstance(default_additional_args, Mapping):
@@ -1209,7 +1212,7 @@ async def _prepare_run_context(
         mcp_duplicate_message = "Tool names must be unique. Consider setting `tool_name_prefix` on the MCPTool."
 
         # Normalize tools
-        normalized_tools = normalize_tools(tools_)
+        normalized_tools = normalize_tools(session_context.options.get("tools", tools_))
 
         # Resolve final tool list (configured tools + runtime provided tools + local MCP server tools)
         final_tools = list(base_tools)

python/packages/core/agent_framework/_sessions.py

@@ -149,7 +149,8 @@ class SessionContext:
         middleware: Dict mapping source_id -> chat/function middleware added by that provider.
             Maintains insertion order (provider execution order).
         response: After invocation, contains the full AgentResponse, should not be changed.
-        options: Options passed to agent.run() - read-only, for reflection only.
+        options: Options passed to agent.run(). Providers can inspect these and may
+            update ``options["tools"]`` to influence per-run tool resolution.
         metadata: Shared metadata dictionary for cross-provider communication.
     """
 
@@ -176,7 +177,8 @@ def __init__(
             instructions: Pre-populated instructions.
             tools: Pre-populated tools.
             middleware: Pre-populated chat/function middleware by source.
-            options: Options from agent.run() - read-only for providers.
+            options: Options from agent.run(). Providers may inspect these and can
+                update ``options["tools"]`` to influence per-run tool resolution.
             metadata: Shared metadata for cross-provider communication.
         """
         self.session_id = session_id

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/core/tests/core/test_agents.py

@@ -841,6 +841,67 @@ async def test_per_service_call_persistence_rejects_existing_conversation_id_whe
         await agent.run("Hello", session=session, options={"store": False, "conversation_id": "existing_conversation"})
 
 
+async def test_context_provider_can_inspect_runtime_tools_from_run(
+    chat_client_base: SupportsChatGetResponse,
+) -> None:
+    seen_tools: list[Any] = []
+
+    class RuntimeToolsProvider(ContextProvider):
+        def __init__(self) -> None:
+            super().__init__(source_id="runtime-tools")
+
+        async def before_run(self, *, agent: Any, session: Any, context: Any, state: Any) -> None:
+            del agent, session, state
+            tools = context.options.get("tools", [])
+            seen_tools.extend(list(tools) if isinstance(tools, list) else [tools])
+
+    runtime_tool = FunctionTool(func=lambda: "runtime", name="runtime_tool", description="Runtime tool")
+    agent = Agent(client=chat_client_base, context_providers=[RuntimeToolsProvider()])
+
+    await agent._prepare_run_context(  # type: ignore[reportPrivateUsage]
+        messages="Hello",
+        session=agent.create_session(),
+        tools=[runtime_tool],
+        options=None,
+        compaction_strategy=None,
+        tokenizer=None,
+        function_invocation_kwargs=None,
+        client_kwargs=None,
+    )
+
+    assert seen_tools == [runtime_tool]
+
+
+async def test_context_provider_can_remove_runtime_tools_from_run(
+    chat_client_base: SupportsChatGetResponse,
+) -> None:
+    class RuntimeToolsProvider(ContextProvider):
+        def __init__(self) -> None:
+            super().__init__(source_id="runtime-tools")
+
+        async def before_run(self, *, agent: Any, session: Any, context: Any, state: Any) -> None:
+            del agent, session, state
+            context.options["tools"] = []
+
+    base_tool = FunctionTool(func=lambda: "base", name="base_tool", description="Base tool")
+    runtime_tool = FunctionTool(func=lambda: "runtime", name="runtime_tool", description="Runtime tool")
+    agent = Agent(client=chat_client_base, tools=[base_tool], context_providers=[RuntimeToolsProvider()])
+
+    ctx = await agent._prepare_run_context(  # type: ignore[reportPrivateUsage]
+        messages="Hello",
+        session=agent.create_session(),
+        tools=[runtime_tool],
+        options=None,
+        compaction_strategy=None,
+        tokenizer=None,
+        function_invocation_kwargs=None,
+        client_kwargs=None,
+    )
+
+    tool_names = [_get_tool_name(tool_obj) for tool_obj in ctx["chat_options"]["tools"]]
+    assert tool_names == ["base_tool"]
+
+
 async def test_chat_client_agent_run_with_session(chat_client_base: SupportsChatGetResponse) -> None:
     mock_response = ChatResponse(
         messages=[Message(role="assistant", contents=[Content.from_text("test response")])],

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,36 @@
+# 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.
+
+## Public API
+
+- `AllowedDomain`
+- `AllowedDomainInput`
+- `HyperlightCodeActProvider`
+- `HyperlightExecuteCodeTool`
+- `FileMount`
+- `FileMountInput`
+
+## 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__",
+]