mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

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

* Add Microsoft.Agents.AI.Hyperlight package for CodeAct integration

Introduces a new Microsoft.Agents.AI.Hyperlight package that enables CodeAct-style sandboxed code execution via Hyperlight (hyperlight-sandbox .NET SDK, PR #46) for .NET agents, following the docs/features/code_act/dotnet-implementation.md design and the Python agent_framework_hyperlight reference.

Highlights:
- HyperlightCodeActProvider (AIContextProvider): injects an execute_code tool and CodeAct guidance per invocation; single-instance-per-agent via a fixed StateKeys value; supports multiple provider-owned tools (exposed inside the sandbox via call_tool), file mounts, and an outbound domain allow-list; snapshot/restore per run.
- HyperlightExecuteCodeFunction: standalone AIFunction for manual/static wiring when the sandbox configuration is fixed.
- Approval model via CodeActApprovalMode (AlwaysRequire / NeverRequire) with propagation from ApprovalRequiredAIFunction-wrapped tools.
- Unit tests (instruction builder, tool bridge, approval computation, provider CRUD, ProvideAIContextAsync snapshot isolation and approval wrapping).
- Env-gated integration test (HYPERLIGHT_PYTHON_GUEST_PATH).
- Three samples under samples/02-agents/AgentWithCodeAct (interpreter, tool-enabled, manual wiring).

Build is not yet runnable: requires .NET SDK 10.0.200 and the not-yet-published HyperlightSandbox.Api 0.1.0-preview NuGet package. Package is marked IsPackable=false until the dependency is available.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR #5329 review feedback for Hyperlight CodeAct provider

- 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 <223556219+Copilot@users.noreply.github.com>

* Align Hyperlight package id and JS warm-up with merged upstream SDK

The .NET SDK in hyperlight-dev/hyperlight-sandbox PR #46 has merged. The
published package id is Hyperlight.HyperlightSandbox.Api (the bare
HyperlightSandbox.Api remains the assembly/namespace) and the reference
CodeExecutionTool uses 'void 0;' as the JavaScript warm-up no-op. Update
the package reference, project comment, README, and SandboxExecutor warm-up
accordingly.

No functional change beyond that — all other public APIs we depend on
(SandboxBuilder.With*, Sandbox.Run/RegisterToolAsync/AllowDomain/Snapshot/
Restore, ExecutionResult, SandboxBackend) match the merged shape.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Bump Hyperlight package to 0.4.0 and fix build/test issues

Hyperlight.HyperlightSandbox.Api 0.4.0 is now published on nuget.org. Bump
the version reference and address the analyzer/runtime issues that surfaced
once restore could complete:

- Add HyperlightJsonContext source-generated JsonSerializerContext for the
  execute_code result + tool error envelopes; route arbitrary AIFunction
  results through AIJsonUtilities.DefaultOptions to keep IsAotCompatible=true.
- Replace explicit ObjectDisposedException throws with
  ObjectDisposedException.ThrowIf (CA1513).
- Use HyperlightSandbox.Api.SandboxBackend in cref docs to disambiguate.
- Update tests to match AIContext.Tools being IEnumerable<AITool>, drop
  ConfigureAwait(false) in xUnit test methods (xUnit1030), use collection
  expressions for AllowedDomain methods.
- Add 'using OpenAI.Chat;' to all three samples so AsAIAgent resolves.
- Verified: dotnet build of all four hyperlight projects + samples succeeds
  on net8/9/10; dotnet test for the unit tests passes 32/32 on net10.0.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix CI check failures: file encoding (UTF-8 BOM + LF) and broken markdown link

- Convert all new .cs/.csproj files to UTF-8 with BOM and LF line endings
  to satisfy the dotnet/.editorconfig charset/end_of_line settings
  enforced by check-format.
- Drop unused System.Collections.Generic using in HyperlightCodeActProviderTests.
- Add missing using Microsoft.Extensions.AI in CodeActApprovalMode.cs and
  shorten ApprovalRequiredAIFunction cref (IDE0001).
- Fix broken README link to docs/decisions/0024-codeact-integration.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review: AIFunction inheritance, packaging, GetService approval check

- HyperlightExecuteCodeFunction now inherits AIFunction directly. The
  AsAIFunction() indirection is gone; instances are accepted anywhere an
  AIFunction is. Approval requirement is surfaced via GetService<ApprovalRequiredAIFunction>()
  which lazily exposes a wrapping ApprovalRequiredAIFunction proxy when the
  effective ApprovalMode/tool stack requires it.
- ComputeApprovalRequired now uses GetService<ApprovalRequiredAIFunction>() so
  approval-required tools nested anywhere in the AITool decorator stack are
  detected (not just the top-most class).
- csproj: drop IsPackable=false (ready to release with the published
  Hyperlight.HyperlightSandbox.Api 0.4.0 dependency); add PackageReadmeFile
  and pack README.md at the package root, matching the pattern used by
  Aspire.Hosting.AgentFramework.DevUI / Microsoft.Agents.AI.DurableTask.
- Update Step03 sample and README wording to reflect direct AIFunction usage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

e7dc3b91f1 · 2026-05-05 12:56:24 +00:00

History

AgentWithCodeAct_Step02_ToolEnabled.csproj

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

2026-05-05 12:56:24 +00:00

Program.cs

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

2026-05-05 12:56:24 +00:00

README.md

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

2026-05-05 12:56:24 +00:00

README.md

AgentWithCodeAct_Step02_ToolEnabled

Demonstrates adding provider-owned tools to HyperlightCodeActProvider. Those tools are only available to code running inside the sandbox via call_tool("<name>", ...) — they are never exposed to the model as direct tools. This lets the model orchestrate multiple tool calls in a single Python block.

One tool (send_email) is wrapped in ApprovalRequiredAIFunction, which causes the entire execute_code invocation to require user approval when that tool is configured.

Configuration

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI endpoint. Required.
`AZURE_OPENAI_DEPLOYMENT_NAME`	Azure OpenAI deployment. Defaults to `gpt-5.4-mini`.
`HYPERLIGHT_PYTHON_GUEST_PATH`	Absolute path to the Hyperlight Python guest module (`.wasm` or `.aot` file). Required.

Run

cd AgentWithCodeAct_Step02_ToolEnabled
dotnet run

Planned follow-up

A more realistic "upload a file (e.g. an Excel workbook), have the agent analyze it with code" sample is planned as a separate step that will use HostInputDirectory together with a guest tool capable of reading the uploaded file. It will be added in a follow-up PR once the corresponding guest module support is in place.