Hyperlight 是代理框架中 CodeAct 的当前记录后端。 它提供了一个由独立沙盒运行时支持的execute_code工具，并可以通过call_tool(...)调用属于提供商的主机工具。
有关模式级别的概述，请参阅 CodeAct。
为什么 Hyperlight CodeAct
与模型本身相比，现代代理往往更受工具调用开销的限制。 读取数据、执行轻量计算和组合结果的任务可以轻松转换为模型链-工具->>模型->工具交互，即使每个步骤都很简单。
由 Hyperlight 支持的 CodeAct 简化了该循环。 该模型编写一个简短的 Python 程序，沙盒执行一次，由提供商拥有的工具可以从沙盒内部访问。call_tool(...) 在具有代表性的工具密集型工作负载中，这种转变可以将延迟减少近一半，并将令牌使用降低超过 60%，同时使执行保持独立和可审计。
开始
即将推出。
安装软件包
pip install agent-framework-hyperlight --pre
agent-framework-hyperlight 与 agent-framework-core 是分别交付的，所以只有在需要时才使用沙盒运行时。
注释
包依赖于 Hyperlight 沙盒组件。 如果后端尚未针对当前平台发布， execute_code 则尝试创建沙盒时会失败。
使用 HyperlightCodeActProvider
HyperlightCodeActProvider 是在希望为每次运行自动添加 CodeAct 时推荐的入口点。 它注入运行范围内的 CodeAct 指令和 execute_code 工具，同时使提供程序拥有的工具远离直接代理工具图面。
在提供程序上注册的工具可通过沙盒内的call_tool(...)提供，但它们不会公开为直接的代理工具。 提供程序还通过诸如add_tools(...)、remove_tool(...)、add_file_mounts(...) 和add_allowed_domains(...)方法，公开了工具、文件装载和出站允许名单条目的 CRUD 样式管理。
审批和托管工具的工作原理
代理框架工具包含一个 approval_mode，该控件决定工具是可以自动调用还是必须暂停等待用户批准。
在 HyperlightCodeActProvider 上注册工具和在 Agent(tools=...) 上直接注册工具的主要区别在于 如何调用该工具，而不是 Python 函数最终运行的位置：
- 在
HyperlightCodeActProvider(tools=...)上注册的工具被隐藏为模型中的直接工具。 模型通过编写代码在call_tool("name", ...)内调用execute_code来访问它们。 - 注册
Agent(tools=...)的工具作为一级工具集成到模型中，每次调用时都遵循该工具自身的approval_mode功能。
call_tool(...) 是回到主机回调的桥梁, 它不是工具在沙盒内的重新实现。 这意味着提供程序拥有的工具仍在主机进程中执行，无论主机进程本身可以访问什么文件系统、网络和凭据。
一般来说：
- 在提供程序上放置廉价、确定性的、安全的链式工具，以便模型可以在一
execute_code轮内编写许多调用。 - 将具有副作用或需要审批的操作保留为直接代理工具，通常使用
approval_mode="always_require"，这样每次调用都保持单独可见且可审批。
由于主机工具在沙盒外部运行，file_mounts和allowed_domains约束的是沙盒内的代码本身，而不是call_tool(...)后的主机回调。 需要控制对敏感资源的访问时，首选窄主机工具而不是扩大沙盒权限。
注释
通过 call_tool(...) 调用的工具将本机Python值（dict、list、基元或自定义对象）直接返回到来宾。 在result_parser上配置的任何FunctionTool内容都是为面向 LLM 的用户设计的，并不会在沙盒路径上运行。如果需要为沙盒内的用户设置格式，请在工具功能内进行。
请使用 HyperlightExecuteCodeTool 进行直接连接
当您需要在同一个代理上将 execute_code 与仅用于直接访问的工具混合使用时，请选择使用 HyperlightExecuteCodeTool，而不是提供程序。 对于固定配置，可以生成 CodeAct 指令一次，并直接连接该工具：
from agent_framework_hyperlight import HyperlightExecuteCodeTool
execute_code = HyperlightExecuteCodeTool(
tools=[compute],
approval_mode="never_require",
)
codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)
当 CodeAct 表面固定并且每次运行时不需要提供者生命周期时，此模式非常有用。 与HyperlightCodeActProvider不同，独立工具不会自动注入提示指导，因此你需手动将build_instructions(...)输出添加到代理指令中。
配置文件和出站访问
Hyperlight 可以暴露一个只读 /input 树以及一个用于生成工件的可写 /output 区域。
- 使用
workspace_root使工作区在/input/下可用。 - 用于
file_mounts将特定主机路径映射到沙盒中。 - 用于
allowed_domains仅针对特定目标或方法启用出站访问。
file_mounts 接受简写字符串、显式 (host_path, mount_path) 对或 FileMount 命名元组。
allowed_domains 接受字符串目标、显式 (target, method-or-methods) 对或 AllowedDomain 命名元组。
from agent_framework_hyperlight import HyperlightCodeActProvider
codeact = HyperlightCodeActProvider(
tools=[compute],
file_mounts=[
"/host/data",
("/host/models", "/sandbox/models"),
],
allowed_domains=[
"api.github.com",
("internal.api.example.com", "GET"),
],
)
输出指南
若要显示文本 execute_code，应在代码末尾增加 print(...)；Hyperlight 不会自动返回最后一个表达式的值。
在启用文件系统访问时, 改为将更大的工件写入/output/<filename>。 返回的文件附加到工具结果，而下面的 /input 文件可用于在沙盒中读取。
比较 CodeAct 和直接工具调用
基准示例使用同一客户端、模型、工具、提示和结构化输出架构运行相同的任务，一次通过传统工具调用，一次通过 Hyperlight 支持的 CodeAct 运行一次。 唯一的区别是布线：直接连接的工具与由 execute_code 支持的单个 HyperlightCodeActProvider 工具。
在该示例中，代理通过重复查找数据和执行轻计算来计算用户数据集和订单的总计。 正是这种多步小步骤的工作流，CodeAct 可以减少编排开销。 完整示例打印两次运行的已用时间和令牌使用情况，以便您可以比较自己环境中的执行形态。
当前限制
此包仍是测试版，需要围绕一些限制进行规划：
- 平台支持遵循已发布的 Hyperlight 后端包。 今天，这意味着支持的 Linux 和 Windows 环境;创建沙盒时，不支持的平台将失败。
- 当前集成执行 Python 客户代码。 .NET 文档即将推出。
- 内存中解释器状态不会在单独的
execute_code调用中保留。 当数据需要跨调用生存时，请使用装载的文件和/output项目。 - 审批适用于
execute_code整个调用，不适用于同一代码块中的每个个人call_tool(...)。 - 工具说明、参数注释和返回形状在这里更为重要，因为模型正在针对该协定编写代码，而不是选择独立的直接工具调用。