SDK de Antigravity: qué es, cómo instalarlo y crear tu primer agente

¿Qué es el SDK de Antigravity?

Un SDK permite que una aplicación llame a una capacidad de producto de forma compatible. El SDK de Antigravity permite definir un agente, conectar herramientas aprobadas y consumir el resultado desde Python. Sirve para asistentes internos, ayudantes de repositorio, pruebas y flujos repetibles.

La diferencia es quién controla el flujo: el IDE sirve para trabajo interactivo, la CLI para comandos de terminal y el SDK para que tu programa orqueste el proceso. Pueden complementarse, pero no comparten una versión ni una configuración universal.

Cómo instalar el SDK de Antigravity para Python

Empieza por la página oficial de inicio del SDK y los metadatos actuales de PyPI. Comprueba la versión de Python, los extras, la autenticación y las rutas de importación en vez de copiar ejemplos antiguos. Usa un entorno virtual y un proyecto desechable; mantén los secretos fuera de Git y comienza con una solicitud de solo lectura o reversible.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. Crea un entorno aisladoUsa un entorno virtual local para que la resolución y la reversión sean predecibles.
2. Instala desde la fuente mantenidaSigue las instrucciones oficiales, incluidos los extras o pasos de autenticación actuales.
3. Fija la versión después de probarEjecuta el ejemplo mínimo y registra la versión y el intérprete que funcionaron.
4. Deja la configuración fuera de los commitsUsa variables de entorno o un gestor de secretos e ignora la configuración local.
5. Lee las notas antes de actualizarLa API del SDK puede cambiar de forma independiente del escritorio, la CLI o el IDE.

Confirma los requisitos de Python y las instrucciones actuales antes de usarla en producción.

Crea un primer agente pequeño

Un buen primer agente tiene una función, una instrucción y un resultado revisable. Resume una nota corta o clasifica un fixture local. No juntes navegador, shell, base de datos y escritura al principio: así es más difícil aislar fallos.

Los nombres de clases y propiedades dependen de la versión actual del SDK. El ejemplo muestra el flujo básico: configura, envía una solicitud, revisa el resultado y sigue el ciclo documentado. Úsalo como esquema, no como promesa permanente de API.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• Entrada — Usa un fixture corto con una respuesta esperada.
• Resultado — Inspecciona el resultado antes de añadir automatización.
• Ciclo de vida — Sigue el ciclo de vida y los reintentos documentados.
• Repetibilidad — Guarda el prompt, la versión, los ajustes y el resultado observado.

Añade herramientas de una en una

Las herramientas conectan el razonamiento del agente con una acción externa. Elige la acción mínima útil, define un contrato de entrada pequeño, valida los argumentos y devuelve un resultado limitado. Registra identificadores seguros; no expongas el directorio personal ni otorgues escritura cuando bastan datos de lectura.

Usa subagentes para trabajos separados

Un subagente ayuda cuando hay un papel separado, como planificar, recuperar datos, validar o dar formato. Define límites claros de entrada y salida; el planificador no debería heredar credenciales del validador.

Empieza en secuencia para revisar cada entrega. Añade paralelismo, límites y reintentos cuando los límites sean estables, y muestra los fallos parciales.

Devuelve una salida estructurada que tu programa pueda confiar

El texto libre es cómodo para una persona, pero frágil para la lógica. Si el resultado alimenta una base de datos, UI, prueba u otro agente, usa la salida estructurada actual del SDK con un esquema pequeño y valídalo localmente.

Un esquema no hace verdadera la respuesta: comprueba tipos, valores permitidos y campos obligatorios. Separa los diagnósticos de la salida para el usuario.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• Valida el objeto devuelto localmente.
• Usa enums y cadenas limitadas para opciones finitas.
• Trata los campos ausentes o malformados como un fallo visible.
• Separa los diagnósticos de la salida para el usuario.

SDK frente a IDE y CLI: elige la superficie correcta

El SDK integra un flujo de agente en código; el IDE sirve para proyectos interactivos y la CLI para comandos y scripts. Elige la superficie dueña del trabajo, no tres botones para el mismo flujo.

Sus versiones pueden avanzar en calendarios distintos. Registra la fuente y la fecha del componente que utilizas.

Comprobaciones de seguridad y fiabilidad

Un SDK puede llevar un agente a una aplicación real. Revisa origen del paquete, credenciales, destinos de red, rutas, argumentos y registros. Si accede a datos externos, empieza con un proyecto desechable y una cuenta de prueba.

Mantén visible la aprobación para cambiar archivos, enviar mensajes, gastar dinero, modificar cuentas o publicar. Usa tiempos de espera y reintentos limitados, y distingue entrada inválida, servicio no disponible, permiso denegado y revisión humana.

• Credenciales — Usa un gestor de secretos; nunca guardes tokens en Git ni en prompts.
• Rutas — Permite solo los directorios del proyecto necesarios, no la raíz del disco.
• Acciones — Separa lecturas de escrituras, shell, navegador y red.
• Observabilidad — Registra identificadores, duración, resultados y categorías de error seguras.
• Recuperación — Documenta cómo desactivar, revocar acceso, repetir un fixture y revertir.

Problemas habituales del SDK de Antigravity

Cuando falle la primera ejecución, reduce el sistema a una variable cada vez.

El paquete instala, pero el import falla

Confirma entorno e intérprete y compara la importación con el quickstart actual. Revisa metadatos antes de cambiar código.

El agente devuelve un error de autorización

Compara credenciales, alcance y permisos con la documentación actual. Quita secretos de los registros y repite la solicitud mínima.

Una herramienta se bloquea o se repite

Añade un tiempo de espera, registra el límite y prueba con entrada fija. Limita reintentos y no repitas automáticamente una escritura desconocida.

La salida estructurada está incompleta

Reduce el esquema y valida campos obligatorios localmente. Trata rechazo, truncamiento o datos malformados como revisión.

Referencia de versiones y regla de fuente

El 12 de septiembre de 2026, PyPI mostraba google-antigravity v0.1.16. Las listas oficiales mostraban escritorio v2.13.0, CLI v1.2.0 e IDE v2.5.5; avanzan por separado.

Usa páginas oficiales actuales y registra la versión instalada. La página oficial de descargas es el fallback para escritorio y CLI.