使用 Agent Engine 的代码执行工具¶
Agent Engine 代码执行 ADK 工具提供了一种低延迟、高效率的方法，使用Google Cloud Agent Engine服务运行 AI 生成的代码。此工具专为快速执行而设计，适用于智能体工作流，并使用沙箱环境以提高安全性。代码执行工具允许代码和数据在多个请求中持续存在，实现复杂的多步骤编码任务，包括：
- 代码开发和调试： 创建对代码版本进行测试和在多个请求中迭代的智能体任务。
- 带数据分析的代码： 上传最大 100MB 的数据文件，并运行多个基于代码的分析，而无需在每次代码运行时重新加载数据。
此代码执行工具是 Agent Engine 套件的一部分，但你不需要将你的智能体部署到 Agent Engine 来使用它。你可以在本地运行你的智能体或使用其他服务并使用此工具。有关 Agent Engine 中的代码执行功能的更多信息，请参阅 Agent Engine Code Execution文档。
预览版发布
Agent Engine 代码执行功能是预览版发布。有关更多信息，请参阅发布时间表说明。
使用该工具¶
使用 Agent Engine 代码执行工具需要你在将工具与 ADK 智能体一起使用之前，使用 Google Cloud Agent Engine 创建一个沙箱 环境。
要在你的 ADK 智能体中使用代码执行工具：
- 遵循 Agent Engine代码执行快速入门中的说明创建代码执行沙箱环境。
- 创建一个 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-2.5-flash",
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 Engine 使用指定的语言和机器配置创建沙箱，隔离代码执行环境。如果没有预创建沙箱，代码执行工具将使用默认设置自动创建一个。
- 持久化代码执行： 工具调用的 AI 生成代码被流式传输到沙箱，然后在隔离环境中执行。执行后，沙箱在同一会话中的后续工具调用中保持活动状态，为同一智能体的下一次工具调用保留变量、导入的模块和文件状态。
- 结果检索： 标准输出和捕获的错误流被收集并传回给调用智能体。
- 沙箱清理： 一旦智能体任务或对话结束，智能体可以显式删除沙箱，或依赖于创建沙箱时指定的沙箱 TTL 功能。
主要优势¶
- 持久状态： 解决数据操作或变量上下文必须在多个工具调用之间传递的复杂任务。
- 目标隔离： 提供强大的进程级隔离，确保工具代码执行安全且保持轻量级。
- Agent Engine 集成： 紧密集成到 Agent Engine 工具使用和编排层。
- 低延迟性能： 专为速度而设计，允许智能体高效执行复杂的工具使用工作流，而不会产生显著开销。
- 灵活的计算配置： 使用特定的编程语言、处理能力和内存配置创建沙箱。
系统要求¶
要成功将 Agent Engine 代码执行工具与你的 ADK 智能体一起使用，必须满足以下要求：
- 启用了 Vertex API 的 Google Cloud 项目
- 智能体的服务账号需要 roles/aiplatform.user 角色，该角色允许它：
- 创建、获取、列出和删除代码执行沙箱
- 执行代码执行沙箱
配置参数¶
Agent Engine 代码执行工具具有以下参数。你必须设置以下资源参数之一：
sandbox_resource_name: 一个沙箱资源路径，指向一个现有沙箱环境，它在每次工具调用时使用。预期的字符串格式如下：agent_engine_resource_name: Agent Engine 资源名称，工具在其中创建沙箱环境。预期的字符串格式如下：
你可以使用 Google Cloud Agent Engine 的 API 通过 Google Cloud 客户端连接单独配置 Agent Engine 沙箱环境，包括以下设置：
- 编程语言， 包括 Python 和 JavaScript
- 计算环境，包括 CPU 和内存大小
有关连接到 Google Cloud Agent Engine 和配置沙箱环境的更多信息，请参阅 Agent Engine代码执行快速入门。
高级示例¶
以下示例代码展示了如何在 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():
"""Returns: data science agent 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-2.5-flash",
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_resource_name="AGENT_ENGINE_RESOURCE_NAME",
),
)
有关使用此示例代码的 ADK 智能体的完整版本，请参阅agent_engine_code_execution 示例。