CodeActCodeAct

CodeAct lets an agent solve a task by writing code and executing it through an execute_code tool. Instead of asking the model to emit one tool call at a time, CodeAct gives it a sandboxed place to combine control flow, data transformation, and tool orchestration inside a single execution step.CodeAct 让代理通过编写代码并使用 execute_code 工具执行代码来解决问题。它不是要求模型一次发出一个工具调用，而是为它提供一个沙盒环境，使其能够在单个执行步骤中组合控制流、数据转换和工具编排。

In Agent Framework, CodeAct is exposed through backend-specific packages rather than a single built-in core type. A connector can add the execute_code tool, inject runtime guidance, and optionally expose provider-owned tools that are callable from inside the sandbox.在 Agent Framework 中，CodeAct 通过后端特定的包暴露，而不是单一的内置核心类型。连接器可以添加 execute_code 工具、注入运行时指导，并可选地暴露提供者拥有的、可从沙盒内部调用的工具。

Why CodeAct为什么选择CodeAct

Modern AI agents often are not bottlenecked by model quality, but by orchestration overhead. When an agent chains together many small tool calls, each step usually requires another model turn, which increases both latency and token usage.现代AI智能体往往不受模型质量的瓶颈限制，而是受制于编排开销。当智能体将许多小工具调用串联起来时，每一步通常都需要一次额外的模型推理，这既增加了延迟，也增加了令牌消耗。

CodeAct collapses that model -> tool -> model loop. Instead of asking the model to pick one tool at a time, Agent Framework can expose a single execute_code tool and let the model express the full plan as a short program. The tools stay the same, the model stays the same, and the main change is that the plan runs once inside a sandbox instead of being scattered across several tool-call turns.CodeAct打破了模型→工具→模型的循环。Agent Framework无需让模型每次只选择一个工具，而是可以暴露一个单一的execute_code工具，让模型将完整计划表达为一段简短的程序。工具保持不变，模型保持不变，主要变化在于计划在沙箱内一次性执行，而不是分散在多次工具调用回合中。

For tool-heavy workloads, that can materially reduce end-to-end latency and token usage while keeping the plan compact and auditable in one code block. See the Hyperlight CodeAct integration for a side-by-side wiring comparison.对于工具密集型工作负载，这可以显著降低端到端延迟和令牌消耗，同时将计划保持在一个代码块中，紧凑且可审计。请参阅Hyperlight CodeAct集成以了解并排接线比较。

When CodeAct is a good fitCodeAct何时适用

Use CodeAct when a task benefits from:当任务受益于以下情况时，使用CodeAct：

• combining multiple tool calls with loops, branching, filtering, or aggregation将多个工具调用与循环、分支、过滤或聚合相结合
• transforming tool results before returning a final answer在返回最终答案前转换工具结果
• generating larger structured outputs or artifacts as part of a run在运行过程中生成更大的结构化输出或工件
• keeping some tools available only inside a controlled execution environment仅将某些工具保留在受控执行环境中
• collapsing many small, chainable lookups or lightweight computations into one execution step将许多小型、可链式调用的查找或轻量级计算合并到一个执行步骤中

Stay with direct tool calling when:在以下情况下坚持直接工具调用：

• the task only needs one or two tool calls, so there is little orchestration overhead to remove任务只需要一两次工具调用，因此几乎没有编排开销需要消除
• each call has side effects that should stay individually visible to the model and the user每次调用都有副作用，应保持对模型和用户单独可见
• you need per-call approval prompts instead of one approval decision around the whole execute_code run你需要每次调用的审批提示，而不是围绕整个 execute_code 运行的一个审批决策

How CodeAct fits in Agent FrameworkCodeAct 如何融入代理框架

A CodeAct connector typically does four things for a run:CodeAct 连接器通常为一次运行做四件事：

1. Adds an execute_code tool to the model-facing tool surface.向模型面向的工具界面添加一个 execute_code 工具。
2. Supplies instructions for the configured sandbox runtime.为配置的沙箱运行时提供指令。
3. Optionally exposes provider-owned tools through call_tool(...).可选地通过 call_tool(...) 暴露提供商拥有的工具。
4. Applies capability limits such as filesystem access or outbound-network allow lists.应用能力限制，如文件系统访问或出站网络允许列表。

Because the connector owns the runtime configuration, the exact setup details depend on the backend you choose.由于连接器拥有运行时配置，具体设置细节取决于你选择的后端。

Current limitations当前限制

CodeAct is a strong fit for tool-heavy workflows, but there are a few current constraints to keep in mind:CodeAct 非常适合工具密集型工作流，但需要注意一些当前约束：

• The documented Agent Framework connector today is Hyperlight CodeAct, available for both Python and .NET (in preview).目前文档化的代理框架连接器是 Hyperlight CodeAct，适用于 Python 和 .NET（预览版）。
• Approvals currently apply to the execute_code call as a whole. If you need individual operations to be approved one by one, keep those operations as direct agent tools instead of relying on call_tool(...).审批目前适用于整个 execute_code 调用。如果你需要逐个批准单个操作，请将这些操作保留为直接代理工具，而不是依赖 call_tool(...)。
• Tools reached through call_tool(...) still execute in the host process. Use narrow, reviewed host tools for sensitive I/O instead of broadening sandbox access unnecessarily.通过 call_tool(...) 访问的工具仍在主机进程中执行。对于敏感的 I/O，请使用狭窄、经过审查的主机工具，而不是不必要地扩大沙箱访问权限。
• CodeAct works best when orchestration overhead dominates. For small tasks with only one or two tool calls, the added abstraction may not buy you much.当编排开销占主导地位时，CodeAct 效果最佳。对于只有一两次工具调用的小任务，增加的抽象可能不会带来太多好处。
• Tool names, parameter metadata, and return shapes matter more here because the model is writing code against that contract rather than choosing from one direct tool call at a time.工具名称、参数元数据和返回形状在这里更为重要，因为模型是根据该合约编写代码，而不是一次选择一个直接工具调用。

Next steps后续步骤

Related content相关内容

• Hyperlight CodeActHyperlight CodeAct
• CodeAct paperCodeAct 论文
• Code Interpreter代码解释器
• Tool Approval工具审批
• Context Providers上下文提供者