Hyperlight-backed CodeAct integrations for Microsoft Agent Framework.
Warning
FIDES integration is not supported with CodeAct providers. Host-tool calls
made inside generated code bypass the agent's function middleware, so FIDES
policy enforcement and label tracking do not apply to those nested calls or
intermediate code values. Checks on the outer execute_code invocation do not
enforce the policies of individual tools called inside it.
Registering tools with recognized FIDES additional_properties logs a warning,
but does not block execution. This is a best-effort diagnostic: FIDES also uses
defaults for unannotated tools, so no warning does not imply support or safety.
Keep tools that require FIDES as direct agent tools, not Hyperlight-managed tools,
and enforce authorization and destination restrictions inside host functions.
Sandbox isolation does not supply FIDES enforcement.
See the FIDES guide.
Host tool callbacks expose a generic RuntimeError("Host tool execution failed.")
by default, before diagnostics reach generated code. Raw sandbox failure details
are omitted from error contents. Successful outputs and known-safe output-limit
or cleanup errors retain their existing behavior.
Both HyperlightCodeActProvider and HyperlightExecuteCodeTool accept the
host-side option include_detailed_errors=True for trusted channels. It preserves
original callback exceptions and sandbox error details, which may contain
sensitive data. It is not a parameter of execute_code and is independent of the
outer chat client's error policy and sensitive-data logging.
The policy is captured in each run snapshot and serialized state. Sandbox cache keys include it, so detailed-error callbacks are not reused for redacted runs. Initialization, snapshot restore, and execution failures follow the same policy. Failed sandbox entries are retired; cancellation and system-exit signals still propagate without becoming ordinary execution errors.
Guest execution has a finite 30-second budget by default. Both
HyperlightCodeActProvider and HyperlightExecuteCodeTool accept the host-side
execution_timeout_seconds option, which must be a positive finite number.
Applications that intentionally run longer must configure a larger budget.
The option is captured in provider run snapshots and serialized state; it is
not a model-controlled execute_code argument.
Reaching the budget returns an error content with
Code execution exceeded its time limit. Caller task cancellation interrupts
guest execution and propagates asyncio.CancelledError. Cancellation waits for
native execution and its interruption thread to finish, even if the caller
cancels again. Queued cancellation does not interrupt another invocation.
The next invocation restores the warm snapshot before reusing the sandbox.
The budget starts on the sandbox's owning worker, not while waiting for that worker. Initialization and warm-up share the invocation's budget, but runtime initialization and host tool callbacks cannot be interrupted. Host tools must enforce their own cancellation and time limits. Completed results and unrelated execution failures are not replaced with a timeout that arrives late.
This behavior uses the cross-thread Sandbox.interrupt_handle() API included
in the required Hyperlight SDK 0.9.0 or later.
To run the native regressions on a KVM host with the required SDK and both backends installed:
HYPERLIGHT_RUN_GUEST_TESTS=true uv run --directory python/packages/hyperlight pytest \
tests/hyperlight/test_execution_limits.py -m integrationpip install agent-framework-hyperlight --preThis package depends on hyperlight-sandbox, the packaged Python guest, and the
Wasm backend package on supported platforms. The backend is currently installed
for supported Python versions 3.11 through 3.15 on Linux x86_64 and Windows AMD64. If a compatible
backend is not published for your current platform and Python version,
execute_code will fail at runtime when it tries to create the sandbox.
Use HyperlightCodeActProvider to automatically inject the execute_code tool
and CodeAct instructions into every agent run. Tools registered on the provider
are available inside the sandbox via call_tool(...) but are not exposed as
direct agent tools.
from agent_framework import Agent, tool
from agent_framework_hyperlight import HyperlightCodeActProvider
@tool
def compute(operation: str, a: float, b: float) -> float:
"""Perform a math operation."""
ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b}
return ops[operation]
codeact = HyperlightCodeActProvider(
tools=[compute],
approval_mode="never_require",
)
agent = Agent(
client=client,
name="CodeActAgent",
instructions="You are a helpful assistant.",
context_providers=[codeact],
)
result = await agent.run("Multiply 6 by 7 using execute_code.")Use HyperlightExecuteCodeTool directly when you want full control over how the
tool is added to the agent. This is useful when mixing sandbox tools with
direct-only tools on the same agent.
from agent_framework import Agent, tool
from agent_framework_hyperlight import HyperlightExecuteCodeTool
@tool
def send_email(to: str, subject: str, body: str) -> str:
"""Send an email (direct-only, not available inside the sandbox)."""
return f"Email sent to {to}"
execute_code = HyperlightExecuteCodeTool(
tools=[compute],
approval_mode="never_require",
)
agent = Agent(
client=client,
name="MixedToolsAgent",
instructions="You are a helpful assistant.",
tools=[send_email, execute_code],
)For fixed configurations where provider lifecycle overhead is unnecessary, build the CodeAct instructions once and pass them to the agent at construction time:
execute_code = HyperlightExecuteCodeTool(
tools=[compute],
approval_mode="never_require",
)
codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)
agent = Agent(
client=client,
name="StaticWiringAgent",
instructions=f"You are a helpful assistant.\n\n{codeact_instructions}",
tools=[execute_code],
)Mount host directories into the sandbox and allow outbound HTTP to specific domains:
from agent_framework_hyperlight import HyperlightCodeActProvider, FileMount
codeact = HyperlightCodeActProvider(
tools=[compute],
file_mounts=[
"/host/data", # shorthand — same path in sandbox
("/host/models", "/sandbox/models"), # explicit host → sandbox mapping
FileMount("/host/config", "/sandbox/config"), # named tuple
],
allowed_domains=[
"api.github.com", # all methods
("internal.api.example.com", "GET"), # GET only
],
)Both HyperlightExecuteCodeTool and HyperlightCodeActProvider accept the
keyword-only tool_description_format option. The default, "compact", includes
each parameter's scalar type, required/optional status, description, enum values,
and default when present. Use "json" to include the complete JSON Schema:
execute_code = HyperlightExecuteCodeTool(
tools=[compute],
tool_description_format="json",
)
codeact = HyperlightCodeActProvider(
tools=[compute],
tool_description_format={"compute": "json", "send_email": "compact"},
)A string applies to every registered tool. A mapping selects formats by exact,
case-sensitive tool name; missing names use "compact". Mappings are copied at
construction and when creating run-scoped tools, and entries for unregistered
tools are retained for later registration.
Compact mode automatically falls back to full JSON Schema, with an explanatory
note, when a schema cannot be represented faithfully (for example, nested objects,
arrays, references, or additional constraints). No schema details are discarded.
Only "compact" and "json" are accepted; None is not supported.
Tool parameter schemas are model-visible metadata, just as they are for direct function calling. Do not put credentials, tenant identifiers, or other secrets in parameter descriptions, enum values, defaults, or custom schema fields.
This option affects HyperlightExecuteCodeTool.description, or the injected
run tool's .description when using HyperlightCodeActProvider. It does not
change the short CodeAct instructions, the execute_code input schema, sandbox
execution, or runtime caching.
Files written under /output are returned as inline data attachments. Hyperlight
limits each invocation to 20 files, 5 MiB per file, and 20 MiB of cumulative raw
file data by default. Oversized output is returned as a structured execution error
without partial data attachments.
Output discovery also has finite internal entry and nesting-depth safeguards;
directory-heavy output that exceeds them is rejected as an execution error.
Trusted applications can raise these limits with positive integers on either
HyperlightExecuteCodeTool or HyperlightCodeActProvider:
codeact = HyperlightCodeActProvider(
workspace_root="./workspace",
max_output_files=40,
max_output_file_bytes=10 * 1024 * 1024,
max_output_total_bytes=50 * 1024 * 1024,
)Limits are always finite. Increasing them also increases host memory use because file data is encoded as inline base64, and may increase model context cost when attachments are included in subsequent requests.
Nested output paths require secure directory-relative file opening. On platforms
without that capability, nested attachments fail closed; write attachment files
directly under /output for portable behavior.
allowed_domains controls outbound requests from the sandbox. It does not
install Python packages or make packages from the host environment available
inside the guest. Installing a dependency with pip on the host is separate
from making it importable in sandboxed code.
module_path selects an existing guest module; it is not a package-installation
option. The Agent Framework integration does not provide a custom guest build
or package installation workflow. Guest package availability depends on the
selected Hyperlight module and backend.
For operations requiring host-installed libraries or external APIs, register a
host function in tools and call it from sandboxed code using call_tool(...).
Keep credentials and access checks in that function. Host tools execute outside
the guest, so the sandbox's allowed_domains setting does not restrict their
network requests; enforce any required destination policy in the host tool.
- This package is intentionally separate from
agent-framework-coreso CodeAct usage and installation remain optional. Withagent-framework-core[all](or the metaagent-framework) installed it is also reachable through the lazy-loading namespaceagent_framework.hyperlight. file_mountsaccepts a single string shorthand, an explicit(host_path, mount_path)pair, or aFileMountnamed tuple. The host-side path in the explicit forms may be astrorPath. Use the explicit two-value form when the host path differs from the sandbox path.allowed_domainsaccepts a single string target such as"github.com"to allow all backend-supported methods, an explicit(target, method_or_methods)tuple such as("github.com", "GET"), or anAllowedDomainnamed tuple.- Tools registered with the sandbox return their native Python value
(
dict,list, primitives, or custom objects) directly to the guest via the Hyperlight FFI. Anyresult_parserconfigured on aFunctionToolis intended for LLM-facing consumers and does not run on the sandbox path — apply formatting inside the tool function itself if you need it for in-sandbox consumers.