# AI Studio 试验场中的智能体

Google AI Studio Playground 提供了一个可视化的原型界面，并学习如何构建托管智能体，而无需创建和编写 API 调用。

要开始使用，请导航至 **游乐场** Google AI Studio导航面板中的选项卡，并将切换开关切换为 **智能体**.

## 预建模板  {% #pre-built-templates %}

该 **智能体** 选项卡具有一系列模板，通过设置工具和环境配置来预先配置基础 Antigravity 智能体。所有模板都是开源的并在 [谷歌双子座/gemini-managed-agents-templates](https://github.com/google-gemini/gemini-managed-agents-templates/) 存储库。探索这些模板是学习如何构建和构建您自己的托管智能体的好方法。

例如，当您选择 AI Radio 模板时，它会启用所有允许的工具，并链接专门的 `AGENTS.md` 广播节目制作的文件和技巧。您可以在 Playground UI 的以下位置查看这些设置 **环境** 部分，通过单击 **来源** 按钮。

重要提示：当您运行这些模板时，沙箱内的智能体可以访问 Gemini API。它将使用您配置的 API 密钥执行呼叫，这可能会在您的帐户上产生额外的 token 费用。参见 [安全与成本管理](/docs/aistudio-agents#safety-and-cost-management) 部分了解更多详细信息。

## 工具配置  {% #tool-configuration %}

在 Playground 中的智能体设置下，您可以切换对以下内置工具的访问：

* **Google 搜索：** 访问开放网络获取实时信息事实依据。

* **网址上下文：** 获取并解析特定网页 URL 的文本内容。

* **代码执行：** 直接在隔离的沙箱环境中运行 Bash 和 Python 命令。

* **文件系统工具：** 读取、写入、列出和删除工作区中的文件。

## 环境配置  {% #environment-configuration %}

托管智能体在安全的临时 Linux 沙箱（环境）中运行，提供操作所需的工作空间和工具。要了解更多信息，请参阅 [托管智能体环境](/docs/agent-environment) 指导。

### 控制智能体行为  {% #controlling-agent-behavior %}

智能体的行为、角色和功能主要由其环境中存在的文件决定。 智能体自动检测并加载来自特殊的配置 `.agents` 文件夹：

* **`AGENTS.md`**：预加载到智能体的上下文中以定义系统指令和角色。
* **`SKILL.md`**：位于相应的技能文件夹下（例如， `.agents/skills/my-skill/SKILL.md`）来定义特定的功能和工作流程。

### 配置环境  {% #provisioning-the-environment %}

您可以在开始会话之前通过将文件挂载到环境来配置智能体使用的环境。您可以通过安装源来构建新环境，也可以恢复以前的环境：

* **创造新环境**，点击 **添加来源** 在环境设置面板中，然后从以下源类型中进行选择：

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
来源类型
{% /doc-cell %}

{% doc-cell %}
说明
{% /doc-cell %}

{% doc-cell %}
安装路径
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**内联文件**
{% /doc-cell %}

{% doc-cell %}
将配置文件、模拟数据集或实用程序脚本（最多 100KB）直接写入或粘贴到 Playground UI 中。
{% /doc-cell %}

{% doc-cell %}
用户定义的目标路径（例如， `/workspace/scripts/parser.py`).
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**Google Cloud 存储**
{% /doc-cell %}

{% doc-cell %}
安装公共或私有 Cloud Storage 存储桶。

专用存储桶需要标准 OAuth 2.0 承载 token。有关更多信息，请参阅 [私人来源](/docs/agent-environment#private-sources).
{% /doc-cell %}

{% doc-cell %}
映射 GCS 存储桶路径（例如， `gs://your-bucket-name/data/`）到工作区目录（例如， `/workspace/data/`).
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**GitHub 存储库**
{% /doc-cell %}

{% doc-cell %}
克隆公共或私有代码库。

私有存储库需要使用 GitHub 个人访问token (PAT) 进行基本身份验证。有关更多信息，请参阅 [私人来源](/docs/agent-environment#private-sources).
{% /doc-cell %}

{% doc-cell %}
直接克隆到 `/workspace/` （通常在 `/workspace/<repo-name>`).
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

* **恢复之前的环境**，你可以 [重用现有环境 ID](/docs/aistudio-agents#reusing-an-existing-environment-id) 克隆并分叉其确切状态。

### 重用现有环境 ID  {% #reusing-an-existing-environment-id %}

如果您已经花时间设置沙盒环境，则不必从头开始。要使用现有环境：

1. 转到 AI Studio 中的“环境”面板并切换 **类型** 到 **现有**
1. 输入 **环境ID** (e.g., `env_abc123`)

有关更多信息，请参阅 [配置环境](/docs/agent-environment#configure-an-environment)。您还可以从 UI 中的“环境”选项卡检索当前会话的环境 ID。

一旦您将第一条消息发送到智能体，该会话的环境配置就会固定下来。当交互正在运行时，您无法挂载新源或修改网络允许列表。

## 下载环境  {% #download-the-environment %}

创建环境后，您可以随时使用以下命令下载环境快照 **下载** AI Studio Playground 的环境设置中的按钮，以 tarball 形式检索环境文件。

## 安全与成本管理  {% #safety-and-cost-management %}

### 管理代币消耗  {% #managing-token-consumption %}

与产生单个输出的标准聊天请求不同，Antigravity 智能体执行自主工作流程。它计划、运行代码、观察结果和迭代。这意味着单个提示可能会导致无限制的 token 消耗。

为了管理成本， **在提示中提供明确的终止条件并缩小智能体的任务范围**。一个很好的例子是这样的提示 *查看拉取请求并在生成 Markdown 摘要后停止。不要尝试自己编写修复程序*.

重要提示：如果您发现智能体运行了很长时间或者没有朝着正确的方向运行（通过观察其思想和工具调用），您可以使用 **停止** 按钮可随时停止智能体，避免不必要的token消耗。

### 额外费用  {% #additional-costs %}

默认情况下，Playground 上的所有智能体模板都可以访问 Gemini API 服务，并且可以从环境中进行 API 调用以满足请求。这些可能会产生额外费用，这些费用不会反映在 token 消耗中。

同样，如果您添加其他外部服务，智能体可能会因代表您调用这些服务而产生额外费用。

### 网络允许列表  {% #network-allow-list %}

默认情况下，在 AI Studio 上，来自智能体沙箱环境内的所有出站网络请求都受到严格控制和限制，以确保安全。要授予您的智能体访问外部 API、Web 服务或包管理器的能力，您必须显式声明它们：

1. 转到 AI Studio 中的环境面板。
1. 选择 **规则** 旁边的按钮 **网络**.
1. 在 **网络配置** 面板，单击 **添加到白名单** 并填写相关详细信息：*  **域名限制：** 智能体的虚拟机只能访问添加到列表中的特定域或通配符模式。例如，您可以输入精确的域，例如 `api.github.com` 或广泛的模式，如 `*.googleapis.com`.

* **添加 HTTP 标头和token注入：** 使用 **添加 HTTP 标头**
  用于安全地注入特定域所需凭据（例如 API token）的选项。这些凭证安全地通过出口代理，并且永远不会作为原始文本直接暴露在智能体沙箱内。

将域添加到白名单时请务必小心谨慎。授予智能体对经过身份验证的服务的访问权限意味着它可以代表您行事，如果不仔细监控，可能会导致意外的操作。

{% callout type="note" %}
**重要：**

* 默认情况下，通过 AI Studio Playground 进行的所有智能体调用都会启用经过身份验证的 Gemini API（使用链接的 API 密钥）。
* 当您使用API时，网络默认是打开的。参见 [API 文档](/docs/agent-environment#network-configuration) 了解详情。
{% /callout %}

### 凭证最佳实践  {% #credentials-best-practices %}

如果您的工作流程需要智能体通过外部服务进行身份验证，则您负责配置这些凭据并确定其范围。请遵循以下指南来降低风险：

* **使用最低权限凭据：** 仅使用智能体所需的权限创建服务帐户或 API 密钥。避免传递具有广泛或管理访问权限的凭据。

* **更喜欢短命的 token：** 如果可能，请使用有时间限制的凭证或过期的 token，而不是长期存在的 API 密钥。

* **假设完全访问：** 智能体可以使用它有权访问的任何凭证来完成您赋予它的任务。仅提供您愿意授予其完整访问范围的凭据。

* **定期轮换凭证：** 像处理任何编程凭证一样对待与智能体共享的凭证；定期轮换他们。

### 连接外部工具和 API  {% #connecting-external-tools-and-apis %}

您可以连接外部工具和API（例如Model Context Protocol / MCP服务器）来扩展智能体的功能。这样做时：

* 仅连接来自您信任的来源的工具。恶意或编写不当的工具可能会泄露数据或执行意外操作。

* 使用您的用例所需的最低权限配置工具。如果工具支持只读模式，则首选该模式，除非严格需要写入。

* 在将工具连接到生产数据源之前，请根据示例或合成数据对其进行测试，以验证智能体按预期使用它。

### 人为监督  {% #human-oversight %}

智能体可以高度自主地推理、规划和执行多步骤工作流程。虽然这很强大，但也意味着您应该进行适当的监督；特别是对于修改数据或与外部系统交互的任务。

在部署之前始终验证关键输出，例如生成的代码、数据转换或配置更改。
