CodeAct 允许代理通过编写代码并使用 execute_code 工具执行来解决任务。 CodeAct 不要求模型每次只发出一个工具调用，而是在单个执行步骤中提供一个沙盒环境，用于结合控制流、数据转化和工具编排。
在 Agent Framework 中，CodeAct 通过特定于后端的包（而不是单个内置核心类型）公开。 连接器可以添加 execute_code 工具、注入运行时指南，并且选择性地公开可从沙盒内部调用的提供程序拥有的工具。
为什么 CodeAct
现代 AI 代理通常不是受限于模型质量，而是被协调开销所限制。 当代理将许多小型工具调用链接在一起时，每个步骤通常需要另一个模型轮次，这会增加延迟和令牌的使用。
CodeAct 压缩了那种模型 -> 工具 -> 模型循环。 代理框架可以公开单个 execute_code 工具，并让模型将完整计划表示为简短程序，而不是要求模型一次选取一个工具。 工具保持不变，模型保持不变，主要更改是计划在沙盒中运行一次，而不是分散在多个工具调用轮次中。
对于工具密集型工作负荷，它可以大幅减少端到端延迟和令牌使用，同时在一个代码块中保持计划紧凑且可审核。 有关并排接线比较，请参阅 Hyperlight CodeAct 集成。
何时适合使用 CodeAct
当任务受益于以下情况时使用 CodeAct：
- 将多个工具调用与循环、分支、筛选或聚合组合在一起
- 在返回最终答案之前转换工具结果
- 在运行过程中生成更大的结构化输出或项目
- 使某些工具仅在受控的执行环境中可用
- 将许多小的、可链接的查找或轻量级计算压缩到单个执行步骤中
在以下情况下坚持使用直接工具调用：
- 任务只需要一两次工具调用，因此几乎没有需要移除的编排开销
- 每次调用都有副作用，这些副作用应单独对模型和用户可见
- 你需要每次调用的审批提示，而不是围绕整个
execute_code运行的单一审批决策
CodeAct 如何集成到代理框架中
CodeAct 连接器通常对运行执行四项操作：
- 将工具
execute_code添加到面向模型的工具界面。 - 提供关于配置的沙盒运行时的指示说明。
- 可选通过
call_tool(...)公开提供程序拥有的工具。 - 应用能力限制，例如文件系统访问或出站网络允许列表。
由于连接器拥有运行时配置，因此确切的设置详细信息取决于所选后端。
当前限制
CodeAct 非常适合工具密集型工作流，但需要记住一些当前约束：
- 目前已有文档记录的 Agent Framework 连接器是 Hyperlight CodeAct，提供 Python 和 .NET 版本（预览版）。
- 审批目前整体应用于
execute_code调用。 如果需要逐个批准单个操作，请将这些操作保留为直接代理工具，而不是依赖call_tool(...)。 -
call_tool(...)访问的工具仍在主机进程中执行。 对敏感 I/O 使用经过审查的窄范围宿主工具，而不是不必要地扩大沙盒访问。 - 当编排开销占主导地位时，CodeAct 最有效。 对于只有一两个工具调用的小型任务，添加的抽象可能并不能带来太多好处。
- 工具名称、参数元数据和返回形状在这里更为重要，因为模型依据该合同进行代码编写，而不是每次从一个直接工具调用中选择。
开始
对于 .NET，当前文档中说明的连接器是 Hyperlight CodeAct，以 Microsoft.Agents.AI.Hyperlight 包的形式提供。
包提供：
-
HyperlightCodeActProvider— 一个为每个运行注入AIContextProvider和 CodeAct 指南的execute_code -
HyperlightExecuteCodeFunction— 当沙盒配置固定时用于静态/手动接线的独立AIFunction - 通过
call_tool(...)在沙盒内保持可用的提供程序管理工具 - 用于审批的
CodeActApprovalMode和ApprovalRequiredAIFunction集成 - 沙盒运行时的可选文件系统 （
FileMounts、HostInputDirectory） 和出站网络 （AllowedDomains） 配置
Important
.NET 包目前为预览版，并且依赖于尚未发布到 nuget.org 的 Hyperlight.HyperlightSandbox.Api NuGet 包。有关当前安装注意事项和平台要求，请参阅 Hyperlight CodeAct。
有关安装、示例和特定于运行时的指南，请参阅 Hyperlight CodeAct 。
开始
对于 Python，目前记录的连接器是 Hyperlight CodeAct。
Hyperlight 包提供：
- 用于基于上下文提供程序的运行的
HyperlightCodeActProvider -
HyperlightExecuteCodeTool如果想要直接接线execute_code - 通过
call_tool(...)在沙盒内保持可用的提供程序管理工具 - 沙盒运行时的可选文件系统和出站网络配置
请参阅 Hyperlight CodeAct 以获取安装信息、示例、何时使用 print(...) 和 /output/ 等特定于运行时的指南，以及当前特定于 Hyperlight 的限制。
注释
Go 语言对该功能的支持即将推出。 有关最新状态，请参阅 Agent Framework Go 存储库 。