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(...)公开提供程序拥有的工具。 - 应用能力限制，例如文件系统访问或出站网络允许列表。
由于连接器拥有运行时配置，因此确切的设置详细信息取决于所选后端。
当前限制
警告
不支持将 FIDES 与当前的 CodeAct 提供程序组合在一起。 FIDES 目前仅支持 Python，在 .NET CodeAct 提供程序中不可用。
生成的代码内由提供程序管理的主机工具调用不会通过代理的按函数中间件管道传递。 对直接智能体工具或外部 execute_code 调用的检查不会为嵌套调用或代码内部中间值建立 FIDES 强制执行。 它们也不涵盖文件或网络功能。
主机工具必须强制执行自己的授权和目标控制。 将依赖于 FIDES 的工具保留为直接代理工具，而不是 CodeAct 托管工具，或者为需要这些保证的工作流禁用 CodeAct。 此兼容性边界是当前的集成限制，而不是 CodeAct 模式的固有限制。 请参阅 FIDES 的代理安全性。
CodeAct 非常适合工具密集型工作流，但请记住以下约束：
- Hyperlight CodeAct 支持Python和.NET。 Monty 仅限 Python；本地 CodeAct 仅限 .NET。
- 审批目前整体应用于
execute_code调用。 如果需要逐个批准单个操作，请将这些操作保留为直接代理工具，而不是依赖call_tool(...)。 -
call_tool(...)访问的工具仍在主机进程中执行。 对敏感 I/O 使用经过审查的窄范围宿主工具，而不是不必要地扩大沙盒访问。 - 当编排开销占主导地位时，CodeAct 最有效。 对于只有一两个工具调用的小型任务，添加的抽象可能不值得。
- 工具名称、参数元数据和返回形状在这里更为重要，因为模型依据该合同进行代码编写，而不是每次从一个直接工具调用中选择。
开始
对于 .NET，Hyperlight CodeAct 以 Microsoft.Agents.AI.Hyperlight 包形式提供。
本地 CodeAct 在子进程中运行生成的 Python，并依赖于外部隔离。
Hyperlight 包提供：
-
HyperlightCodeActProvider— 一个为每个运行注入execute_code和 CodeAct 指南的AIContextProvider -
HyperlightExecuteCodeFunction— 当沙盒配置固定时用于静态/手动接线的独立AIFunction - 通过
call_tool(...)在沙盒内保持可用的提供程序管理工具 - 用于审批的
CodeActApprovalMode和ApprovalRequiredAIFunction集成 - 沙盒运行时的可选文件系统 （
FileMounts、HostInputDirectory） 和出站网络 （AllowedDomains） 配置
Important
该 .NET 包目前为预览版，并且依赖于 Hyperlight.HyperlightSandbox.Api NuGet，而该 NuGet 尚未发布到 nuget.org。 有关当前安装注意事项和平台要求，请参阅 Hyperlight CodeAct 。
有关安装、示例和特定于运行时的指南，请参阅 Hyperlight CodeAct 。
开始
对于Python，将 Hyperlight CodeAct 用于隔离沙盒，或者使用 Monty 作为跨平台的受限解释器。
Hyperlight 包提供：
- 用于基于上下文提供程序的运行的
HyperlightCodeActProvider -
HyperlightExecuteCodeTool如果想要直接接线execute_code - 通过
call_tool(...)在沙盒内保持可用的提供程序管理工具 - 沙盒运行时的可选文件系统和出站网络配置
请参阅 Hyperlight CodeAct 以获取安装信息、示例、何时使用 print(...) 和 /output/ 等特定于运行时的指南，以及当前特定于 Hyperlight 的限制。
注释
Go 语言对该功能的支持即将推出。 有关最新状态，请参阅 Agent Framework Go 存储库 。