Gemini Deep Research ya está disponible en versión preliminar con planificación colaborativa, visualización, compatibilidad con MCP y mucho más.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cómo crear agentes administrados

Los agentes administrados en la API de Gemini te permiten agrupar instrucciones, habilidades y un entorno en un agente reutilizable que luego puedes invocar por ID. Define un revisor de código, un analista de datos o un bot de implementación una vez y llámalo desde cualquier cliente sin repetir la configuración.

Python


from google import genai

client = genai.Client()

agent = client.agents.create(
    id="code-reviewer",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
    },
)

result = client.interactions.create(
    agent="code-reviewer",
    input="Review the latest changes in /workspace/repo/src and file a summary.",
    environment="remote",
)
print(result.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "code-reviewer",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
    },
});

const result = await client.interactions.create({
    agent: "code-reviewer",
    input: "Review the latest changes in /workspace/repo/src and file a summary.",
    environment: "remote",
}, { timeout: 300000 });

console.log(result.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "id": "code-reviewer",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo"
            }
        ]
    }
}'

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "agent": "code-reviewer",
    "input": "Review the latest changes in /workspace/repo/src and file a summary.",
    "environment": "remote"
}'

Crea un agente administrado

Un agente administrado combina un base_agent, un system_instruction, un base_environment y un tools en una sola configuración a la que llamas por ID. El arnés del agente de Antigravity proporciona el tiempo de ejecución. En cada invocación, la plataforma bifurca el base_environment en una zona de pruebas nueva con todas las capacidades del base_agent (ejecución de código, administración de archivos y acceso web).

Puedes crear un agente a partir de fuentes, como Git, Cloud Storage o fuentes intercaladas, o bifurcarlo desde un entorno que ya configuraste. Desde fuentes: Especifica system_instruction y base_environment con fuentes. La plataforma aprovisiona un sandbox nuevo con tus archivos en cada invocación. Consulta la sección sobre entornos para conocer los tipos de fuentes disponibles (Git, Cloud Storage, intercalado).

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="data-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md", # This is appended to the system instruction
                "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.",
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates",
            },
        ],
    },
)

print(f"Created agent: {agent.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "data-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
    base_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.",
            },
            {
                type: "repository",
                source: "https://github.com/my-org/analysis-templates",
                target: "/workspace/templates",
            },
        ],
    },
});

console.log(`Created agent: ${agent.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "id": "data-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
    "base_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."
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates"
            }
        ]
    }
}'

Desde un entorno existente (bifurcación)

Itera con el agente base de Antigravity hasta que el entorno sea el adecuado (paquetes instalados, archivos en su lugar) y, luego, crea una bifurcación en un agente administrado.

Python

from google import genai

client = genai.Client()

# Step 1: set up the environment interactively
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment="remote",
)

# Step 2: fork that environment into a named agent

agent = client.agents.create(
    id="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment=interaction.environment_id,
)

print(f"Forked agent successfully: {agent.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment: "remote",
}, { timeout: 300000 });

const agent = await client.agents.create({
    id: "my-data-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment: interaction.environment_id,
});

console.log(`Forked agent successfully: ${agent.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "antigravity-preview-05-2026",
      "input": "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
      "environment": "remote"
  }'

Configura reglas de red

Puedes usar el campo network para restringir el tráfico saliente a dominios específicos. Las credenciales pasan por el proxy de salida y nunca se exponen dentro de la zona de pruebas. Para obtener más información sobre cómo configurar el acceso a la red, consulta Configuración de red en el documento de Entornos:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(f"Created issue-resolver agent successfully: {agent.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "issue-resolver",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "api.github.com",
                    transform: {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                { domain: "pypi.org" },
            ]
        }
    },
});

console.log(`Created issue-resolver agent successfully: ${agent.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "id": "issue-resolver",
      "base_agent": "antigravity-preview-05-2026",
      "system_instruction": "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "repository",
                  "source": "https://github.com/my-org/backend",
                  "target": "/workspace/repo"
              }
          ],
          "network": {
              "allowlist": [
                  {
                      "domain": "api.github.com",
                      "transform": {
                          "Authorization": "Basic YOUR_BASE64_TOKEN"
                      }
                  },
                  {"domain": "pypi.org"}
              ]
          }
      }
  }'

Cuando se establece una lista de entidades permitidas, solo se permiten las solicitudes a los dominios incluidos en la lista. Consulta Environments: Network configuration para ver el esquema completo de la lista de entidades permitidas y los patrones de credenciales. Puedes usar comodines para hacer coincidir subdominios (p.ej., {"domain": "*.example.com"}), pero ten en cuenta que esto no coincide con el dominio raíz example.com, que se debe agregar por separado. Para permitir todo el tráfico restante, como el enrutamiento de dominios no incluidos en la lista sin encabezados insertados, agrega {"domain": "*"} como una entrada general.

Referencia de la definición del agente

En la siguiente tabla, se describen todos los parámetros configurables de un agente:

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	Es el identificador único del agente. Se usa para invocar al agente.
`description`	string	No	Es una descripción del agente legible por humanos.
`base_agent`	string	Sí	Es el ID del agente base (p.ej., `antigravity-preview-05-2026`).
`system_instruction`	string	No	Es la instrucción del sistema que define el comportamiento y la personificación.
`tools`	cadena o objeto	No	Son las herramientas que puede usar el agente. Si se omite, tendrá acceso a `code_execution`, `google_search` y `url_context`.
`base_environment`	cadena o objeto	No	`"remote"`, un `environment_id` o un objeto de configuración con `sources` y `network`. Consulta la sección sobre los entornos.

Instrucciones del sistema: AGENTS.md

El arnés busca AGENTS.md en dos rutas de acceso al inicio:

Ruta	Alcance
`.agents/AGENTS.md`	Raíz del espacio de trabajo actual.
`/.agents/AGENTS.md`	Es la raíz del sistema de archivos.

Si existen ambos, se cargan como instrucciones del sistema.

Para activar un AGENTS.md con una fuente intercalada, haz lo siguiente:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="styled-writer",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept",
            },
        ],
    },
)

print(f"Created styled-writer agent: {agent.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "styled-writer",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept",
            },
        ],
    },
});

console.log(`Created styled-writer agent: ${agent.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "id": "styled-writer",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/AGENTS.md",
                  "content": "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept"
              }
          ]
      }
  }'

Habilidades: SKILL.md

Las habilidades son archivos que amplían las capacidades del agente. Colócalos debajo de .agents/skills/<skill-name>/SKILL.md, y el arnés los detectará y registrará automáticamente.

.agents/
├── AGENTS.md
└── skills/
    └── slide-maker/
        └── SKILL.md

Para activar una skill con una fuente intercalada, haz lo siguiente:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="presenter",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You create presentations from data.",
    base_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(f"Created presenter: {agent.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "presenter",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You create presentations from data.",
    base_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",
            },
        ],
    },
});

console.log(`Created presenter: ${agent.id}`);

REST

# Create agent with skill
curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "id": "presenter",
      "base_agent": "antigravity-preview-05-2026",
      "system_instruction": "You create presentations from data.",
      "base_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"
              }
          ]
      }
  }'

Invoca el agente

Para invocar tu agente administrado personalizado, llama a client.interactions.create con tu ID de agente. Cada invocación bifurca el entorno base, por lo que cada ejecución comienza de forma limpia.

Python

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment="remote",
)

print(result.output_text)

JavaScript

const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment: "remote",
}, { timeout: 300000 });

console.log(result.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" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "data-analyst",
      "input": "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
      "environment": "remote"
  }'

Para conversaciones de varios turnos y transmisión, consulta la Guía de inicio rápido. Los mismos patrones de previous_interaction_id y environment se aplican a los agentes administrados.

Anulación de la configuración durante la invocación

Puedes anular los valores predeterminados system_instruction y tools del agente cuando creas una interacción. Esto te permite modificar el comportamiento o las capacidades del agente para una ejecución específica sin cambiar la definición almacenada del agente.

Python

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction="You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools=[{"type": "code_execution"}], # Override to only use code execution
    environment="remote",
)
print(result.output_text)

JavaScript

const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction: "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools: [{ type: "code_execution" }], // Override to only use code execution
    environment: "remote",
}, { timeout: 300000 });

console.log(result.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" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "data-analyst",
      "input": "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
      "system_instruction": "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
      "tools": [{"type": "code_execution"}],
      "environment": "remote"
  }'

Administrar los agentes

Puedes enumerar, obtener y borrar agentes.

Mostrar lista de agentes

Python

agents = client.agents.list()
for a in agents.agents:
    print(f"{a.id}: {a.description}")

JavaScript

const agents = await client.agents.list();
if (agents.agents) {
    for (const a of agents.agents) {
        console.log(`${a.id}: ${a.description}`);
    }
}

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Obtén un agente

Python

agent = client.agents.get(id="data-analyst")
print(agent)

JavaScript

const agent = await client.agents.get("data-analyst");
console.log(agent);

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Borra un agente

Si borras la configuración, se quitará. Los entornos y las interacciones existentes creados por el agente no se verán afectados.

Python

client.agents.delete(id="data-analyst")

JavaScript

await client.agents.delete("data-analyst");

REST

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Flujo de trabajo de iteración

Prototipa con el agente base de Antigravity. Probar instrucciones, habilidades y configuración del entorno de forma interactiva
Estabiliza el entorno. Instala paquetes, monta fuentes y verifica que todo funcione.
Persiste como un agente administrado con client.agents.create, ya sea desde fuentes o bifurcando el entorno.
Actualiza la definición del agente. Cambia system_instruction, intercambia habilidades o agrega fuentes. La siguiente invocación recoge la configuración nueva.

Limitaciones

Estado de vista previa: Los agentes administrados están en versión preliminar. Las funciones y los esquemas pueden cambiar.
Agente base: Solo se admite antigravity-preview-05-2026 como base_agent.
Sin control de versiones: El control de versiones y la reversión del agente aún no están disponibles.
Sin anidamiento de subagentes: La delegación de subagentes aún no es compatible.
Puedes tener hasta 1,000 agentes administrados por proyecto en cualquier momento.

¿Qué sigue?

Descripción general de los agentes: Obtén información sobre los conceptos básicos de los agentes administrados.
Guía de inicio rápido: Comienza a crear con conversaciones de varios turnos y transmisión.
Antigravity Agent: Explora las capacidades, las herramientas y los precios del agente predeterminado.
Entornos de agentes: Configura zonas de pruebas, fuentes y redes.