Google AI Studio Playground 提供了一个可视化界面，用于制作原型并了解如何构建托管代理，而无需创建和编写 API 调用。
如需开始，请在 Google AI Studio 的导航面板中前往 Playground 标签页，然后将切换开关切换到 Agents 。
预构建模板
Agents 标签页提供了一系列模板，这些模板通过设置工具和环境配置来预配置基本 Antigravity 代理。所有模板都是开源的，并发布在 google-gemini/gemini-managed-agents-templates代码库下。探索这些模板是了解如何构建和构建自己的托管代理的好方法。
例如，当您选择 AI Radio 模板时，它会启用所有允许的工具，并关联一个专门的 AGENTS.md 文件和用于广播节目制作的技能。您可以在 Playground 界面中的环境 部分下点击来源 按钮，查看这些设置。
工具配置
在 Playground 的代理设置下，您可以切换对以下内置工具的访问权限：
- Google 搜索： 访问开放式网络，以获取实时信息。
- 网址上下文： 获取和解析特定网页网址的文本内容。
- 代码执行： 直接在隔离的沙盒环境中运行 Bash 和 Python 命令。
- 文件系统工具： 在工作区内读取、写入、列出和删除文件。
环境配置
托管代理在安全的临时 Linux 沙盒（环境）中运行，该沙盒提供代理运行所需的工作区和工具。如需了解详情，请参阅托管代理环境指南。
控制代理行为
代理的行为、角色和功能主要由其环境中存在的文件决定。代理会自动检测并从特殊的 .agents 文件夹加载配置：
AGENTS.md：预加载到代理的上下文中，以定义系统指令和角色。SKILL.md：位于相应技能文件夹（例如.agents/skills/my-skill/SKILL.md）下，用于定义特定功能和工作流。
预配环境
您可以在启动会话之前将文件挂载到环境中，以配置代理使用的环境。您可以通过挂载来源来构建新环境，也可以恢复之前的环境：
- 如需创建新环境，请在“环境设置”面板中点击添加来源，然后从以下来源类型中进行选择：
| 来源类型 | 说明 | 挂载路径 |
|---|---|---|
| 内嵌文件 | 直接在 Playground 界面中写入或粘贴配置文件、模拟数据集或实用脚本（最多 100 KB）。 | 用户定义的目标路径（例如 /workspace/scripts/parser.py）。 |
| Google Cloud Storage | 挂载公开或私有 Cloud Storage 存储分区。 私有存储分区需要标准的 OAuth 2.0 不记名令牌。如需了解详情，请参阅私有来源。 |
将 GCS 存储分区路径（例如 gs://your-bucket-name/data/）映射到工作区目录（例如 /workspace/data/）。 |
| GitHub 代码库 | 克隆公开或私有代码库。 私有代码库需要使用 GitHub 个人访问令牌 (PAT) 进行基本身份验证。如需了解详情，请参阅私有来源。 |
直接克隆到 /workspace/ 中（通常位于 /workspace/<repo-name> 下）。 |
- 如需恢复之前的环境，您可以重复使用现有的环境 ID来克隆和派生其确切状态。
重复使用现有环境 ID
如果您已经花费时间设置了沙盒环境，则无需从头开始。如需使用现有环境，请执行以下操作：
- 前往 AI Studio 中的“环境”面板，然后将类型 切换为现有
- 输入环境 ID （例如
env_abc123）
如需了解详情，请参阅配置环境。您还可以从界面中的“环境”标签页检索当前会话的环境 ID。
首次向代理发送消息后，该会话的环境配置将固定下来。在互动积极运行时，您无法挂载新来源或修改网络许可名单。
下载环境
创建环境后，您可以随时使用 AI Studio Playground 的“环境设置”中的下载 按钮下载环境快照，以检索环境文件作为 tarball。
安全和费用管理
管理令牌消耗量
与生成单个输出的标准聊天请求不同，Antigravity 代理执行的是自主工作流。它会规划、运行代码、观察结果并进行迭代。这意味着，单个提示可能会导致无限的令牌消耗量。
如需管理费用，请在提示中提供明确的终止条件，并为代理缩小任务范围 。一个很好的示例可能是这样的提示： 查看拉取请求，并在生成 Markdown 摘要后停止。 请勿尝试自行编写修复程序。
额外费用
默认情况下，Playground 上的所有代理模板都可以访问 Gemini API 服务，并且可以从环境中进行 API 调用以满足请求。这些可能会产生额外的费用，这些费用不会反映在令牌消耗量中。
同样，如果您添加其他外部服务，代理可能会代表您调用这些服务而产生额外的费用。
网络许可名单
默认情况下，在 AI Studio 中，对代理沙盒环境内的所有出站网络请求都受到严格控制和限制，以确保安全。如需授予代理访问外部 API、Web 服务或软件包管理器的能力，您必须明确声明它们：
- 前往 AI Studio 中的“环境”面板。
- 选择网络 旁边的规则 按钮。
- 在网络配置 面板中，点击添加到许可名单 ，然后填写相关详细信息：
- 网域限制： 代理的虚拟机只能访问添加到列表中的特定网域或通配符模式。例如，您可以输入确切的网域（如
api.github.com）或广泛的模式（如*.googleapis.com）。 - 添加 HTTP 标头和令牌注入： 使用添加 HTTP 标头 选项安全地注入特定网域所需的凭据（例如 API 令牌）。这些凭据会安全地通过出站代理，并且绝不会在代理沙盒内直接以原始文本的形式公开。
- 网域限制： 代理的虚拟机只能访问添加到列表中的特定网域或通配符模式。例如，您可以输入确切的网域（如
向许可名单添加网域时，请务必谨慎。授予代理对经过身份验证的服务的访问权限意味着它可以代表您执行操作，如果未仔细监控，可能会导致意外操作。
凭据最佳实践
如果您的工作流要求代理使用外部服务进行身份验证，您需要负责预配和限定这些凭据的范围。请遵循以下准则以降低风险：
- 使用最小权限凭据： 创建仅具有代理所需权限的服务账号或 API 密钥。避免传递具有广泛或管理访问权限的凭据。
- 首选短期令牌： 在可能的情况下，请使用有时限的凭据或令牌（会过期），而不是长期有效的 API 密钥。
- 假定完全访问权限： 代理可能会使用它有权访问的任何凭据来完成您分配给它的任务。请仅提供您愿意授予其完整访问权限的凭据。
- 定期轮替凭据： 以与处理任何程序化凭据相同的方式处理与代理共享的凭据；按定期计划轮替它们。
连接外部工具和 API
您可以连接外部工具和 API（例如 Model Context Protocol / MCP 服务器）来扩展代理的功能。执行此操作时：
- 请仅连接来自可信来源的工具。恶意或编写不当的工具可能会泄露数据或执行意外操作。
- 使用您的使用场景所需的最低权限配置工具。如果某个工具支持只读模式，请首选该模式，除非必须进行写入。
- 在将工具连接到生产数据源之前，请针对示例数据或合成数据对其进行测试，以验证代理是否按预期使用该工具。
人工监督
代理可以推理、规划和执行具有高度自主性的多步骤工作流。虽然这很强大，但也意味着您应该进行适当的监督；尤其是对于修改数据或与外部系统交互的任务。
在部署关键输出（例如生成的代码、数据转换或配置更改）之前，请务必对其进行验证。