Repository Public
1Managed agents on the Gemini API let you extend the Antigravity agent with your own instructions, skills, and data. You can [customize the agent inline](https://ai.google.dev/gemini-api/docs/custom-agents#customize-inline) at interaction time, or [save the configuration](https://ai.google.dev/gemini-api/docs/custom-agents#save-agent) as a managed agent you invoke by ID.23## Customize the Antigravity agent45The fastest way to build a custom agent is to pass your configuration inline while creating a new interaction with no registration step required. You can extend the agent in several key ways:67- **[Model selection](https://ai.google.dev/gemini-api/docs/antigravity-agent#model-selection)** : Choose the underlying Gemini model via `agent_config` (defaults to **Gemini 3.8 Flash**).8- **System instructions** : Pass inline text via `system_instruction` to shape behavior.9- **Tools**: Override default tools (Code Execution, Search, URL Context), register remote MCP servers, or define custom functions (Function Calling).10- **Files and skills** : Mount files like `AGENTS.md` and `SKILL.md` into the environment.1112Here is an example of passing all three inline:1314### Python1516 from google import genai1718 client = genai.Client()1920 interaction = client.interactions.create(21 agent="antigravity-preview-09-2026",22 input="Analyze the Q1 revenue data and create a slide deck.",23 system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",24 environment={25 "type": "remote",26 "sources": [27 {28 "type": "inline",29 "target": ".agents/AGENTS.md",30 "content": "Always use matplotlib for charts. Include a summary table in every report.",31 },32 {33 "type": "inline",34 "target": ".agents/skills/slide-maker/SKILL.md",35 "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",36 },37 ],38 },39 )4041 print(interaction.output_text)4243### JavaScript4445 import { GoogleGenAI } from "@google/genai";4647 const client = new GoogleGenAI({});4849 const interaction = await client.interactions.create({50 agent: "antigravity-preview-09-2026",51 input: "Analyze the Q1 revenue data and create a slide deck.",52 system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",53 environment: {54 type: "remote",55 sources: [56 {57 type: "inline",58 target: ".agents/AGENTS.md",59 content: "Always use matplotlib for charts. Include a summary table in every report.",60 },61 {62 type: "inline",63 target: ".agents/skills/slide-maker/SKILL.md",64 content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",65 },66 ],67 },68 }, { timeout: 300000 });6970 console.log(interaction.output_text);7172### Java7374 import com.google.genai.Client;75 import com.google.genai.gaos.models.interactions.AgentOption;76 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;77 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;78 import com.google.genai.gaos.models.interactions.Environment;79 import com.google.genai.gaos.models.interactions.Interaction;80 import com.google.genai.gaos.models.interactions.InteractionsInput;81 import com.google.genai.gaos.models.interactions.Source;82 import com.google.genai.gaos.models.interactions.SourceType;83 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;84 import java.util.List;8586 Client client = new Client();8788 Environment env = Environment.builder()89 .sources(List.of(90 Source.builder()91 .type(SourceType.INLINE)92 .target(".agents/AGENTS.md")93 .content("Always use matplotlib for charts. Include a summary table in every report.")94 .build(),95 Source.builder()96 .type(SourceType.INLINE)97 .target(".agents/skills/slide-maker/SKILL.md")98 .content("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.")99 .build()100 ))101 .build();102103 CreateAgentInteraction params = CreateAgentInteraction.builder()104 .agent(AgentOption.of("antigravity-preview-09-2026"))105 .input(InteractionsInput.of("Analyze the Q1 revenue data and create a slide deck."))106 .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")107 .environment(CreateAgentInteractionEnvironment.of(env))108 .build();109110 Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();111 System.out.println(interaction.outputText().orElse(""));112113### REST114115 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \116 -H "Content-Type: application/json" \117 -H "x-goog-api-key: $GEMINI_API_KEY" \118 -d '{119 "agent": "antigravity-preview-09-2026",120 "input": "Analyze the Q1 revenue data and create a slide deck.",121 "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",122 "environment": {123 "type": "remote",124 "sources": [125 {126 "type": "inline",127 "target": ".agents/AGENTS.md",128 "content": "Always use matplotlib for charts. Include a summary table in every report."129 },130 {131 "type": "inline",132 "target": ".agents/skills/slide-maker/SKILL.md",133 "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."134 }135 ]136 }137 }'138139Everything is defined at interaction time. No need to register anything first. The Antigravity agent harness provides the runtime (code execution, file management, web access) and your configuration layers on top.140141### Tools and system instructions142143You can customize the agent's behavior and capabilities for a specific interaction using the `system_instruction` and `tools` parameters.144145- **System instructions** : Use the `system_instruction` parameter to pass inline text that shapes the agent's behavior. This is ideal for quick tweaks you want to change per call. The `system_instruction` and `AGENTS.md` are additive; both apply when present.146- **Tools** : By default, the Antigravity agent has access to `code_execution`, `google_search`, and `url_context`. You can override this list by passing the `tools` parameter at interaction time. You can also register [remote MCP servers](https://ai.google.dev/gemini-api/docs/antigravity-agent#mcp-servers) or define [custom functions (function calling)](https://ai.google.dev/gemini-api/docs/antigravity-agent#function-calling) to connect the agent to your own APIs and databases. For full details on available tools, see [Antigravity Agent: Supported tools](https://ai.google.dev/gemini-api/docs/antigravity-agent#supported-tools).147148### File-based customization149150#### Agent directory structure151152While you can pass configuration inline, we recommend organizing your agent's files in a structured directory. This makes it easier to manage, version control, and mount into the agent's environment.153154> [!NOTE]155> **Note:** You can use the experimental open-source [Gemini API CLI](https://github.com/google-gemini/Gemini-API-CLI) to automatically scaffold, test, and deploy this directory structure directly from your terminal.156157A typical agent project directory looks like this:158159 my-agent/160 ├── AGENTS.md # Instructions on how the agent should operate161 ├── skills/ # Custom skills (subfolders and SKILL.md files)162 │ └── slide-maker/163 │ └── SKILL.md164 └── workspace/ # Initial data files and knowledge165166The Antigravity runtime scans `.agents/` (and the root of the environment) for these files.167168#### AGENTS.md169170The agent automatically loads `.agents/AGENTS.md` (or `/.agents/AGENTS.md`) from the environment as system instructions on startup. Use `AGENTS.md` for long-form persona definitions, detailed guidelines, and instructions you want to version control alongside your code.171172Mount an `AGENTS.md` using an inline source:173174### Python175176 from google import genai177178 client = genai.Client()179180 interaction = client.interactions.create(181 agent="antigravity-preview-09-2026",182 input="Analyze the Q1 revenue data and create a report.",183 system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",184 environment={185 "type": "remote",186 "sources": [187 {188 "type": "inline",189 "target": ".agents/AGENTS.md",190 "content": "Always use matplotlib for charts. Include a summary table in every report.",191 },192 ],193 },194 )195196 print(interaction.output_text)197198### JavaScript199200 import { GoogleGenAI } from "@google/genai";201202 const client = new GoogleGenAI({});203204 const interaction = await client.interactions.create({205 agent: "antigravity-preview-09-2026",206 input: "Analyze the Q1 revenue data and create a report.",207 system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",208 environment: {209 type: "remote",210 sources: [211 {212 type: "inline",213 target: ".agents/AGENTS.md",214 content: "Always use matplotlib for charts. Include a summary table in every report.",215 },216 ],217 },218 }, { timeout: 300000 });219220 console.log(interaction.output_text);221222### Java223224 import com.google.genai.Client;225 import com.google.genai.gaos.models.interactions.AgentOption;226 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;227 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;228 import com.google.genai.gaos.models.interactions.Environment;229 import com.google.genai.gaos.models.interactions.Interaction;230 import com.google.genai.gaos.models.interactions.InteractionsInput;231 import com.google.genai.gaos.models.interactions.Source;232 import com.google.genai.gaos.models.interactions.SourceType;233 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;234 import java.util.List;235236 Client client = new Client();237238 Environment env = Environment.builder()239 .sources(List.of(240 Source.builder()241 .type(SourceType.INLINE)242 .target(".agents/AGENTS.md")243 .content("Always use matplotlib for charts. Include a summary table in every report.")244 .build()245 ))246 .build();247248 CreateAgentInteraction params = CreateAgentInteraction.builder()249 .agent(AgentOption.of("antigravity-preview-09-2026"))250 .input(InteractionsInput.of("Analyze the Q1 revenue data and create a report."))251 .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")252 .environment(CreateAgentInteractionEnvironment.of(env))253 .build();254255 Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();256 System.out.println(interaction.outputText().orElse(""));257258### REST259260 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \261 -H "Content-Type: application/json" \262 -H "x-goog-api-key: $GEMINI_API_KEY" \263 -d '{264 "agent": "antigravity-preview-09-2026",265 "input": "Analyze the Q1 revenue data and create a report.",266 "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",267 "environment": {268 "type": "remote",269 "sources": [270 {271 "type": "inline",272 "target": ".agents/AGENTS.md",273 "content": "Always use matplotlib for charts. Include a summary table in every report."274 }275 ]276 }277 }'278279#### Skills: SKILL.md280281Skills are files that extend the agent's capabilities. Place them under `.agents/skills/<skill-name>/SKILL.md` and the harness auto-discovers and registers them.282283 .agents/284 ├── AGENTS.md285 └── skills/286 └── slide-maker/287 └── SKILL.md288289Mount a skill using an inline source:290291### Python292293 from google import genai294295 client = genai.Client()296297 interaction = client.interactions.create(298 agent="antigravity-preview-09-2026",299 input="Create a presentation about our Q1 results.",300 system_instruction="You create presentations from data.",301 environment={302 "type": "remote",303 "sources": [304 {305 "type": "inline",306 "target": ".agents/skills/slide-maker/SKILL.md",307 "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",308 },309 ],310 },311 )312313 print(interaction.output_text)314315### JavaScript316317 import { GoogleGenAI } from "@google/genai";318319 const client = new GoogleGenAI({});320321 const interaction = await client.interactions.create({322 agent: "antigravity-preview-09-2026",323 input: "Create a presentation about our Q1 results.",324 system_instruction: "You create presentations from data.",325 environment: {326 type: "remote",327 sources: [328 {329 type: "inline",330 target: ".agents/skills/slide-maker/SKILL.md",331 content: "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",332 },333 ],334 },335 }, { timeout: 300000 });336337 console.log(interaction.output_text);338339### Java340341 import com.google.genai.Client;342 import com.google.genai.gaos.models.interactions.AgentOption;343 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;344 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;345 import com.google.genai.gaos.models.interactions.Environment;346 import com.google.genai.gaos.models.interactions.Interaction;347 import com.google.genai.gaos.models.interactions.InteractionsInput;348 import com.google.genai.gaos.models.interactions.Source;349 import com.google.genai.gaos.models.interactions.SourceType;350 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;351 import java.util.List;352353 Client client = new Client();354355 Environment env = Environment.builder()356 .sources(List.of(357 Source.builder()358 .type(SourceType.INLINE)359 .target(".agents/skills/slide-maker/SKILL.md")360 .content("---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html")361 .build()362 ))363 .build();364365 CreateAgentInteraction params = CreateAgentInteraction.builder()366 .agent(AgentOption.of("antigravity-preview-09-2026"))367 .input(InteractionsInput.of("Create a presentation about our Q1 results."))368 .systemInstruction("You create presentations from data.")369 .environment(CreateAgentInteractionEnvironment.of(env))370 .build();371372 Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();373 System.out.println(interaction.outputText().orElse(""));374375### REST376377 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \378 -H "Content-Type: application/json" \379 -H "x-goog-api-key: $GEMINI_API_KEY" \380 -d '{381 "agent": "antigravity-preview-09-2026",382 "input": "Create a presentation about our Q1 results.",383 "system_instruction": "You create presentations from data.",384 "environment": {385 "type": "remote",386 "sources": [387 {388 "type": "inline",389 "target": ".agents/skills/slide-maker/SKILL.md",390 "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html"391 }392 ]393 }394 }'395396Skills loaded from `.agents/skills/` and `/.agents/skills/` are both discovered automatically.397398## Create a managed agent399400Once you've iterated on your configuration, you can create it as a managed agent with `agents.create`. This lets you invoke the agent by ID without repeating the configuration each time.401402The `id` you specify when creating a managed agent must be unique to your project and must not start with reserved prefixes (e.g., `google-`, `gemini-`). See [Agent ID restrictions](https://ai.google.dev/gemini-api/docs/custom-agents#agent-id-restrictions) for the full list of restricted prefixes.403404### From sources405406Specify `base_agent`, `id`, `agent_config`, `system_instruction` and `base_environment` with sources. The platform provisions a fresh sandbox with your files on every invocation. See [Environments](https://ai.google.dev/gemini-api/docs/agent-environment) for available source types (Git, GCS, inline).407408### Python409410 from google import genai411412 client = genai.Client()413414 agent = client.agents.create(415 id="data-analyst",416 base_agent="antigravity-preview-09-2026",417 agent_config={418 "type": "antigravity",419 "model": "gemini-3.8-flash",420 },421 system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",422 base_environment={423 "type": "remote",424 "sources": [425 {426 "type": "inline",427 "target": ".agents/AGENTS.md",428 "content": "Always use matplotlib for charts. Include a summary table in every report.",429 },430 {431 "type": "inline",432 "target": ".agents/skills/slide-maker/SKILL.md",433 "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",434 },435 {436 "type": "repository",437 "source": "https://github.com/my-org/analysis-templates",438 "target": "/workspace/templates",439 },440 ],441 },442 )443444 print(f"Created agent: {agent.id}")445446### JavaScript447448 import { GoogleGenAI } from "@google/genai";449450 const client = new GoogleGenAI({});451452 const agent = await client.agents.create({453 id: "data-analyst",454 base_agent: "antigravity-preview-09-2026",455 agent_config: {456 type: "antigravity",457 model: "gemini-3.8-flash",458 },459 system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",460 base_environment: {461 type: "remote",462 sources: [463 {464 type: "inline",465 target: ".agents/AGENTS.md",466 content: "Always use matplotlib for charts. Include a summary table in every report.",467 },468 {469 type: "inline",470 target: ".agents/skills/slide-maker/SKILL.md",471 content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",472 },473 {474 type: "repository",475 source: "https://github.com/my-org/analysis-templates",476 target: "/workspace/templates",477 },478 ],479 },480 });481482 console.log(`Created agent: ${agent.id}`);483484### Java485486 import com.google.genai.Client;487 import com.google.genai.gaos.models.agents.Agent;488 import com.google.genai.gaos.models.agents.AgentConfig;489 import com.google.genai.gaos.models.agents.BaseEnvironment;490 import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;491 import com.google.genai.gaos.models.interactions.Environment;492 import com.google.genai.gaos.models.interactions.Source;493 import com.google.genai.gaos.models.interactions.SourceType;494 import java.util.List;495496 Client client = new Client();497498 Environment env = Environment.builder()499 .sources(List.of(500 Source.builder()501 .type(SourceType.INLINE)502 .target(".agents/AGENTS.md")503 .content("Always use matplotlib for charts. Include a summary table in every report.")504 .build(),505 Source.builder()506 .type(SourceType.INLINE)507 .target(".agents/skills/slide-maker/SKILL.md")508 .content("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.")509 .build(),510 Source.builder()511 .type(SourceType.REPOSITORY)512 .source("https://github.com/my-org/analysis-templates")513 .target("/workspace/templates")514 .build()515 ))516 .build();517518 Agent agentParams = Agent.builder()519 .id("data-analyst")520 .baseAgent("antigravity-preview-09-2026")521 .agentConfig(AgentConfig.of(522 AntigravityAgentConfig.builder()523 .model("gemini-3.8-flash")524 .build()525 ))526 .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")527 .baseEnvironment(BaseEnvironment.of(env))528 .build();529530 Agent agent = client.agents.create(agentParams).agent().get();531 System.out.println("Created agent: " + agent.id().orElse(""));532533### REST534535 curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \536 -H "Content-Type: application/json" \537 -H "x-goog-api-key: $GEMINI_API_KEY" \538 -d '{539 "id": "data-analyst",540 "base_agent": "antigravity-preview-09-2026",541 "agent_config": {542 "type": "antigravity",543 "model": "gemini-3.8-flash"544 },545 "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",546 "base_environment": {547 "type": "remote",548 "sources": [549 {550 "type": "inline",551 "target": ".agents/AGENTS.md",552 "content": "Always use matplotlib for charts. Include a summary table in every report."553 },554 {555 "type": "inline",556 "target": ".agents/skills/slide-maker/SKILL.md",557 "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."558 },559 {560 "type": "repository",561 "source": "https://github.com/my-org/analysis-templates",562 "target": "/workspace/templates"563 }564 ]565 }566 }'567568### From an existing environment (fork)569570Iterate with the base Antigravity agent until the environment is right (packages installed, files in place), then fork it into a managed agent.571572### Python573574 from google import genai575576 client = genai.Client()577578 # Step 1: set up the environment interactively579 interaction = client.interactions.create(580 agent="antigravity-preview-09-2026",581 input="Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",582 environment="remote",583 )584585 # Step 2: fork that environment into a managed agent586587 agent = client.agents.create(588 id="my-data-analyst",589 base_agent="antigravity-preview-09-2026",590 system_instruction="You are a data analyst. Use the template at /workspace/template.py for all reports.",591 base_environment=interaction.environment_id,592 )593594 print(f"Forked agent successfully: {agent.id}")595596### JavaScript597598 import { GoogleGenAI } from "@google/genai";599600 const client = new GoogleGenAI({});601602 const interaction = await client.interactions.create({603 agent: "antigravity-preview-09-2026",604 input: "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",605 environment: "remote",606 }, { timeout: 300000 });607608 const agent = await client.agents.create({609 id: "my-data-analyst",610 base_agent: "antigravity-preview-09-2026",611 system_instruction: "You are a data analyst. Use the template at /workspace/template.py for all reports.",612 base_environment: interaction.environment_id,613 });614615 console.log(`Forked agent successfully: ${agent.id}`);616617### Java618619 import com.google.genai.Client;620 import com.google.genai.gaos.models.agents.Agent;621 import com.google.genai.gaos.models.agents.BaseEnvironment;622 import com.google.genai.gaos.models.interactions.AgentOption;623 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;624 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;625 import com.google.genai.gaos.models.interactions.Interaction;626 import com.google.genai.gaos.models.interactions.InteractionsInput;627 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;628629 Client client = new Client();630631 // Step 1: set up the environment interactively632 CreateAgentInteraction params = CreateAgentInteraction.builder()633 .agent(AgentOption.of("antigravity-preview-09-2026"))634 .input(InteractionsInput.of("Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py."))635 .environment(CreateAgentInteractionEnvironment.of("remote"))636 .build();637638 Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();639640 // Step 2: fork that environment into a managed agent641 Agent agentParams = Agent.builder()642 .id("my-data-analyst")643 .baseAgent("antigravity-preview-09-2026")644 .systemInstruction("You are a data analyst. Use the template at /workspace/template.py for all reports.")645 .baseEnvironment(BaseEnvironment.of(interaction.environmentId().orElse("")))646 .build();647648 Agent agent = client.agents.create(agentParams).agent().get();649 System.out.println("Forked agent successfully: " + agent.id().orElse(""));650651### REST652653 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \654 -H "Content-Type: application/json" \655 -H "x-goog-api-key: $GEMINI_API_KEY" \656 -d '{657 "agent": "antigravity-preview-09-2026",658 "input": "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",659 "environment": "remote"660 }'661662### With network rules663664You can lock down outbound access or inject credentials when saving a managed agent. For the full allowlist schema, credential patterns, and wildcards, see [Environments: Network configuration](https://ai.google.dev/gemini-api/docs/agent-environment#network-configuration).665666Reference a stored [credential](https://ai.google.dev/gemini-api/docs/agent-credentials) by ID on an allowlist rule (`"credential": "github-production"`) and the egress proxy injects the secret at request time, so it never lands in your agent definition. This example sets the header inline with `transform` instead. The proxy applies both forms the same way, a credential additionally lets you reuse the secret across agents and rotate it in one place.667668The following example creates an `issue-resolver` agent that can only access GitHub and PyPI, with credentials injected for GitHub:669670### Python671672 from google import genai673674 client = genai.Client()675676 agent = client.agents.create(677 id="issue-resolver",678 base_agent="antigravity-preview-09-2026",679 system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",680 base_environment={681 "type": "remote",682 "sources": [683 {684 "type": "repository",685 "source": "https://github.com/my-org/backend",686 "target": "/workspace/repo",687 }688 ],689 "network": {690 "allowlist": [691 {692 "domain": "api.github.com",693 "transform": {694 "Authorization": "Basic YOUR_BASE64_TOKEN"695 },696 },697 {"domain": "pypi.org"},698 ]699 },700 },701 )702703 print(f"Created issue-resolver agent successfully: {agent.id}")704705### JavaScript706707 import { GoogleGenAI } from "@google/genai";708709 const client = new GoogleGenAI({});710711 const agent = await client.agents.create({712 id: "issue-resolver",713 base_agent: "antigravity-preview-09-2026",714 system_instruction: "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",715 base_environment: {716 type: "remote",717 sources: [718 {719 type: "repository",720 source: "https://github.com/my-org/backend",721 target: "/workspace/repo",722 }723 ],724 network: {725 allowlist: [726 {727 domain: "api.github.com",728 transform: {729 "Authorization": "Basic YOUR_BASE64_TOKEN"730 },731 },732 { domain: "pypi.org" },733 ]734 }735 },736 });737738 console.log(`Created issue-resolver agent successfully: ${agent.id}`);739740### Java741742 import com.google.genai.Client;743 import com.google.genai.gaos.models.agents.Agent;744 import com.google.genai.gaos.models.agents.BaseEnvironment;745 import com.google.genai.gaos.models.interactions.Allowlist;746 import com.google.genai.gaos.models.interactions.AllowlistEntry;747 import com.google.genai.gaos.models.interactions.Environment;748 import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;749 import com.google.genai.gaos.models.interactions.Network;750 import com.google.genai.gaos.models.interactions.Source;751 import com.google.genai.gaos.models.interactions.SourceType;752 import com.google.genai.gaos.models.interactions.Transform;753 import java.util.List;754 import java.util.Map;755756 Client client = new Client();757758 Environment env = Environment.builder()759 .sources(List.of(760 Source.builder()761 .type(SourceType.REPOSITORY)762 .source("https://github.com/my-org/backend")763 .target("/workspace/repo")764 .build()765 ))766 .network(Network.of(EnvironmentNetworkEgressAllowlist.of(767 Allowlist.builder()768 .allowlist(List.of(769 AllowlistEntry.builder()770 .domain("api.github.com")771 .transform(Transform.of(Map.of(772 "Authorization", "Basic YOUR_BASE64_TOKEN"773 )))774 .build(),775 AllowlistEntry.builder().domain("pypi.org").build()776 ))777 .build()778 )))779 .build();780781 Agent agentParams = Agent.builder()782 .id("issue-resolver")783 .baseAgent("antigravity-preview-09-2026")784 .systemInstruction("You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.")785 .baseEnvironment(BaseEnvironment.of(env))786 .build();787788 Agent agent = client.agents.create(agentParams).agent().get();789 System.out.println("Created issue-resolver agent successfully: " + agent.id().orElse(""));790791### REST792793 curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \794 -H "Content-Type: application/json" \795 -H "x-goog-api-key: $GEMINI_API_KEY" \796 -d '{797 "id": "issue-resolver",798 "base_agent": "antigravity-preview-09-2026",799 "system_instruction": "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",800 "base_environment": {801 "type": "remote",802 "sources": [803 {804 "type": "repository",805 "source": "https://github.com/my-org/backend",806 "target": "/workspace/repo"807 }808 ],809 "network": {810 "allowlist": [811 {812 "domain": "api.github.com",813 "transform": {814 "Authorization": "Basic YOUR_BASE64_TOKEN"815 }816 },817 {"domain": "pypi.org"}818 ]819 }820 }821 }'822823## Invoke the agent824825Call your managed agent with your agent ID by creating a new interaction. Each invocation forks the base environment, so every run starts clean.826827### Python828829 result = client.interactions.create(830 agent="data-analyst",831 input="Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",832 environment="remote",833 )834835 print(result.output_text)836837### JavaScript838839 const result = await client.interactions.create({840 agent: "data-analyst",841 input: "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",842 environment: "remote",843 }, { timeout: 300000 });844845 console.log(result.output_text);846847### Java848849 import com.google.genai.Client;850 import com.google.genai.gaos.models.interactions.AgentOption;851 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;852 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;853 import com.google.genai.gaos.models.interactions.Interaction;854 import com.google.genai.gaos.models.interactions.InteractionsInput;855 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;856857 Client client = new Client();858859 CreateAgentInteraction params = CreateAgentInteraction.builder()860 .agent(AgentOption.of("data-analyst"))861 .input(InteractionsInput.of("Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck."))862 .environment(CreateAgentInteractionEnvironment.of("remote"))863 .build();864865 Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();866 System.out.println(result.outputText().orElse(""));867868### REST869870 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \871 -H "Content-Type: application/json" \872 -H "x-goog-api-key: $GEMINI_API_KEY" \873 -d '{874 "agent": "data-analyst",875 "input": "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",876 "environment": "remote"877 }'878879For multi-turn conversations and streaming, see the [Quickstart](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart). The same `previous_interaction_id` and `environment` patterns apply to managed agents.880881Managed agents also support background execution and cancellation. For details and code examples, see [Antigravity Agent: Background execution](https://ai.google.dev/gemini-api/docs/antigravity-agent#background-execution).882883## Overriding configuration at invocation884885You can override the agent's default `system_instruction`, `tools`, and886`environment` network configuration when creating an interaction. This887lets you modify the agent's behavior, capabilities, or credentials for a888specific run without changing the stored agent definition.889890### Override system instruction and tools891892### Python893894 result = client.interactions.create(895 agent="data-analyst",896 input="Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",897 system_instruction="You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",898 tools=[{"type": "code_execution"}], # Override to only use code execution899 environment="remote",900 )901 print(result.output_text)902903### JavaScript904905 const result = await client.interactions.create({906 agent: "data-analyst",907 input: "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",908 system_instruction: "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",909 tools: [{ type: "code_execution" }], // Override to only use code execution910 environment: "remote",911 }, { timeout: 300000 });912913 console.log(result.output_text);914915### Java916917 import com.google.genai.Client;918 import com.google.genai.gaos.models.interactions.AgentOption;919 import com.google.genai.gaos.models.interactions.CodeExecution;920 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;921 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;922 import com.google.genai.gaos.models.interactions.Interaction;923 import com.google.genai.gaos.models.interactions.InteractionsInput;924 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;925 import java.util.List;926927 Client client = new Client();928929 CreateAgentInteraction params = CreateAgentInteraction.builder()930 .agent(AgentOption.of("data-analyst"))931 .input(InteractionsInput.of("Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table."))932 .systemInstruction("You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.")933 .tools(List.of(CodeExecution.builder().build())) // Override to only use code execution934 .environment(CreateAgentInteractionEnvironment.of("remote"))935 .build();936937 Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();938 System.out.println(result.outputText().orElse(""));939940### REST941942 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \943 -H "Content-Type: application/json" \944 -H "x-goog-api-key: $GEMINI_API_KEY" \945 -d '{946 "agent": "data-analyst",947 "input": "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",948 "system_instruction": "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",949 "tools": [{"type": "code_execution"}],950 "environment": "remote"951 }'952953### Override network configuration (refresh credentials)954955If your managed agent has network credentials baked into its `base_environment`,956you can override them at invocation time to refresh expired tokens or rotate API957keys. Pass an `environment` object with a new `network` configuration. The new958network rules fully replace the previous ones for that interaction. The base959environment's sources (files, repositories) are preserved.960961If the `base_environment` references a stored962[credential](https://ai.google.dev/gemini-api/docs/agent-credentials) instead of an inline token, you963don't need to override anything. Rotate the credential with a `PATCH` and every964agent referencing it picks up the new secret on the next run.965966### Python967968 # Invoke the agent with a fresh token, overriding the base_environment credentials969 result = client.interactions.create(970 agent="issue-resolver",971 input="Fix issue #42 and open a PR.",972 environment={973 "type": "remote",974 "network": {975 "allowlist": [976 {977 "domain": "api.github.com",978 "transform": {979 "Authorization": "Bearer ghp_REFRESHED_TOKEN"980 },981 },982 {"domain": "pypi.org"},983 ]984 },985 },986 )987988 print(result.output_text)989990### JavaScript991992 // Invoke the agent with a fresh token, overriding the base_environment credentials993 const result = await client.interactions.create({994 agent: "issue-resolver",995 input: "Fix issue #42 and open a PR.",996 environment: {997 type: "remote",998 network: {999 allowlist: [1000 {1001 domain: "api.github.com",1002 transform: {1003 "Authorization": "Bearer ghp_REFRESHED_TOKEN"1004 },1005 },1006 { domain: "pypi.org" },1007 ]1008 },1009 },1010 }, { timeout: 300000 });10111012 console.log(result.output_text);10131014### Java10151016 import com.google.genai.Client;1017 import com.google.genai.gaos.models.interactions.AgentOption;1018 import com.google.genai.gaos.models.interactions.Allowlist;1019 import com.google.genai.gaos.models.interactions.AllowlistEntry;1020 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1021 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;1022 import com.google.genai.gaos.models.interactions.Environment;1023 import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;1024 import com.google.genai.gaos.models.interactions.Interaction;1025 import com.google.genai.gaos.models.interactions.InteractionsInput;1026 import com.google.genai.gaos.models.interactions.Network;1027 import com.google.genai.gaos.models.interactions.Transform;1028 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1029 import java.util.List;1030 import java.util.Map;10311032 Client client = new Client();10331034 // Invoke the agent with a fresh token, overriding the base_environment credentials1035 Environment env = Environment.builder()1036 .network(Network.of(EnvironmentNetworkEgressAllowlist.of(1037 Allowlist.builder()1038 .allowlist(List.of(1039 AllowlistEntry.builder()1040 .domain("api.github.com")1041 .transform(Transform.of(Map.of(1042 "Authorization", "Bearer ghp_REFRESHED_TOKEN"1043 )))1044 .build(),1045 AllowlistEntry.builder().domain("pypi.org").build()1046 ))1047 .build()1048 )))1049 .build();10501051 CreateAgentInteraction params = CreateAgentInteraction.builder()1052 .agent(AgentOption.of("issue-resolver"))1053 .input(InteractionsInput.of("Fix issue #42 and open a PR."))1054 .environment(CreateAgentInteractionEnvironment.of(env))1055 .build();10561057 Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();1058 System.out.println(result.outputText().orElse(""));10591060### REST10611062 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1063 -H "Content-Type: application/json" \1064 -H "x-goog-api-key: $GEMINI_API_KEY" \1065 -d '{1066 "agent": "issue-resolver",1067 "input": "Fix issue #42 and open a PR.",1068 "environment": {1069 "type": "remote",1070 "network": {1071 "allowlist": [1072 {1073 "domain": "api.github.com",1074 "transform": {1075 "Authorization": "Bearer ghp_REFRESHED_TOKEN"1076 }1077 },1078 {"domain": "pypi.org"}1079 ]1080 }1081 }1082 }'10831084## Manage agents10851086You can list, get, and delete agents.10871088### List agents10891090### Python10911092 agents = client.agents.list()1093 for a in agents.agents:1094 print(f"{a.id}: {a.description}")10951096### JavaScript10971098 const agents = await client.agents.list();1099 if (agents.agents) {1100 for (const a of agents.agents) {1101 console.log(`${a.id}: ${a.description}`);1102 }1103 }11041105### Java11061107 import com.google.genai.Client;1108 import com.google.genai.gaos.models.agents.Agent;1109 import java.util.List;11101111 Client client = new Client();11121113 List<Agent> agents = client.agents.listDirect().agentListResponse().get().agents().orElse(List.of());1114 for (Agent a : agents) {1115 System.out.println(a.id().orElse("") + ": " + a.description().orElse(""));1116 }11171118### REST11191120 curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents" \1121 -H "x-goog-api-key: $GEMINI_API_KEY"11221123### Get an agent11241125### Python11261127 agent = client.agents.get(id="data-analyst")1128 print(agent)11291130### JavaScript11311132 const agent = await client.agents.get("data-analyst");1133 console.log(agent);11341135### Java11361137 import com.google.genai.Client;1138 import com.google.genai.gaos.models.agents.Agent;11391140 Client client = new Client();11411142 Agent agent = client.agents.get("data-analyst").agent().get();1143 System.out.println(agent);11441145### REST11461147 curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \1148 -H "x-goog-api-key: $GEMINI_API_KEY"11491150### Delete an agent11511152Deleting removes the configuration. Existing environments and interactions created by the agent are not affected.11531154### Python11551156 client.agents.delete(id="data-analyst")11571158### JavaScript11591160 await client.agents.delete("data-analyst");11611162### Java11631164 import com.google.genai.Client;11651166 Client client = new Client();11671168 client.agents.delete("data-analyst");11691170### REST11711172 curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \1173 -H "x-goog-api-key: $GEMINI_API_KEY"11741175## Agent definition reference11761177| Field | Type | Required | Description |1178|---|---|---|---|1179| `id` | string | Yes | Unique agent identifier within the Google Cloud project. Used to invoke the agent. Must not use reserved prefixes. See [Agent ID restrictions](https://ai.google.dev/gemini-api/docs/custom-agents#agent-id-restrictions). |1180| `description` | string | No | Human-readable description of the agent. |1181| `base_agent` | string | Yes | Base agent ID (e.g., `antigravity-preview-09-2026`). |1182| `agent_config` | object | No | Configuration for the base agent, including model selection (`{"type": "antigravity", "model": "gemini-3.8-flash"}`). Defaults to `gemini-3.8-flash` if omitted. Cannot be overridden at interaction time for named agents. |1183| `system_instruction` | string | No | System prompt defining behavior and persona. |1184| `tools` | array | No | Tools the agent can use. If omitted, defaults to `code_execution`, `google_search`, and `url_context`. Supported tools include `code_execution`, `google_search`, `url_context`, `mcp_server`, and custom `function` definitions. |1185| `base_environment` | string or object | No | `"remote"`, an `environment_id`, or a config object with `sources` and `network`. See Environments. |11861187### Agent ID restrictions11881189When creating a managed agent, the `id` you specify must follow these rules:11901191- It must be unique to your Google Cloud project.1192- It must **not** start with any of the following reserved prefixes (case-insensitive), otherwise creation will fail:1193 - `antigravity-`1194 - `veo-`1195 - `omni-`1196 - `lyria-`1197 - `imagen-`1198 - `gemma-`1199 - `gemini-`1200 - `google-`1201 - `youtube-`1202 - `android-`1203 - `chrome-`1204 - `pixel-`1205 - `waze-`1206 - `fitbit-`1207 - `nest-`1208 - `kaggle-`12091210## Iteration workflow121112121. **Prototype** with the base Antigravity agent. Pass system instruction and environment sources inline. Test instructions, skills, and environment setup interactively.12132. **Stabilize** the environment. Install packages, mount sources, verify everything works.12143. **Persist** as a managed agent by creating a new agent, either from sources or by forking the environment.12154. **Update** the agent definition. Change system instruction, swap skills, or add sources. The next invocation picks up the new configuration.12161217## Limitations12181219- **Preview status**: Managed agents are in preview. Features and schemas may change.1220- **Base agent and models** : Only `antigravity-preview-09-2026` is supported as `base_agent`. Supported model options in `agent_config` are `gemini-3.8-flash` (default), `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, and `gemini-3.5-flash-lite`. For named agents, the model cannot be overridden at interaction time.1221- **No versioning**: Agent versioning and rollback are not yet available.1222- **No subagent nesting**: Subagent delegation is not yet supported.1223- You can have up to 1000 managed agents.12241225## What's next12261227- [Agents Overview](https://ai.google.dev/gemini-api/docs/agents): Learn about the core concepts of managed agents.1228- [Quickstart](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart): Start building with multi-turn conversations and streaming.1229- [Antigravity Agent](https://ai.google.dev/gemini-api/docs/antigravity-agent): Explore capabilities, tools, and pricing for the default agent.1230- [Agent Environments](https://ai.google.dev/gemini-api/docs/agent-environment): Configure sandboxes, sources, and networking.1231- [Managed Agents API on Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents): For creating agents with built-in organizational governance.