Thanks to visit codestin.com
Credit goes to github.com

Skip to content

.NET: Add Microsoft.Agents.AI.Hyperlight package for CodeAct integration (.NET)#5329

Merged
eavanvalkenburg merged 6 commits into
microsoft:mainfrom
eavanvalkenburg:codeact_dotnet
May 5, 2026
Merged

.NET: Add Microsoft.Agents.AI.Hyperlight package for CodeAct integration (.NET)#5329
eavanvalkenburg merged 6 commits into
microsoft:mainfrom
eavanvalkenburg:codeact_dotnet

Conversation

@eavanvalkenburg

@eavanvalkenburg eavanvalkenburg commented Apr 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Adds a new Microsoft.Agents.AI.Hyperlight package that brings first-class CodeAct support to the .NET Agent Framework, backed by the Hyperlight sandbox via the new .NET SDK from hyperlight-dev/hyperlight-sandbox PR 46.

Follows docs/features/code_act/dotnet-implementation.md and the Python agent_framework_hyperlight reference.

What's included

  • HyperlightCodeActProvider (AIContextProvider):
    • Injects an execute_code tool + CodeAct guidance into every invocation.
    • Single-instance-per-agent enforced via a fixed StateKeys value (ChatClientAgent rejects duplicate state keys).
    • CRUD for provider-owned tools, file mounts, and outbound-domain allow-list — all exposed inside the sandbox via call_tool(...).
    • Run-scoped snapshot captured under a lock so mutations between runs don't affect in-flight executions.
  • HyperlightExecuteCodeFunction: standalone AIFunction for manual/static wiring.
  • Async tool registration end-to-end (Sandbox.RegisterToolAsync).
  • Approval model via CodeActApprovalMode (AlwaysRequire / NeverRequire with propagation from ApprovalRequiredAIFunction-wrapped tools).
  • Both entry points accept options = null and fall back to defaults (mirroring the Python reference).

Tests & samples

  • Unit tests: instruction builder, tool bridge (JSON round-trip + error wrapping + approval unwrap), approval computation matrix, provider CRUD, snapshot isolation, approval wrapping in ProvideAIContextAsync.
  • Integration test: env-gated on HYPERLIGHT_PYTHON_GUEST_PATH, runs print("hi") end-to-end.
  • Three samples under dotnet/samples/02-agents/AgentWithCodeAct/: Interpreter, ToolEnabled (with an ApprovalRequiredAIFunction-wrapped tool), ManualWiring.

Draft — not yet buildable

  • Requires .NET SDK 10.0.200 (per repo global.json).
  • Requires HyperlightSandbox.Api 0.1.0-preview, which is not yet published (hyperlight-dev/hyperlight-sandbox PR 46). The src project is IsPackable=false until the dependency is available.
  • Nothing in this PR has been compiled or run locally yet. Needs to be validated end-to-end once the Hyperlight .NET SDK lands on nuget.org (or a local feed is set up).

Open items to resolve before un-drafting

  • Verify compile on net8.0 / net9.0 / net10.0 against the real SDK.
  • Confirm Sandbox.RegisterToolAsync return-type handling in ToolBridge.RegisterOne.
  • Decide on richer per-mount filesystem API once the Hyperlight SDK exposes one (today, FileMount entries are surfaced only in the execute_code description).
  • Add CHANGELOG entry if required by area owners.

Tracks: CodeAct .NET implementation (see docs/features/code_act/dotnet-implementation.md).

Closes #5188

@moonbox3 moonbox3 added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net labels Apr 17, 2026
@github-actions github-actions Bot changed the title Add Microsoft.Agents.AI.Hyperlight package for CodeAct integration (.NET) .NET: Add Microsoft.Agents.AI.Hyperlight package for CodeAct integration (.NET) Apr 17, 2026
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/AllowedDomain.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProviderOptions.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProviderOptions.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs Outdated
westey-m
westey-m reviewed Apr 17, 2026
View reviewed changes
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs Outdated
@eavanvalkenburg eavanvalkenburg requested a review from Copilot April 17, 2026 15:22
Copilot AI reviewed Apr 17, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new .NET package (Microsoft.Agents.AI.Hyperlight) that integrates Hyperlight-backed CodeAct into the Agent Framework, including an AIContextProvider that injects an execute_code tool plus companion tests and samples.

Changes:

  • Introduces Microsoft.Agents.AI.Hyperlight (provider, options, execute_code function wrapper, internal sandbox executor/tool bridge, and supporting models).
  • Adds unit + integration tests validating instruction/description building, tool bridging, approval behavior, and an env-gated end-to-end sandbox run.
  • Adds three new CodeAct samples and wires them into the .NET solution + samples index.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/ToolBridgeTests.cs Unit coverage for ToolBridge argument passing, error wrapping, and approval unwrap behavior.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/ProvideAIContextTests.cs Validates provider context injection, approval wrapping behavior, and snapshot isolation in tool description.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj Adds new unit test project referencing Hyperlight + core AI projects.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/InstructionBuilderTests.cs Tests CodeAct instruction/description text generation for tools, mounts, and network config.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/HyperlightCodeActProviderTests.cs CRUD + lifecycle tests for provider-owned registries and fixed StateKeys behavior.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/ApprovalComputationTests.cs Tests approval-required computation matrix.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests/Microsoft.Agents.AI.Hyperlight.IntegrationTests.csproj Adds new integration test project referencing Hyperlight.
dotnet/tests/Microsoft.Agents.AI.Hyperlight.IntegrationTests/CodeActEndToEndTests.cs Env-gated end-to-end execute_code run against a real sandbox guest module.
dotnet/src/Microsoft.Agents.AI.Hyperlight/README.md Package-level documentation and requirements/status notes.
dotnet/src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj New multi-targeted Hyperlight integration project and dependencies.
dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ToolBridge.cs Bridges host AIFunctions to sandbox tool callbacks (JSON in/out) and unwraps approval wrappers.
dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/SandboxExecutor.cs Central executor managing sandbox lifecycle and snapshot/restore per invocation.
dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/InstructionBuilder.cs Generates model-facing guidance + execute_code description sections.
dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ExecuteCodeFunction.cs Implements the run-scoped execute_code AIFunction bound to a snapshot + executor.
dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightExecuteCodeFunction.cs Public manual-wiring wrapper for registering execute_code directly.
dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProviderOptions.cs Public options surface for backend/module path/tools/mounts/allow-list/approval mode.
dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightCodeActProvider.cs AIContextProvider that injects execute_code and maintains provider-owned registries with snapshotting.
dotnet/src/Microsoft.Agents.AI.Hyperlight/FileMount.cs Public model for describing host-to-sandbox mounts.
dotnet/src/Microsoft.Agents.AI.Hyperlight/CodeActApprovalMode.cs Public enum controlling approval semantics for execute_code.
dotnet/src/Microsoft.Agents.AI.Hyperlight/AllowedDomain.cs Public model for outbound network allow-list entries.
dotnet/samples/02-agents/README.md Adds the new “AgentWithCodeAct (Hyperlight)” entry to the samples index.
dotnet/samples/02-agents/AgentWithCodeAct/README.md New sample group README describing the three CodeAct sample steps.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/README.md Docs for manual wiring sample configuration and run instructions.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/Program.cs Manual wiring example using HyperlightExecuteCodeFunction.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/AgentWithCodeAct_Step03_ManualWiring.csproj Manual wiring sample project wiring + dependencies.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/README.md Docs for provider-owned tool orchestration + approval-required tool example.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/Program.cs Tool-enabled sample using HyperlightCodeActProvider with provider-owned tools.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/AgentWithCodeAct_Step02_ToolEnabled.csproj Tool-enabled sample project wiring + dependencies.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/README.md Docs for interpreter-only CodeAct sample.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/Program.cs Interpreter mode sample using HyperlightCodeActProvider.
dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/AgentWithCodeAct_Step01_Interpreter.csproj Interpreter sample project wiring + dependencies.
dotnet/agent-framework-dotnet.slnx Adds the new Hyperlight project, tests, and sample projects into the solution structure.
dotnet/Directory.Packages.props Introduces central package version entry for HyperlightSandbox.Api.

Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/ExecuteCodeFunction.cs Outdated
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/HyperlightExecuteCodeFunction.cs Outdated
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/SandboxExecutor.cs
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/InstructionBuilder.cs Outdated
Comment thread dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/InstructionBuilder.cs Outdated
Comment thread ...sts/Microsoft.Agents.AI.Hyperlight.UnitTests/Microsoft.Agents.AI.Hyperlight.UnitTests.csproj Outdated
Comment thread ...Agents.AI.Hyperlight.IntegrationTests/Microsoft.Agents.AI.Hyperlight.IntegrationTests.csproj Outdated
eavanvalkenburg added a commit to eavanvalkenburg/agent-framework that referenced this pull request Apr 20, 2026
@eavanvalkenburg
Address PR microsoft#5329 review feedback for Hyperlight CodeAct prov…
62c9370 
…ider

- A. Build-breakers: drop unused usings, override test TargetFrameworks
  off net472, drop redundant Microsoft.Extensions.AI.Abstractions PackageRef.
- B. API: keep CRUD but rebuild sandbox when config fingerprint changes;
  add HyperlightCodeActProviderOptions.CreateForWasm/CreateForJavaScript
  factory methods (Backend/ModulePath now read-only); rename WorkspaceRoot
  to HostInputDirectory; convert AllowedDomain & FileMount from record to
  sealed class; drop ToolBridge.Unwrap (ApprovalRequiredAIFunction is
  invocable as-is).
- C. ToolBridge: collapse SerializeResult switch; add comment explaining
  AOT-driven choice to keep JsonNode.Parse over typed Deserialize.
- D. InstructionBuilder: drop language-specific 'Python code' phrasing;
  strip host filesystem paths from execute_code description.
- E. Style polish: ternary expression-body for ComputeApprovalRequired,
  .Where(x is not null), .ToList() over .ToArray() in IReadOnlyList
  returns.
- F. Samples: add guest-module / KVM-WHP build instructions to Step01;
  note future Excel-upload sample in Step02.

Also adds SandboxExecutorTests covering the new RunSnapshot.ComputeFingerprint
used for sandbox-rebuild detection.

Co-authored-by: Copilot <[email protected]>
This was referenced Jun 4, 2026
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
This was referenced Jun 11, 2026
Open
Open
Closed
Closed
Closed
Closed
Closed
This was referenced Jun 24, 2026
Closed
Closed
Open
Closed
Closed
@eavanvalkenburg eavanvalkenburg deleted the codeact_dotnet branch June 30, 2026 09:01
This was referenced Jul 1, 2026
Open
Open
Closed
Open
@dependabot dependabot Bot mentioned this pull request Jul 8, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actions github-actions[bot] github-actions[bot] left review comments
Copilot code review Copilot Copilot left review comments
@SergeyMenshykh SergeyMenshykh SergeyMenshykh approved these changes
@westey-m westey-m westey-m approved these changes
+1 more reviewer
@Vijay-Nirmal Vijay-Nirmal Vijay-Nirmal left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs .NET Usage: [Issues, PRs], Target: .Net

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

.NET: [Feature]: .NET CodeAct implementation

6 participants

@eavanvalkenburg @Vijay-Nirmal @SergeyMenshykh @westey-m @moonbox3