pages/custom-agents.txt

route: /gemini-api/docs/custom-agents
title: Building Managed Agents
description: How to create and use custom agents with managed agents in the Gemini API.

Managed agents on the Gemini API let you extend the Antigravity agent with your own instructions, skills, and data. You can customize the agent inline at interaction time, or save the configuration as a managed agent you invoke by ID.
Customize the Antigravity agent
The 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 three ways:
System instructions: Pass inline text via system_instruction to shape behavior.
Tools: Override default tools (Code Execution, Search, URL Context), register remote MCP servers, or define custom functions (Function Calling).
Files and skills: Mount files like AGENTS.md and SKILL.md into the environment.
Here is an example of passing all three inline:
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Analyze the Q1 revenue data and create a slide deck.",
system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": "Always use matplotlib for charts. Include a summary table in every report.",
},
{
"type": "inline",
"target": ".agents/skills/slide-maker/SKILL.md",
"content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
},
],
},
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: "antigravity-preview-05-2026",
input: "Analyze the Q1 revenue data and create a slide deck.",
system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
environment: {
type: "remote",
sources: [
{
type: "inline",
target: ".agents/AGENTS.md",
content: "Always use matplotlib for charts. Include a summary table in every report.",
},
{
type: "inline",
target: ".agents/skills/slide-maker/SKILL.md",
content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
},
],
},
}, { timeout: 300000 });
console.log(interaction.output_text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-05-2026",
"input": "Analyze the Q1 revenue data and create a slide deck.",
"system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
"environment": {
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": "Always use matplotlib for charts. Include a summary table in every report."
},
{
"type": "inline",
"target": ".agents/skills/slide-maker/SKILL.md",
"content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."
}
]
}
}'
Everything 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.
Tools and system instructions
You can customize the agent's behavior and capabilities for a specific interaction using the system_instruction and tools parameters.
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.
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 or define custom functions (function calling) to connect the agent to your own APIs and databases. For full details on available tools, see Antigravity Agent: Supported tools.
File-based customization
Agent directory structure
While 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.
Note: You can use the experimental open-source Gemini API CLI to automatically scaffold, test, and deploy this directory structure directly from your terminal.
A typical agent project directory looks like this:
my-agent/
├── AGENTS.md # Instructions on how the agent should operate
├── skills/ # Custom skills (subfolders and SKILL.md files)
│ └── slide-maker/
│ └── SKILL.md
└── workspace/ # Initial data files and knowledge
The Antigravity runtime scans .agents/ (and the root of the environment) for these files.
AGENTS.md
The 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.
Mount an AGENTS.md using an inline source:
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Analyze the Q1 revenue data and create a report.",
system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": "Always use matplotlib for charts. Include a summary table in every report.",
},
],
},
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: "antigravity-preview-05-2026",
input: "Analyze the Q1 revenue data and create a report.",
system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
environment: {
type: "remote",
sources: [
{
type: "inline",
target: ".agents/AGENTS.md",
content: "Always use matplotlib for charts. Include a summary table in every report.",
},
],
},
}, { timeout: 300000 });
console.log(interaction.output_text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-05-2026",
"input": "Analyze the Q1 revenue data and create a report.",
"system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
"environment": {
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": "Always use matplotlib for charts. Include a summary table in every report."
}
]
}
}'
Skills: SKILL.md
Skills 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.
.agents/
├── AGENTS.md
└── skills/
└── slide-maker/
└── SKILL.md
Mount a skill using an inline source:
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Create a presentation about our Q1 results.",
system_instruction="You create presentations from data.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/skills/slide-maker/SKILL.md",
"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",
},
],
},
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const clien
…