让模型写 工作流程。
CodeAct是AI代理通过编写短程序来采取行动的一种方式。该程序仅调用您批准的工具，将其结果与普通代码相结合，并通过 ADK-Rust 运行时返回答案。
cart = call_tool("fetch_cart", args) subtotal = sum(item["price"] * item["qty"] for item in cart["items"]) rate = call_tool("tax_rate", region) total = subtotal * (1 + rate)
从这里开始
什么是CodeAct代理？
CodeAct 代理是一种 AI 智能体，它编写 executable 代码来决定多个已批准的工具应如何协同工作。 您的应用程序在受控解释器中运行该代码，并对每个外部操作负责。
传统工具调用
该模型一次选择一个动作。
- 01询问模型要调用哪个工具。
- 02运行该工具并将其结果发送回模型。
- 03询问模型下一步要做什么，然后重复。
CodeAct
该模型编写了完整的过程。
- 01使用可用的工具向模特询问一个简短的程序。
- 02运行程序并仅在到达实际工具时暂停。
- 03继续使用工具结果，直到程序返回其答案。
一个简单的比喻
传统的工具调用就像要求同事按下一个计算器按钮，报告屏幕，然后等待下一条指令。 CodeAct 就像授予该同事编写小型电子表格公式的权限：允许的输入保持不变，但计算可以包含变量、条件、循环和多个步骤。
您将在此页面上看到八个单词
型号
编写脚本的LLM。
代理
将目标转化为行动和结果的组件。
工具
经批准的 Rust 功能，可到达业务数据或系统。
脚本
为当前代理轮次编写的短程序。
运行时
executes 和暂停脚本的解释器。
观察
结果或错误返回到模型以进行另一轮。
检查站
已保存的暂停程序，稍后可以继续。
最终结果
输入的答案返回到您的应用程序。
这个想法是从哪里来的
CodeAct 最初是一个关于智能体动作语言的研究问题。
大多数早期使用工具的代理将动作表示为自然语言或包含工具名称和参数的 JSON 对象。研究人员 Xingyao Wang、Yangyi Chen、Lifan Yuan、Yizhe Zhang、Yunzhu Li、Hao Peng 和 Heng Ji 询问是否 executable Python 将是一种更具表现力的动作格式.
他们的论文， “可执行代码操作引出更好的 LLM 代理”，于 2024 年 2 月发布，并出现在 ICML 2024 上。它在 API-Bank 和论文的 M³ToolEval 基准上 evaluated 17 个语言模型。作者报告说，代码操作的成功率比测试的文本和 JSON 操作格式高出 20%。
论文还介绍了 CodeActInstruct，一个包含 7,000 次多轮交互的数据集，以及针对 execute 代码进行微调的 CodeActAgent 模型，观察结果、修改失败的程序并继续对话。这些是论文任务的研究结果；它们并不意味着代码操作对于每个产品来说都会更好。
为什么我要使用CodeAct？
CodeAct
当智能体必须将工具与计算结合起来时，CodeAct 非常引人注目。它为模型提供了一种熟悉的语言来表达逻辑，同时您的应用程序保留了工具和运行时边界。
组合几个工具
一个脚本可以调用多个已批准的工具，并将一个结果直接传递到下一步。
使用真实的控制流
循环、条件、变量、排序、过滤和算术都直接用代码表达。
减少模型往返次数
需要多次选择工具的工作有时可以在一个生成的脚本中表达。
将中间数据保留在本地
运行时可以在决定模型记录中包含哪些内容之前过滤或聚合大型工具结果。
纠正executable错误
语法错误、异常或失败的断言可以成为模型用来修改下一个脚本的观察结果。
检查动作
开发人员可以将生成的程序、工具调用、输出和检查点作为 execution 跟踪来读取。
权衡
我什么时候应该避免它？
一个简单的动作
当请求完全映射到一项业务操作时，正常的 LlmAgent 工具调用会更容易。
弱代码生成
一个难以编写有效代码的模型可能需要比结构化工具调用更多的修正次数。
没有安全运行时间
生成的代码需要具有显式访问和资源限制的解释器。切勿将其传递给不受限制的 eval 或 exec。
完整的软件开发
当目标是编辑存储库、运行 shell 命令或操作开发工作区时，请使用 CodingAgent。
生态系统中的实施
CodeAct 概念现在出现在多个代理系统中。
它们共享代码作为操作格式的想法，但在语言支持、工具公开、沙箱、状态和预期工作负载方面有所不同。
CodeAct
原创研究
Python 动作、CodeActInstruct、微调研究模型和容器化 execution 引擎。
了解更多↗OpenHands
软件代理
它的 CodeActAgent 可以与 execute Python 进行对话，并运行 shell 命令来进行软件开发工作。
了解更多↗smolagents
Hugging Face
CodeAgent 使用带有循环和条件的 Python 操作，并支持多个沙箱 executors。
了解更多↗Pydantic AI
代码模式
将代理的工具包装在代码接口中，并使用 Monty 作为受控 Python 运行时。
了解更多↗ADK-Rust
Rust-本机运行时
将 CodeAct 循环添加到类型化代理、工具、会话、事件、批准、回调和传输。
了解更多↗ADK-Rust如何实现CodeAct
CodeAct 在 ADK-Rust 运行时内工作。
CodeActAgent 旁边是代理类型 LlmAgent。你给它一个模型，一个 CodeRuntime和 Rust 工具。然后，您可以通过其他 ADK-Rust 代理使用的相同 Runner、会话、事件、回调、授权和输出系统来运行它。
1. 型号
选择任何能够生成可靠代码的 ADK-Rust 模型提供商。
2.CodeRuntime
使用 Monty 支持的 Python 运行时或实现与语言无关的 CodeRuntime 特征。
3.Rust工具
注册类型工具。该脚本只能访问为该调用提供的工具。
4.Runner
使用用户和会话运行代理，然后使用正常类型的 ADK-Rust 事件。
5. 会议
当批准或长时间运行的工具暂停程序时保留检查点。
6. 控制
应用确认、重试、超时、回调、护栏和验证输出。
最快的工作启动
首先运行签入的示例。
它使用确定性模型、真正的 Monty Python 解释器、两个 Rust 工具、内存中会话和 ADK-Rust Runner。不需要模型 API 密钥。
Monty 适配器当前是实验性 Git 依赖项，需要 Rust 1.95+，因此该示例带有自己的工具链文件。
git clone https://github.com/zavora-ai/adk-rust.git
cd adk-rust/examples/codeact_monty_agent
# This example selects Rust 1.95 automatically.
cargo run=== ADK-Rust CodeAct × Monty (Python) example ===
[cart_assistant]
{
"lines": 3,
"region": "CA",
"subtotal": 132.0,
"tax_rate": 0.0725,
"total": 141.57,
"user": "u-42"
}
Done.建筑
该脚本在代理系统内部运行。
该模型提出了 executable 逻辑。 CodeRuntime 控制逻辑的前进方式。 ADK-Rust 拥有应用程序看到的每个外部操作、持久检查点和事件。
型号
使用运行时简报和可用于此调用的工具编写脚本。
CodeRuntime
逐步运行脚本并公开调用、完成、stdout 和脚本错误。
ADK-Rust主机
使用授权和上下文执行工具，保留状态并传输最终结果。
源码支持的 execution 演练
案例研究：在 CodeAct 回合内为购物车定价。
这遵循 ADK-Rust 存储库中的确定性 CodeAct × Monty 示例。选择每个边界以查看系统的哪一部分正在工作以及下一部分可以看到哪些内容。
Runner
请求输入ADK-Rust
Runner 在 CodeAct 代理开始之前附加用户、会话、调用上下文、回调和可用工具。
可见信号
购物车 u-42 的总金额是多少（包括加州税）？
选择合适的代理形状
CodeAct 有特定的工作。
当模型可以更清晰地将工作表达为程序时使用它。 ADK-Rust 还提供用于对话工具使用和完整软件开发环境的代理形状。
LlmAgent
以对话方式选择和调用工具。
最适合： 问题、对话、孤立的业务行为和自然的切换。
模型 → 工具 → 模型
CodeActAgent
在一个 executable 计划中组合工具和逻辑。
最适合： 分析、数据转换、批处理工作、计算和条件流。
模型 → 脚本 ↔ 工具 → 结果
CodingAgent
在软件开发工具中工作。
最适合： 存储库编辑、shell 命令、构建、测试、补丁和编码代理协议。
代理 ↔ 工作区 + shell
Monty运行时
给生成的代码一个清晰的操作边界。
ADK-Rust 的当前 Python 适配器在进程内运行 Monty。主机在 execution 开始之前决定脚本可以读、写、知道和消耗什么。
Monty 仍处于实验阶段。目前它是固定的 Git 依赖项，需要 Rust 1.95+。该适配器位于其自己的板条箱中，直到 Monty 在 crates.io 上可用为止。
默认沙箱
没有文件系统访问权限和空环境。网络和子流程操作没有 Monty 表面。
显式挂载
将选定的主机目录映射到虚拟路径，并为每个目录选择只读或读写访问权限。
资源限制
为每次进展设置时间上限和内存上限。序列化延续在恢复时保留这些限制。
一种工具形式
脚本调用 call_tool(name, args)。精确命名的参数在序列化后仍然存在，并集中绑定在 ADK-Rust 中。
受控环境
仅公开任务所需的环境值。主机进程的秘密永远不会自动继承。
可见的故障
语法错误和异常作为可修复的脚本反馈返回到模型；主机运行时故障停止运行。
耐用 execution
暂停的程序可以成为持久代理状态。
确认门控和长时间运行的工具可能需要请求在答案存在之前结束。 CodeAct 快照暂停的解释器、其转录本以及对会话的挂起调用，以便另一个调用可以从同一行代码继续。
之前保存
在允许运行外部工具之前保留延续。
解决
执行、批准、拒绝或等待待处理的工具结果。
之后保存
保留返回的值，以便恢复不会重复已完成的调用。
简历
加载检查点并从其调用边界继续执行相同的脚本。
开发商责任： 在外部副作用之后但在保存后检查点之前发生的崩溃可能会导致该工具再次运行。为非幂等工具提供幂等密钥或另一个重复操作防护。
实施
四部分定义了完整的代理。
选择一个模型，提供一个CodeRuntime，注册脚本可能调用的工具，并通过正常的ADK-Rust Runner运行代理。
use std::sync::Arc;
use adk_agent::codeact::CodeActAgent;
use adk_codeact_monty::MontyRuntime;
let runtime = MontyRuntime::builder()
.environ_var("CART_USER", "u-42")
.environ_var("TAX_REGION", "CA")
.system_clock(true)
.build();
let agent = CodeActAgent::builder()
.name("cart_assistant")
.model(model)
.runtime(Arc::new(runtime))
.instruction("Price the cart by writing Python.")
.tool(Arc::new(fetch_cart))
.tool(Arc::new(tax_rate))
.output_key("priced_cart")
.build()?;