Google AI Studio Playground 提供了一个可视化界面，可用于原型设计和学习如何构建受管理的代理，而无需创建和编写 API 调用。
首先，前往 Google AI Studio 导航面板中的游乐场标签页，然后将开关切换到智能体。
预构建的模板
代理标签页包含一系列模板，这些模板通过设置工具和环境配置来预配置基本 Antigravity 代理。所有模板均为开源，并发布在 google-gemini/gemini-managed-agents-templates 代码库下。探索这些模板是了解如何构建和组织自己的受管代理的绝佳方式。
例如，当您选择“AI 电台”模板时，系统会启用所有允许的工具，并关联一个专门用于制作广播节目的 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 Agent 会执行自主工作流。它会规划、运行代码、观察结果并进行迭代。这意味着，单个提示可能会导致无限制的令牌消耗。
为了控制费用，请在提示中提供明确的终止条件，并为代理限定任务范围。一个很好的示例可以是这样的提示： 查看拉取请求，并在生成 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 服务器）来扩展智能体的功能。执行此操作时：
- 请仅连接来自可信来源的工具。恶意或编写不当的工具可能会泄露数据或执行意外操作。
- 使用所需的最低权限配置工具。如果某个工具支持只读模式，请优先使用该模式，除非必须进行写入操作。
- 在将工具连接到正式版数据源之前，请先使用示例数据或合成数据对其进行测试，以验证代理是否按预期使用该工具。
人工监督
智能体可以高度自主地推理、规划和执行多步骤工作流。虽然这非常强大，但也意味着您应进行适当的监督，尤其是对于修改数据或与外部系统互动的任务。
在部署关键输出（例如生成的代码、数据转换或配置更改）之前，请务必先进行验证。