用于 ADK 的 Agent Runtime 代码执行工具¶
Agent Runtime 代码执行 ADK 工具提供了一种低延迟、高效的方法来使用 Google Cloud Agent Runtime 服务运行 AI 生成的代码。该工具专为快速执行而设计，针对智能体工作流进行了优化，并使用沙箱环境来提高安全性。代码执行工具允许代码和数据在多个请求之间持久化，从而实现复杂的多步编码任务，包括：
- 代码开发和调试：创建智能体任务，对代码版本进行测试，并在多个请求中进行迭代。
- 带数据分析的代码执行：上传最大 100MB 的数据文件，并运行多次基于代码的分析，而无需在每次代码运行时重新加载数据。
该代码执行工具是 Agent Runtime 套件的一部分，但你无需将智能体部署到 Agent Runtime 即可使用它。你可以在本地或与其他服务一起运行你的智能体并使用此工具。有关 Agent Runtime 中代码执行功能的更多信息，请参阅 Agent Runtime 代码执行文档。
使用该工具¶
使用 Agent Engine 代码执行工具需要你在将该工具与 ADK 智能体配合使用之前，先使用 Google Cloud Agent Engine 创建一个沙箱环境。
Using the Agent Runtime Code Execution tool requires that you create a sandbox environment with Google Cloud Agent Runtime before using the tool with an ADK agent.
要将代码执行工具与你的 ADK 智能体配合使用：
- 按照 Agent Runtime代码执行快速入门中的说明创建代码执行沙箱环境。
- 创建一个 ADK 智能体，并配置访问沙箱环境所在的 Google Cloud 项目的设置。
- 以下代码示例显示了一个配置为使用代码执行器工具的智能体。将
SANDBOX_RESOURCE_NAME替换为你创建的沙箱环境资源名称。
from google.adk.agents.llm_agent import Agent
from google.adk.code_executors.agent_engine_sandbox_code_executor import AgentEngineSandboxCodeExecutor
root_agent = Agent(
model="gemini-flash-latest",
name="agent_engine_code_execution_agent",
instruction="你是一个得力的智能体，可以编写并执行代码来回答问题和解决问题。",
code_executor=AgentEngineSandboxCodeExecutor(
sandbox_resource_name="SANDBOX_RESOURCE_NAME",
),
)
有关 sandbox_resource_name 值预期格式以及备选参数 agent_engine_resource_name 的详细信息，请参阅配置参数。有关更高级的示例（包括推荐的系统指令），请参阅高级示例或完整的智能体代码示例。
工作原理¶
AgentEngineCodeExecutor 工具在智能体任务期间维护单个沙箱，这意味着沙箱状态在 ADK 工作流会话的所有操作中是持久的。
- 沙箱创建： 对于需要代码执行的多步任务，Agent Runtime 会使用指定的语言和机器配置创建一个沙箱，隔离代码执行环境。如果未预先创建沙箱，代码执行工具将使用默认设置自动创建一个。
- 带持久化的代码执行： AI 生成的工具调用代码被流式传输到沙箱，然后在隔离环境中执行。执行后，沙箱保持活跃状态，用于同一会话中的后续工具调用，为同一智能体的下一次工具调用保留变量、导入的模块和文件状态。
- 结果检索： 收集标准输出和任何捕获的错误流，并传回给调用智能体。
- 沙箱清理： 智能体任务或对话结束后，智能体可以显式删除沙箱，或依赖创建沙箱时指定的 TTL 功能。
主要优势¶
- 持久状态： 解决需要在多次工具调用之间传递数据操作或变量上下文的复杂任务。
- 目标隔离： 提供健壮的进程级隔离，确保工具代码执行安全且轻量。
- Agent Runtime 集成： 紧密集成到 Agent Runtime 的工具使用和编排层中。
- 低延迟性能： 专为速度而设计，允许智能体高效执行复杂的工具使用工作流，而不会产生显著开销。
- 灵活的计算配置： 创建具有特定编程语言、处理能力和内存（memory）配置的沙箱。
系统要求¶
要成功将 Agent Runtime 代码执行工具与 ADK 智能体配合使用，必须满足以下要求：
- 已启用 Agent Platform API 的 Google Cloud 项目
- 智能体的服务账户需要 roles/aiplatform.user 角色，该角色允许其：
- 创建、获取、列出和删除代码执行沙箱
- 执行代码执行沙箱
配置参数¶
Agent Runtime 代码执行工具有以下参数。你必须设置以下资源参数之一：
sandbox_resource_name：指向现有沙箱环境的资源路径，供每次工具调用时使用。预期字符串格式如下：agent_engine_resource_name：Agent Runtime 资源名称，工具将在该资源下创建沙箱环境。预期的字符串格式如下：
你可以使用 Google Cloud Agent Runtime 的 API 通过 Google Cloud 客户端连接单独配置 Agent Runtime 沙箱环境，包括以下设置：
- 编程语言：包括 Python 和 JavaScript。
- 计算环境：包括 CPU 和内存（memory）大小。
有关连接 Google Cloud Agent Runtime 和配置沙箱环境的更多信息，请参阅 Agent Runtime 代码执行快速入门。
高级示例¶
以下示例代码展示了如何在 ADK 智能体中实现代码执行器工具。此示例包含一个 base_system_instruction 子句，用于设置代码执行的操作指南。此指令子句是可选的，但强烈建议使用它以获得该工具的最佳效果。
from google.adk.agents.llm_agent import Agent
from google.adk.code_executors.agent_engine_sandbox_code_executor import AgentEngineSandboxCodeExecutor
def base_system_instruction():
"""返回数据科学智能体的系统指令。"""
return """
# 指南
**目标：** 帮助用户实现他们的数据分析目标，**重点是避免假设并确保准确性。** 实现该目标可能涉及多个步骤。当你需要生成代码时，你**不需要**一次性解决目标。一次只生成下一步。
**代码执行：** 提供的所有代码片段将在沙箱环境中执行。
**持久化：** 所有代码片段都会执行，且变量会保留在环境中。你**永远不需要**重新初始化变量。你**永远不需要**重新加载文件。你**永远不需要**重新导入库。
**输出可见性：** 始终打印代码执行的输出以可视化结果，特别是用于数据探索和分析。例如：
- 要查看 pandas.DataFrame 的形状，请执行：
```tool_code
print(df.shape)
```
输出将呈现给你如下：
```tool_outputs
(49, 7)
```
- 显示数值计算的结果：
```tool_code
x = 10 ** 9 - 12 ** 5
print(f'{{x=}}')
```
输出将呈现给你如下：
```tool_outputs
x=999751168
```
- 你**绝不**应该自己生成 ```tool_outputs。
- 接着你可以使用此输出来决定下一步。
- 只需打印变量（例如 `print(f'{{variable=}}')`）。
**无假设：** **重要的是，避免对数据性质或列名进行假设。** 仅基于数据本身得出结论。始终根据从 `explore_df` 获得的信息来指导你的分析。
**可用文件：** 仅使用可用文件列表中指定的文件。
**提示词中的数据：** 某些查询直接在提示词中包含输入数据。你必须将该数据解析为 pandas DataFrame。**始终**解析所有数据。**永远不要**编辑提供给你的数据。
**可回答性：** 某些查询可能无法使用现有数据回答。在这种情况下，向用户说明你无法处理其查询的原因，并建议需要什么类型的数据来满足他们的请求。
"""
root_agent = Agent(
model="gemini-flash-latest",
name="agent_engine_code_execution_agent",
instruction=base_system_instruction() + """
你需要结合数据和对话上下文来帮助用户解答他们的查询。
你的最终答案应总结与用户查询相关的代码和代码执行情况。
你应该包含所有数据片段来回答用户查询，例如来自代码执行结果的表格。
如果你无法直接回答问题，应遵循上述指南来生成下一步。
如果问题可以直接回答而无需编写任何代码，你应直接回答。
如果你没有足够的数据来回答问题，应向用户请求澄清。
你**绝不**应该自己安装任何包（如 `pip install ...`）。
绘制趋势图时，应确保按 x 轴对数据进行排序。
""",
code_executor=AgentEngineSandboxCodeExecutor(
# 如果你已有沙箱资源名称，请替换。
sandbox_resource_name="SANDBOX_RESOURCE_NAME",
# 如果未设置 sandbox_resource_name，则替换用于创建沙箱的 Agent Engine 资源名称：
# agent_engine_resource_name="AGENT_ENGINE_RESOURCE_NAME",
),
)
有关使用此示例代码的 ADK 智能体的完整版本，请参阅 agent_engine_code_execution 示例。