Provides Hyperlight-backed CodeAct (sandboxed code execution) integration for Microsoft Agent Framework.
Get Started
| Product | Versions |
|---|---|
| .NET |
README
Microsoft.Agents.AI.Hyperlight
First-class CodeAct support for the Microsoft Agent Framework, backed by the Hyperlight VM-isolated sandbox.
The package exposes two entry points:
HyperlightCodeActProvider— anAIContextProviderthat injects anexecute_codetool and CodeAct guidance into every agent invocation. Only oneHyperlightCodeActProvidermay be attached to a given agent; it enforces this through a fixedStateKeysvalue soChatClientAgent's state-key uniqueness validation rejects duplicate registrations.HyperlightExecuteCodeFunction— a standaloneAIFunctionfor static/manual wiring when the sandbox configuration is fixed for the agent's lifetime.
Both surfaces support:
- Provider-owned tools exposed inside the sandbox via
call_tool(...)(multiple allowed). - Opt-in filesystem mounts and outbound network allow-list.
CodeActApprovalModecontrol:NeverRequire(default; approval propagates from tools wrapped inApprovalRequiredAIFunction) andAlwaysRequire.- Snapshot/restore per run so the guest starts from a known clean state every invocation.
Requirements
- The
Hyperlight.HyperlightSandbox.ApiNuGet package, published from thesrc/sdk/dotnetSDK in hyperlight-dev/hyperlight-sandbox (the .NET API was added in PR #46, now merged). Until the package is published to nuget.org the project restore will fail; this project is intentionallyIsPackable=falsein the meantime. - A Hyperlight Python guest module when using
SandboxBackend.Wasm.
Error diagnostics
Host tool failures return a generic JSON error by default. Host execution
exceptions returned by the executor also use a generic message.
HyperlightCodeActProviderOptions.IncludeDetailedErrors defaults to false
for both the provider and standalone function. Set it to true only for a
trusted channel: full exception details, including stack traces and inner
exceptions, can contain sensitive data. Argument-validation errors keep their
safe messages by default and include stack traces only with this opt-in.
This option is independent of the outer FunctionInvokingChatClient error policy
and sensitive-data logging. Outer error handling cannot redact diagnostics that
generated code has already caught and included in normal output. Run snapshots
capture the policy, and sandbox configuration fingerprints include it so cached
callbacks cannot retain a different disclosure policy.
The same boundary covers initialization, warm-up, snapshot restore, and execution
failures. Ordinary failures dispose and clear failed sandbox state before returning
an error; cancellation still propagates.
Network access and guest packages
HyperlightCodeActProviderOptions.AllowedDomains controls outbound requests
from the sandbox. It does not install guest packages or expose host-installed
dependencies to guest code.
CreateForWasm(modulePath) selects an existing .wasm or .aot guest module;
it does not build a guest or install Python packages. The Agent Framework
integration does not provide a custom guest build or package installation
workflow. Package availability depends on the selected module and backend;
the default JavaScript backend does not run Python code.
For operations requiring application dependencies or external APIs, register
an AIFunction in Tools and invoke it from the guest with call_tool(...).
Keep credentials and authorization in the host function. These functions run
outside the guest, so AllowedDomains does not restrict their network requests;
enforce any required destination policy in the host function.
Status
Preview. API may change until the underlying Hyperlight SDK reaches a stable release.
Downloads by Version
Similar & Alternative Packages
Hand-picked matching NuGet libraries based on tags & ecosystem
Depended On By
Find packages that declare this package as a dependency. NuGet does not provide a reverse-dependency endpoint, so candidates are checked on demand.
Adoption Assessment
A verified publisher signal is available. Assess fit from the package's supported frameworks, license and dependency graph rather than popularity alone.
Related Guides & Workflows
Learn how to evaluate, integrate, or audit this package in your .NET project.