spb/doc-api

1# Agents in AI Studio Playground23Google AI Studio Playground provides a visual interface to prototype and learn4how to build managed agents without having to create and write API calls.56To get started, navigate to the **Playground** tab in the navigation panel of7Google AI Studio, and switch the toggle to **Agents**.89## Pre-built templates1011The **Agents** tab has a series of templates that12pre-configure the base Antigravity Agent by setting tool and environment13configurations. All the templates are open-source and published under14the [google-gemini/gemini-managed-agents-templates](https://github.com/google-gemini/gemini-managed-agents-templates/) repository. Exploring these templates is a great way to learn how to build and structure your own managed agent.1516For example, when you pick the AI Radio template, it enables all the allowed17tools, and links a specialized `AGENTS.md` file and skills for radio show18production. You can view these settings on the Playground UI under the19**Environment** section, by clicking on the **Sources** button.2021> [!IMPORTANT]22> **Important:** When you run these templates, the agent inside the sandbox has access to the Gemini API. It will execute calls using your configured API key, which can incur additional token charges on your account. See [safety and cost23> management](https://ai.google.dev/gemini-api/docs/aistudio-agents#safety-and-cost-management) section for more details.2425## Tool configuration2627Under the Agent settings in the Playground, you can toggle access to the28following built-in tools:2930- **Google Search:** Access the open web for real-time information grounding.31- **URL Context:** Fetch and parse the text content of specific web page URLs.32- **Code Execution:** Run Bash and Python commands directly within the isolated sandbox environment.33- **Filesystem Tools:** Read, write, list, and delete files inside the workspace.3435## Environment Configuration3637Managed agents run within a secure, ephemeral Linux sandbox (the environment) that provides the workspace and tools they need to operate. To learn more, see the [managed agent environment](https://ai.google.dev/gemini-api/docs/agent-environment) guide.3839### Controlling agent behavior4041The agent's behavior, persona, and capabilities are predominantly determined by the files present in its environment. The agent automatically detects and loads configurations from a special `.agents` folder:4243- **`AGENTS.md`**: Pre-loaded into the agent's context to define system instructions and persona.44- **`SKILL.md`** : Located under respective skill folders (e.g., `.agents/skills/my-skill/SKILL.md`) to define specific capabilities and workflows.4546### Provisioning the Environment4748You can configure the environment to be used by the agent by mounting files to the environment before you start a session. You can either build a new environment by mounting sources, or restore a previous one:4950- **To create a new environment** , click **Add Sources** in the Environment settings panel and choose from the following source types:5152| Source type | Description | Mounting path |53|---|---|---|54| **Inline Files** | Write or paste configuration files, mock datasets, or utility scripts (up to 100KB) directly into the Playground UI. | User-defined destination path (e.g., `/workspace/scripts/parser.py`). |55| **Google Cloud Storage** | Mount a public or private Cloud Storage bucket. Private buckets require a standard OAuth 2.0 Bearer token. For more information, see [Private sources](https://ai.google.dev/gemini-api/docs/agent-environment#private-sources). | Maps a GCS bucket path (e.g., `gs://your-bucket-name/data/`) to a workspace directory (e.g., `/workspace/data/`). |56| **GitHub Repositories** | Clone public or private codebases. Private repositories require Basic authentication with your GitHub Personal Access Token (PAT). For more information, see [Private sources](https://ai.google.dev/gemini-api/docs/agent-environment#private-sources). | Cloned directly into `/workspace/` (typically under `/workspace/<repo-name>`). |5758- **To restore a previous environment** , you can [reuse an existing environment ID](https://ai.google.dev/gemini-api/docs/aistudio-agents#reusing-an-existing-environment-id) to clone and fork its exact state.5960### Reusing an existing environment ID6162If you have already spent time setting up a sandbox environment, you don't have to start from scratch. To use an existing environment:63641. Go to the Environments panel in AI Studio and toggle **Type** to **Existing**652. Enter the **Environment ID** (e.g., `env_abc123`)6667For more information, see [Configure an environment](https://ai.google.dev/gemini-api/docs/agent-environment#configure-an-environment). You can also retrieve the current session's Environment ID from the Environment tab in the UI.6869Once you send your first message to the agent, the environment configuration70becomes fixed for that session. You cannot mount new sources or modify the71network allowlist while the interaction is actively running.7273## Download the environment7475Once an environment is created, you can download the environment snapshot at any time using the **Download**76button in the Environment settings of the AI Studio Playground to retrieve77environment files as a tarball.7879## Safety and Cost Management8081### Managing Token Consumption8283Unlike a standard chat request that produces a single output, the Antigravity84Agent executes an autonomous workflow. It plans, runs code, observes results,85and iterates. This means a single prompt can result in unbounded token86consumption.8788To manage costs, **provide clear termination criteria in your prompts and scope89the tasks narrowly for the agent** . A good example could be a prompt like90*Review the pull request and stop once you have generated the markdown summary.91Do not attempt to write the fix yourself*.9293> [!IMPORTANT]94> **Important:** If you see the agent running for a long time or not going in the right direction (by observing its thoughts and tool calls), you can use the **Stop** button to stop the agent at any time to avoid unnecessary token consumption.9596### Additional Costs9798By default, all agent templates on the Playground have access to the Gemini API99service and can make API calls from the environment in order to fulfill100requests. These may incur additional costs which will not be reflected in token101consumption.102103Similarly, if you add other external services, the agent may incur additional104costs by calling these services on your behalf.105106### Network Allow List107108By default, on AI Studio all outbound network requests from within109your agent's sandbox environment are tightly controlled and restricted to ensure110security. To grant your agent the ability to reach external APIs, web services,111or package managers, you must explicitly declare them:1121131. Go to the Environments panel in AI Studio.1142. Select the **rules** button next to **Network**.1153. In the **Network configuration** panel, click **Add to allowlist** and fill in the relevant details:116   - **Domain Restriction:** Only the specific domains or wildcard patterns added to the list can be accessed by the agent's virtual machine. For example, you can input exact domains like `api.github.com` or broad patterns like `*.googleapis.com`.117   - **Add HTTP Header and Token Injection:** Use the **Add HTTP header** option to securely inject required credentials (such as an API token) for a specific domain. These credentials pass safely through an egress proxy and are never exposed directly as raw text inside the agent sandbox.118119Always exercise caution when adding domains to your allowlist. Granting the120agent access to authenticated services means it can act on your behalf, which121could lead to unintended actions if not carefully monitored.122123> [!NOTE]124> **Important:**125>126> - Authenticated Gemini API (using your linked API key) is enabled by default for all agent calls through AI Studio Playground.127> - When you use the API, the network is open by default. See [API documentation](https://ai.google.dev/gemini-api/docs/agent-environment#network-configuration) for details.128129### Credentials best practices130131If your workflow requires the agent to authenticate with external services, you132are responsible for provisioning and scoping those credentials. Follow these133guidelines to reduce risk:134135- **Use least-privilege credentials:** Create service accounts or API keys with only the permissions your agent needs. Avoid passing credentials with broad or administrative access.136- **Prefer short-lived tokens:** Where possible, use time-limited credentials or tokens that expire rather than long-lived API keys.137- **Assume full access:** The agent may use any credential it has access to in order to complete the task you have given it. Only provide credentials whose full scope of access you are willing to grant.138- **Rotate credentials regularly:** Treat credentials shared with the agent the same way you would treat any programmatic credential; rotate them on a regular schedule.139140### Connecting external tools and APIs141142You can connect external tools and APIs (such as Model Context Protocol / MCP143servers) to extend the agent's capabilities. When doing so:144145- Only connect tools from sources you trust. A malicious or poorly written tool could expose data or perform unintended actions.146- Configure tools with the minimum permissions required for your use case. If a tool supports read-only mode, prefer that unless writes are strictly necessary.147- Before connecting a tool to a production data source, test it against sample or synthetic data to verify the agent uses it as expected.148149### Human oversight150151Agents can reason, plan, and execute multi-step workflows with a high degree of152autonomy. While this is powerful, it also means you should apply appropriate153oversight; especially for tasks that modify data or interact with external154systems.155156Always verify critical outputs such as generated code, data transformations, or157configuration changes before you deploy them.