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

[Eduard van Valkenburg (eavanvalkenburg)]

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

[Copilot]

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.