Skip to content

ADK 的环境工具集

Supported in ADKPython v1.29.0Experimental

某些类型的任务，特别是编码和文件操作，需要智能体与能够运行代码并对跨多个智能体请求持久化的文件进行操作的计算环境进行交互。ADK 的 EnvironmentToolset 类允许智能体与环境交互以执行文件操作和 shell 命令。环境工具集被设计为一个通用框架，用于在 ADK 智能体中配置和使用本地或远程执行环境。ADK 提供了一个 LocalEnvironment 实现，用于与环境工具集框架配合使用。

实验性

环境工具集功能是实验性的，可能会更新。我们欢迎你的 反馈！

开始使用

通过将带有 LocalEnvironment 实例的 EnvironmentToolset 添加到智能体的工具中，启用本地环境交互。

from google.adk import Agent
from google.adk.environment import LocalEnvironment
from google.adk.tools.environment import EnvironmentToolset

root_agent = Agent(
    model="gemini-flash-latest",
    name="my_agent",
    instruction="""
    你是一个有用的 AI 助手，可以使用本地环境
    执行命令和文件输入/输出。请遵循环境的规则
    和用户的指令。
    """,
    tools=[
        EnvironmentToolset(
            environment=LocalEnvironment(),
        ),
    ],
)

有关完整的实现示例，请参见 本地环境示例。

与智能体一起尝试

你可以通过与配置了环境工具集的智能体交互，提供需要文件操作和命令执行的提示词来测试。请在与智能体的交互式会话中尝试以下提示：

Write a Python file named hello.py to the working directory
that prints 'Hello from ADK!'. Then read the file to verify
its contents, and finally execute it using a command.

基于这些指令，智能体执行以下操作：

  • 写入文件：智能体创建一个内容为 "Hello from ADK!" 的 hello.py 文件。
  • 读取文件：智能体读取 hello.py 文件并验证其内容。
  • 执行：智能体运行 hello.py 文件并返回输出。

LocalEnvironment

LocalEnvironment 类是 ADK 提供用于与 Environment Toolset 配合使用的环境实现。此环境提供以下能力：

  • 本地执行：使用 Python asyncio 子进程在本地机器上直接运行 shell 命令和脚本。
  • 文件操作：在指定的工作目录中创建、读取和修改文件。
  • 自定义：为智能体的工作区配置自定义环境变量和工作目录。
  • 框架兼容性：适用于 ADK 1.0 和 ADK 2.0 框架版本，包括基于图的工作流。

配置选项

LocalEnvironment 类支持以下参数：

  • working_dir：（可选）智能体执行文件操作和命令的目录。设置工作目录意味着智能体运行后生成的任何文件仍然可访问。有关更多详细信息，请参见文件持久性。
  • env_vars：（可选）要设置给执行上下文的环境变量字典。

以下代码示例展示了如何为 LocalEnvironment 对象设置这些选项：

local_environment=LocalEnvironment(
    working_dir="/tmp/my_agent_workspace",
    env_vars={"PORT": "8080", "LOG_LEVEL": "DEBUG"},
)

文件操作

LocalEnvironment 实现包括以下智能体可在本地计算环境中运行的工具：

  • ReadFile：基于智能体指令读取现有文本文件。
  • EditFile：基于智能体指令编辑现有文本文件。
  • WriteFile：基于智能体指令创建新的文本文件。
  • Execute：基于智能体指令执行终端命令，包括运行安装程序、shell 脚本和程序代码。

危险：可能导致数据丢失和代码执行

在本地环境中执行终端命令可能导致数据丢失，并影响该环境中代码和应用程序的执行。请谨慎操作，并考虑在允许智能体更改文件和执行命令之前实施人工权限检查。

使用 LocalEnvironment 执行的命令使用 asyncio.create_subprocess_shell，确保智能体在长时间运行的任务期间保持响应。

文件持久性

使用 LocalEnvironment 生成的文件和文件输出默认放置在临时目录中。当智能体关闭时（例如退出 ADK Web 会话），该目录会被删除。但是，如果你为环境设置了 工作目录，则写入该目录的任何文件在智能体关闭后不会被删除。

提示： 如果你希望对文件在智能体会话之间如何进行持久化拥有更多控制，请使用 Artifacts 和 Artifact 服务来向环境上传和下载文件。

自定义环境

EnvironmentToolset 架构被设计为可扩展的，因此你可以构建自己的自定义环境，包括远程环境。我们鼓励你使用 BaseEnvironment 类为此功能构建执行环境。你可以查看 LocalEnvironment 实现的代码以帮助你入门。