Gemini API 中的托管代理：实践教程

Gemini API 中的托管代理费用是多少？

Gemini 托管代理的定价涉及多个组成部分，因此很难给出精确的成本估算。费用主要由四个因素驱动：

1. 模型使用（Token）：根据底层 Gemini 模型处理的输入与输出 token 数量计费。请注意，其中包括中间结果所产生的 token。例如，如果代理生成了一个用于构建报告的 Python 脚本，该脚本所需的 token 也会计费。
2. 基础设施与平台费用：托管代理在 Google 的一体化环境中运行，使用平台工具（如 Vertex AI Agent Builder）来管理与部署代理会产生服务费用。
3. 上下文缓存（Context Caching）：如果代理频繁复用相同数据，托管代理可以使用上下文缓存。与标准 token 计价相比，这通常能显著降低成本。
4. 锚定（Grounding）：如果代理使用 Google 的锚定服务，如 Google 搜索或 Google 地图，这些会单独计费，通常是先有一定免费请求配额，之后按每 1,000 次查询计费（通常约 $14/1,000 次）。 

在本教程中，我们将基于 antigravity-preview-05-2026 代理构建一个代理，该代理由d Gemini 3.5 Flash 提供支持。Gemini 3.5 Flash 的 token 成本如下：

如何在 Gemini API 中构建托管代理

本指南将使用 Gemini API 和 Python 构建一个托管代理。由于托管代理是近期发布且处于测试阶段，请注意某些实现细节可能会变化。

本教程中我们编写的所有代码都存放在 这个 GitHub 仓库中，我们也将用它与数据分析师代理共享数据。

API 设置

要创建 AI 密钥，请前往 Google AI Studio，点击右上角的“Create API Key”。

API 密钥需要与一个 Google Cloud 项目关联。您可以选择现有项目或创建新项目。这里我创建了一个名为 gemini-managed-agents 的项目。

创建密钥后，复制它。然后在我们将要创建代理的文件夹中创建一个名为 .env 的文件，并按如下格式粘贴：

GEMINI_API_KEY=<paste_your_api_key_here>

在关闭 Google AI Studio 之前，需要为刚创建的 API 密钥设置结算。否则我们的请求会被拒绝，因为 Google 无法向我们收费。要设置结算，点击“Set up billing”按钮。

Python 环境设置

我们将使用 Anaconda 来为本项目设置 Python 环境。使用以下命令创建环境：

conda create --name gemini_agents python=3.12 -y

这会创建一个名为 gemini_agents 的环境，使用 Python 3.10 版本。参数 -y 用于在创建环境的过程中对所有问题自动回答“yes”。

接下来激活该环境：

conda activate gemini_agents

最后安装必要依赖。如下所示：

pip install google-genai requests python-dotenv

与托管代理创建一次基础交互

我们已经完成首次运行代理所需的全部设置。这个首个代理不会做太多事，它只会安装 matplotlib 并报告安装的版本。

以下是我们如何与托管代理交互的分步说明（完整代码见仓库中的 simple_interaction.py 脚本）：

首先，我们导入必要的包，并从之前创建的 .env 文件中加载 API 密钥：

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

接着，我们初始化 Gemini 客户端，并与当前名为 antigravity-preview-05-2026 的基础代理创建一次交互，要求其安装 matplotlib：

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

最后，我们通过查看 status、environment_id 和 output_text 属性获取代理输出：

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

结果如下：

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

沙盒生命周期状态

在上述示例中，我们展示了托管代理交互的环境标识符：

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

该值很重要，它代表代理执行所在环境的标识符。代理交互存储在一个短暂存在的环境中，自最后一次活动起最多保留 7 天，之后会被删除。

下图展示了代理在一次交互期间所执行沙盒的生命周期。

在环境未被删除期间，我们可以使用环境标识符访问它并进行进一步交互。

执行多次交互

此示例展示如何执行多次交互。完整代码见仓库中的 multiple_interactions.py 文件。

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

请注意，在第二次交互中我们添加了两个参数：

• previous_interaction_id：上一次交互的标识符，使代理了解会话历史。

• environment：环境标识符，用于告知代理应在哪个沙盒中执行。

与代理共享文件

如果无法让代理访问数据，就无法构建数据分析师代理。与代理共享数据有几种方式：

• 内联数据：将文件内容加载为字符串，并在交互过程中发送。
• 托管文件：将数据托管在公共 URL，并提供给代理下载。
• GitHub 仓库：向代理提供公开的 GitHub 仓库 URL。
• Google Cloud 存储桶：将文件托管在 Google Cloud Storage 存储桶中，并配置项目使代理可访问该存储桶。

本文不逐一展开所有方案。我们将演示如何通过将本地文件加载为字符串来发送内联数据，以及如何共享一个 GitHub 仓库。前者适合共享较小的本地文件（每个文件最多 1 MB，所有文件合计最多 2 MB），而后者更适合共享较大的文件，如数据集。

共享内联数据

以下示例展示如何提供内联数据（完整代码见 inline_example.py）：

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

数据通过 environment 配置中的 sources 参数提供。target 定义数据将存储于代理环境中的位置。文件应位于 workspace 文件夹内。本例中将是名为 number.txt 的文件。 

content 参数提供文件内容。对于 inline 源，它只是一个字符串，在此我们通过 utils.py 文件中的 read_text_file() 函数读取。

共享 GitHub 仓库

要共享更大的文件，我们可以提供一个 GitHub 仓库 URL。如下所示：

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

在上述示例中，URL 为 https://github.com/fran-aubry/gemini-agents-tutorial 的仓库被克隆到代理工作区内名为 repository 的文件夹中。

下载代理的环境

我们已经了解了如何与托管代理交互以及如何向这些代理提供文件。要创建我们的数据分析师代理，最后需要学习的是如何下载代理的环境。这是为了使我们能够访问代理生成的图表和结果。

每个工作区都可以通过以下 URL 下载：

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

其中 <env_id> 应替换为我们希望下载的环境标识符。

下面是一个使用 requests 包下载归档的 Python 函数（该函数是我们创建的 utils.py 文件的一部分）：

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

构建数据分析师代理

本节我们将学习如何创建一个执行数据分析的代理。为测试该代理，我们将使用来自 Kaggle 的这个 Netflix 数据集，它也存放在我们仓库的 data 文件夹中。

在之前的所有示例中，我们始终与基础代理 antigravity-preview-05-2026 交互。此处我们将首先使用 client.agents.create() 函数创建一个代理。

创建代理

如下是创建代理的方法：

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

逐一解释各参数：

• id：定义代理名称，此处为 data-analyst。我们将在 client.interactions.create() 方法中使用该标识符，取代此前使用的 antigravity-preview-05-2026。 

• base_agent：要用作基础的代理。这意味着我们在 antigravity-preview-05-2026 之上构建一个代理。

• base_environment：与之前相同，它允许我们向代理提供文件。我们提供了两个特殊文件：.agents/AGENTS.md 和 .agents/skills/csv-aggregator/SKILL.md。这些文件用于定义代理的行为。AGENTS.md 定义代理的一般行为，而 SKILL.md 定义代理的一项特定技能。我们还向代理提供了该仓库，使其能够访问我们要分析的数据文件。

理解 AGENTS.md

该文件可视为系统提示。它充当代理的主要说明手册。我们应该用它清晰地定义代理的具体角色、主要目标以及在工作中需要遵守的边界。 

它同样是列出代理允许访问的特定工具或数据源，以及提供我们希望其沟通或处理任务范式示例的最佳位置。 

将这些说明简明且有条理地写入该文件，有助于代理准确理解应如何行为以及我们期望的结果。

该文件在代理环境中的位置应为 .agents/AGENTS.md。

理解 SKILL.md

技能文件用于为代理配备特定技能。一个代理可以拥有多个技能，每个技能应在 .agents/skills/<skill_name>/SKILL.md 中进行描述，将 <skill_name> 替换为技能名称。

技能文件的结构应为：

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

为作示例，我们为 data-analyst 代理配备了一个名为 csv-aggregator 的技能，定义见此处。当我们希望按某列对 CSV 的行进行分组并对另一列求和时，会用到该技能。 

以 Netflix 数据集为例，如果我们想知道观看量最高的剧集类型（genre），就需要按 Genre 列分组，并对 Viewership 列的值求和。该技能文件向代理解释了如何完成这一任务。

加载代理

由于代理是持久存在的，如果我们尝试重复创建同一个代理，会报错。基于此，我们在 utils.py 中创建了 load_or_create_agent() 函数。该函数会尝试创建代理，如果已存在，则使用 client.agents.load() 加载它。

整合与运行

现在我们已有一个数据分析师代理，是时候通过让它分析 Netflix 的类型（genres）来测试它了。 

我们像之前一样，先导入库、加载 API 密钥并初始化客户端：

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

然后使用 utils.load_or_create_agent() 函数创建（或在非首次运行脚本时加载）data-analyst 代理：

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

接下来我们就可以像之前一样与代理交互。唯一的区别是，在 agent 参数中，我们现在提供的是自己的代理，而非 antigravity-preview-05-2026。

我们首先让代理安装 matplotlib 包：

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

注意，由于环境已在代理层面配置好，我们无需再提供文件，因此只需提供字符串 ”remote”。

接着，我们让它使用 csv-aggregator 工具按类型分析 Netflix 数据，查看最受观看的类型：

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

请注意我们提供了上一次交互环境的标识符，以便代理能在其基础上继续工作。

最后，我们让代理执行在上一步创建的 genres.py 脚本来绘制图表（SKILL.md 文件指示代理创建该脚本）：

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

完成该交互后，图表应已生成。我们可以通过下载环境将其获取到本地：

utils.download_env(inter3.environment_id)

结果如下：

该代理交互的完整代码见 analyze_netflix_genres.py。

结语

能够通过一次 API 调用创建复杂代理，而无需依赖复杂的云计算基础设施来搭建沙盒，极具威力。这让我们能够轻松创建强大的代理，而不必担心这些代理的运行环境。

在本教程中，我们介绍了 Gemini 托管代理的基础，但尚未创建真正复杂的代理。鼓励您继续深入探索，在此基础上不断构建，以提升技能。