Python: Add Hyperlight CodeAct package and docs by eavanvalkenburg · Pull Request #5185 · microsoft/agent-framework

eavanvalkenburg · 2026-04-09T14:00:42Z

Motivation and Context

Add a concrete, optional CodeAct implementation for Python and capture the cross-SDK design for CodeAct with Hyperlight. This provides a reusable path for long-running agents to execute sandboxed code with provider-owned tools, file mounts, and network allow-lists without baking CodeAct into core.

Description

add ADR 0024 plus Python feature design notes for the CodeAct and Hyperlight design
introduce the alpha agent-framework-hyperlight package with HyperlightCodeActProvider and HyperlightExecuteCodeTool
add provider-managed tool, file, and network CRUD; derived approval behavior; serializable provider state; and Hyperlight-backed execution results
move the CodeAct samples into the new package and update workspace/package metadata
add unit coverage, a guarded real-sandbox integration test, and wire Hyperlight into the Python misc integration workflow

Closes: #5187

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

Copilot

Pull request overview

Adds an optional Python Hyperlight-backed CodeAct implementation plus cross-SDK design documentation, and wires the new package into the Python workspace and CI.

Changes:

Introduces the new agent-framework-hyperlight alpha package (provider + execute_code tool), including samples and tests.
Updates agent-framework-core to let context providers inspect/override per-run runtime tools via SessionContext.options["tools"].
Adds ADR/design docs for CodeAct and updates Python CI workflows to include Hyperlight integration coverage.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
python/uv.lock	Adds Hyperlight package + Hyperlight sandbox deps; updates a few dependency markers.
python/pyproject.toml	Registers `agent-framework-hyperlight` in the Python workspace.
python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py	Adds unit coverage + guarded real-sandbox integration test.
python/packages/hyperlight/samples/README.md	Documents how to run the new Hyperlight samples.
python/packages/hyperlight/samples/codeact_tool.py	Standalone `HyperlightExecuteCodeTool` sample.
python/packages/hyperlight/samples/codeact_context_provider.py	Provider-owned CodeAct sample using `HyperlightCodeActProvider`.
python/packages/hyperlight/README.md	Package-level README for installation and public API.
python/packages/hyperlight/pyproject.toml	New package metadata, deps, and tooling config.
python/packages/hyperlight/LICENSE	Adds MIT license for the new package.
python/packages/hyperlight/agent_framework_hyperlight/_types.py	Adds public types (`FileMount`, `FilesystemMode`, `NetworkMode`).
python/packages/hyperlight/agent_framework_hyperlight/_provider.py	Implements `HyperlightCodeActProvider` context provider.
python/packages/hyperlight/agent_framework_hyperlight/_instructions.py	Builds dynamic CodeAct instructions and tool descriptions.
python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py	Implements sandbox execution, caching, CRUD registries for tools/files/network.
python/packages/hyperlight/agent_framework_hyperlight/init.py	Exposes public API + version metadata.
python/packages/core/tests/core/test_agents.py	Adds tests validating providers can inspect/remove runtime tools.
python/packages/core/agent_framework/_tools.py	Introduces `ApprovalMode` type alias and updates signatures.
python/packages/core/agent_framework/_sessions.py	Updates docs to reflect provider mutability of `options["tools"]`.
python/packages/core/agent_framework/_agents.py	Passes runtime tools via `SessionContext.options` and resolves tools from provider-mutated options.
python/PACKAGE_STATUS.md	Adds `agent-framework-hyperlight` as `alpha`.
python/.cspell.json	Adds `codeact` and `hyperlight` to dictionary.
docs/features/code_act/python-implementation.md	Adds Python-specific CodeAct design notes and API contract.
docs/features/code_act/dotnet-implementation.md	Adds placeholder for .NET CodeAct implementation notes.
docs/decisions/0024-codeact-integration.md	Adds ADR covering cross-SDK CodeAct integration approach and approval model.
.github/workflows/python-merge-tests.yml	Includes Hyperlight tests in “misc integration” selection.
.github/workflows/python-integration-tests.yml	Includes Hyperlight tests in “misc integration” job.

python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py

python/packages/hyperlight/pyproject.toml

docs/features/code_act/python-implementation.md

docs/decisions/0024-codeact-integration.md

python/packages/core/agent_framework/_agents.py

moonbox3 · 2026-04-09T14:22:08Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	415	52	87%	461, 470, 525, 1020, 1065, 1138–1142, 1205, 1233, 1270, 1291, 1311–1312, 1317, 1364, 1406, 1428, 1430, 1443, 1449, 1494, 1496, 1505–1510, 1515, 1517, 1523–1524, 1531, 1533–1534, 1542–1543, 1546–1548, 1558–1563, 1567, 1572, 1574
_sessions.py	273	30	89%	82–84, 86–89, 106–107, 109–113, 192–193, 283, 544–548, 590, 593, 627, 676, 680, 690, 823, 839
_tools.py	948	87	90%	191–192, 365, 367, 380, 405–407, 415, 433, 447, 454, 461, 484, 486, 493, 501, 540, 584, 588, 620–622, 630, 675–677, 679, 702, 728, 732, 770–772, 776, 798, 910–916, 952, 964, 966, 968, 971–974, 995, 999, 1003, 1017–1019, 1360, 1382, 1469–1475, 1604, 1608, 1654, 1715–1716, 1831, 1851, 1853, 1909, 1972, 2144–2145, 2165, 2221–2222, 2282, 2360–2361, 2428, 2433, 2440
packages/hyperlight/agent_framework_hyperlight
_execute_code_tool.py	449	75	83%	63, 99–100, 119, 121, 134, 152, 162, 187, 192, 199, 205, 213, 221–223, 225–230, 270, 275, 277, 279, 296–297, 306–309, 336–339, 345, 347, 357–358, 390–391, 394–395, 402, 430, 458–459, 462, 466, 512–513, 539, 602, 638, 644–646, 675–679, 683–684, 689, 706–710, 714–715, 771–772
_instructions.py	44	5	88%	14, 33, 45–46, 56
_provider.py	42	11	73%	53, 57, 65, 69, 73, 77, 81, 85, 89, 93, 97
_types.py	13	0	100%
TOTAL	28096	3289	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5588	22 💤	0 ❌	0 🔥	1m 33s ⏱️

moonbox3

This is a nice and complete ADR - well done. A lot here to unpack so doing a first pass with some questions.

docs/decisions/0024-codeact-integration.md

Co-authored-by: Copilot <[email protected]>

Enable the sandbox filesystem by providing a workspace_root so /output is mounted. Remove os.path.exists assertion (unsupported in WASM guest) and fix Content data assertion to use .uri. Skip the network integration test on Windows where the WASM sandbox lacks the encodings.idna codec. Co-authored-by: Copilot <[email protected]>

TaoChenOSU · 2026-04-14T15:47:10Z

docs/decisions/0024-codeact-integration.md

+
+## Context and Problem Statement
+
+We need an architecture design that supports CodeAct in both Python and .NET. This is a necessary capability for the current generation of long-running agents, which need to plan, iterate, transform tool outputs, and execute bounded code inside a controlled runtime instead of pushing every intermediate step back through the model. The design should preserve the same behavioral contract across SDKs, but it does not need to use the same internal extension point in each runtime. We also want to standardize on Hyperlight as the initial backend, using the existing Python package and an anticipated .NET binding package once it is available.


instead of pushing every intermediate step back through the model

Could we elaborate on what this means?

Also an introduction of CodeAct will greatly help readers of this doc.

TaoChenOSU · 2026-04-14T16:39:14Z

docs/decisions/0024-codeact-integration.md

+- Good, because a provider-owned CodeAct tool registry avoids mutating or inferring the agent's direct tool surface and can work consistently in both SDKs.
+- Good, because the same conceptual design can remain open to `HyperlightCodeActProvider`, a future `MontyCodeActProvider`, and other backend-specific providers over time.
+- Good, because `execute_code` can evolve into multiple backend-specific runtime modes rather than being hard-wired to one Python-plus-tools mode.
+- Bad, because it is a bolt-on, which might make it less runtime efficient.


make it less runtime efficient
Why will a bolt-on make it less efficient?

TaoChenOSU · 2026-04-14T16:45:01Z

docs/features/code_act/python-implementation.md

+
+## What is the problem being solved?
+
+- Today, the easiest way to prototype CodeAct is to infer or reshape the agent's direct tool surface, which is fragile and hard to reason about.


Should this be part of the ADR instead?

TaoChenOSU · 2026-04-14T16:54:57Z

docs/features/code_act/python-implementation.md

+- snapshotting the current CodeAct-managed tool registry and capability settings for the run,
+- computing the effective approval requirement for `execute_code` from the provider default and the snapshotted tool registry,
+- adding a short CodeAct guidance block,
+- adding `execute_code` to the run through `SessionContext.extend_tools(...)`,
+- and wiring any backend-specific execution state needed for the run.


Are these required for each run? Can these be done once at construction time which will inject the available tools to the agent's tool list?

TaoChenOSU · 2026-04-14T17:07:13Z

docs/features/code_act/python-implementation.md

+    client=client,
+    name="assistant",
+    tools=[send_email],  # direct-only tool
+    context_providers=[codeact],


Looking at this, a question that users may have is that is the difference between tools and contexts?

Just an idea: is it possible to do the following

agent = Agent( client=client, name="assistant", tools=[send_email, *codeact.get_tools()], )

where the returned tools have a reference to the provider so that that can access the file mounts, allowed domains, etc?

TaoChenOSU · 2026-04-14T17:08:50Z

docs/features/code_act/python-implementation.md

+agent = Agent(
+    client=client,
+    name="interpreter",
+    context_providers=[code_interpreter],


Adding to the previous comment, code_interpreter is reusing an existing concept whose usage is very different.

TaoChenOSU · 2026-04-14T17:24:11Z

python/packages/hyperlight/samples/README.md

+- `codeact_context_provider.py` shows the provider-owned CodeAct model where the
+  agent only sees `execute_code` and sandbox tools are owned by
+  `HyperlightCodeActProvider`.
+- `codeact_tool.py` shows the standalone `HyperlightExecuteCodeTool` surface
+  where `execute_code` is added directly to the agent tool list.


A short paragraph on when to use what will be helpful for customers.

Copilot AI review requested due to automatic review settings April 9, 2026 14:00

moonbox3 added documentation Improvements or additions to documentation python labels Apr 9, 2026

Copilot started reviewing on behalf of eavanvalkenburg April 9, 2026 14:01 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

eavanvalkenburg force-pushed the code_mode branch from a2f85f8 to 4c6f7da Compare April 10, 2026 06:50

moonbox3 reviewed Apr 10, 2026

View reviewed changes

eavanvalkenburg force-pushed the code_mode branch 2 times, most recently from b309856 to fe24c4f Compare April 14, 2026 07:27

eavanvalkenburg and others added 20 commits April 14, 2026 13:36

initial work on code_mode

a241a42

updated samples

492401d

updates to codeact

9f8eada

udpated codeact

988d4a9

Draft CodeAct ADR and sample updates

ec16c12

Co-authored-by: Copilot <[email protected]>

initial implementation and adr and feature

3d168ff

Python: Limit Hyperlight wasm backend to Python <3.14

8dddecc

Co-authored-by: Copilot <[email protected]>

Python: Fix CI for Hyperlight CodeAct PR

8d70aff

Co-authored-by: Copilot <[email protected]>

Python: Run Hyperlight integration when available

4f77938

Co-authored-by: Copilot <[email protected]>

Python: Address Hyperlight review feedback

d959537

Co-authored-by: Copilot <[email protected]>

Python: Simplify Hyperlight file mount inputs

779ff14

Co-authored-by: Copilot <[email protected]>

Python: Accept Path host paths in Hyperlight mounts

003b5f2

Co-authored-by: Copilot <[email protected]>

Python: Fix Hyperlight mount typing for CI

e296d61

Co-authored-by: Copilot <[email protected]>

temp run integration test

66e5028

Python: Strengthen Hyperlight real sandbox tests

f880d2c

Co-authored-by: Copilot <[email protected]>

added additional tests

f5cb9ea

Python: Simplify Hyperlight CodeAct API

1763ebf

Co-authored-by: Copilot <[email protected]>

set tests as non-integration

07d0b9e

Retry Hyperlight allowed-domain registration

83fe46d

Co-authored-by: Copilot <[email protected]>

Gate Hyperlight integration tests by runtime support

bbb8416

Co-authored-by: Copilot <[email protected]>

eavanvalkenburg and others added 12 commits April 14, 2026 13:37

Fix Hyperlight skip test on Python 3.14

c055acd

Co-authored-by: Copilot <[email protected]>

Delay Hyperlight runtime probe until test execution

85d8e7f

Co-authored-by: Copilot <[email protected]>

Relax Hyperlight Windows integration stdout assertion

2380fc8

Co-authored-by: Copilot <[email protected]>

Scan Hyperlight output directory for artifacts

bf56d12

Co-authored-by: Copilot <[email protected]>

Retry Hyperlight output artifact collection

7cf4091

Co-authored-by: Copilot <[email protected]>

Harden Hyperlight integration output assertions

771d763

Co-authored-by: Copilot <[email protected]>

Retry Hyperlight read-back check in integration test

9f99e03

Co-authored-by: Copilot <[email protected]>

Simplify Hyperlight integration write assertion

21615b6

Co-authored-by: Copilot <[email protected]>

Avoid pathlib in Hyperlight integration sandbox

2d9544b

Co-authored-by: Copilot <[email protected]>

Use socket network check in Hyperlight sandbox

582bf97

Co-authored-by: Copilot <[email protected]>

Replace blocked Azure AI Search blog link

be61f6f

Co-authored-by: Copilot <[email protected]>

Clarify Hyperlight guest stdlib limits

54f1b3a

Co-authored-by: Copilot <[email protected]>

eavanvalkenburg force-pushed the code_mode branch from dd05f42 to 54f1b3a Compare April 14, 2026 11:37

eavanvalkenburg and others added 7 commits April 14, 2026 14:02

Use _socket in Hyperlight integration sandbox

d25bf1f

Co-authored-by: Copilot <[email protected]>

Handle Hyperlight mounted file paths

7cf71c2

Co-authored-by: Copilot <[email protected]>

Broaden Hyperlight sandbox path fallbacks

dafdd21

Co-authored-by: Copilot <[email protected]>

Search Hyperlight guest mounts recursively

55f7403

Co-authored-by: Copilot <[email protected]>

Split Hyperlight mount coverage

32244b1

Co-authored-by: Copilot <[email protected]>

Split Hyperlight live network tests

92eaad2

Co-authored-by: Copilot <[email protected]>

TaoChenOSU reviewed Apr 14, 2026

View reviewed changes


		## Context and Problem Statement

		We need an architecture design that supports CodeAct in both Python and .NET. This is a necessary capability for the current generation of long-running agents, which need to plan, iterate, transform tool outputs, and execute bounded code inside a controlled runtime instead of pushing every intermediate step back through the model. The design should preserve the same behavioral contract across SDKs, but it does not need to use the same internal extension point in each runtime. We also want to standardize on Hyperlight as the initial backend, using the existing Python package and an anticipated .NET binding package once it is available.


		## What is the problem being solved?

		- Today, the easiest way to prototype CodeAct is to infer or reshape the agent's direct tool surface, which is fragile and hard to reason about.

Conversation

eavanvalkenburg commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

moonbox3 commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

moonbox3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

eavanvalkenburg commented Apr 9, 2026 •

edited

Loading

moonbox3 commented Apr 9, 2026 •

edited

Loading