Primeros pasos con Google Antigravity Agent API: Interactions API, llamadas a herramientas y continuación de estado

La antigravedad aparece en la creciente consulta de “agente de codificación” en Google Trends en Estados Unidos.

Google ahora proporciona una vista previa de la API de interacciones de Antigravity Agent, por lo que “disponible en el IDE” y “llamado en el programa” deben entenderse por separado.

¿Para qué tareas es adecuada esta API?

Es adecuado para tareas de desarrollo que tienen objetivos claros y requieren operaciones de herramientas y razonamiento de varios pasos.

Por ejemplo, leer el repositorio, localizar errores, modificar el código y ejecutar pruebas.

La finalización de texto de una sola pasada no requiere el uso del tiempo de ejecución del Agente.

La versión preliminar tampoco es adecuada para el funcionamiento directo de entornos de producción sin aislamiento.

Registre cuatro datos antes de comenzar

Proyecto Google AI Studio.
La clave API pertenece al proyecto.
Modelo seleccionado y disponibilidad regional.
Cuota para niveles gratuitos o pagos.

La clave solo pone variables de entorno:

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

No escriba claves reales en scripts de muestra, capturas de pantalla o historial de Git.

Primero haz la petición mínima sin herramientas

Utilice el SDK y los nombres de campos que se muestran actualmente en la documentación oficial.

La API de vista previa cambia rápidamente, así que verifique la versión antes de copiar el código antiguo del blog.

Solicite al objetivo que escriba sólo una acción aceptable, como “Explique este error y dé dos hipótesis”.

Guarde el ID de respuesta, el nombre del modelo, el tiempo necesario y el uso.

El ID de respuesta es una prueba importante para el estado de la conexión posterior y la resolución de problemas.

Agregar herramientas de solo lectura

La primera herramienta debería ser leer un archivo en lugar de ejecutar un shell.

Fije el directorio permitido al repositorio de prueba:

1

C:\sandbox\antigravity-demo

Los parámetros de la herramienta deben normalizarse en la ruta.

Denegar rutas absolutas, .., escapes de enlaces simbólicos y recursos compartidos de red ocultos.

Establezca un límite de bytes en el contenido devuelto para evitar llenar todo el repositorio en el contexto.

Cómo aceptar el ciclo de llamada de herramienta

Cada llamada se registra:

Nombre de la herramienta propuesta por el Agente.
Parámetros originales.
Resultados de la verificación de parámetros.
Código de salida de herramienta.
Salida truncada.
Conclusión final del agente.

Los ejecutores de herramientas no deben extender los permisos por su cuenta basándose en el lenguaje natural.

Cuando el Agente solicita leer un archivo, por cierto no puede permitir la escritura.

No confíes en la unión del texto del chat para continuar con el estado

Si la API devuelve un identificador de interacción reanudable, primero se utilizará el mecanismo de estado oficial.

El envío manual de todos los mensajes históricos repetidamente aumentará los costos y también puede causar que se pierda el estado de la herramienta.

Antes de continuar, confirme si la ejecución anterior se completó, esperó la herramienta o falló.

No continúe el estado de fracaso directamente como un contexto de éxito.

Las operaciones de escritura adoptan el envío en dos fases

La primera etapa solo genera diferencias.

La segunda fase se aplica después de la aprobación por parte de un motor humano o de políticas.

1
2


git diff --check
git diff --stat

Realice un conjunto mínimo de pruebas después de la aplicación.

Cuando la prueba falla, mantenga el árbol de trabajo y los registros, y no permita que el Agente limpie automáticamente la evidencia.

Agregar una lista de permitidos explícita a la herramienta de comando

Primero puedes permitir:

1
2
3
4


git status --short
git diff --check
npm test -- --runInBand
python -m pytest tests/unit

Denegar empalme de comandos, redirección, ejecución de descargas y escalada de privilegios.

No coincida simplemente con el comienzo del comando.

También es necesario verificar los parámetros.

Tres límites para el control de costes

Establezca el número máximo de pasos del Agente.

Establezca el límite máximo de salida para una sola herramienta.

Establece límites de tiempo y presupuesto para toda la interacción.

Después de alcanzar el límite, regrese a la evidencia existente y “inconclusa”, no pretenda estar completo.

Posicionamiento fallido común

401 Primero verifique la clave y el proyecto.

403 Verifique si la API está abierta, las calificaciones de la cuenta y la región.

429 Distinga entre cuota de minutos, cuota diaria y límite de concurrencia.

Cuando una herramienta llama a los mismos parámetros repetidamente, generalmente significa que los resultados devueltos no están lo suficientemente estructurados.

La respuesta final es inconsistente con diff y debería basarse en el árbol de trabajo real.

Una tarea de prueba confiable

Prepare una prueba unitaria que falle a propósito.

Se pide al Agente que averigüe la causa, pero se le prohíbe redactar expedientes en la primera ronda.

Confirme que lea los archivos fuente relevantes y pruebe el resultado.

La segunda ronda permite la generación de parches.

Aplique y ejecute pruebas después de la revisión manual de parches.

Finalmente, abra una nueva interacción y deje que otro proceso de inspección revise la diferencia.

Esto expone problemas de permisos y estado más que permitir que el Agente modifique proyectos reales.

Comprueba antes de conectarte

Los cambios de vista previa están bloqueados en versiones explícitas del SDK.
Las llaves no ingresan al almacén ni a los registros.
Las herramientas de archivos están restringidas al directorio raíz del sandbox.
Los argumentos del comando se analizan en lugar de buscar coincidencias con el prefijo de cadena.
Las escrituras deben ser aprobadas por diff.
Hay límites en el número de pasos, tiempo, producción y tarifas.
El estado de falla conserva la evidencia.

El objetivo de Antigravity Agent no es “la capacidad de escribir código automáticamente”, sino si puede completar tareas de código dentro de límites observables, detenibles y de reversión.

Entrada oficial API del agente

Diseñe el valor de retorno de la herramienta para que sea JSON estable

Las herramientas no deberían devolver un bloque completo de texto de terminal con un estado indistinguible. El resultado de la lectura del archivo contiene al menos path, encoding, truncated y content; el resultado del comando contiene al menos exit_code, stdout, stderr y duration_ms. Sólo el Agente puede distinguir entre “fallo del comando” y “comando exitoso pero sin resultado”.

1
2
3
4
5
6
7
8


{
  "tool": "read_file",
  "ok": true,
  "path": "src/app.py",
  "encoding": "utf-8",
  "truncated": false,
  "content": "print('hello')"
}

Los resultados del ejecutor de comandos pueden utilizar las siguientes formas:

1
2
3
4
5
6
7
8


{
  "tool": "run_test",
  "ok": false,
  "exit_code": 1,
  "stdout": "3 passed, 1 failed",
  "stderr": "",
  "duration_ms": 1842
}

ok` lo genera el ejecutor en función del código de salida y el modelo en sí no puede completarlo. Cuando se trunca la salida, también devuelve la posición de truncamiento y permite que el Agente solicite un rango más pequeño de registros.

Procesamiento después de la interrupción de la respuesta de transmisión

La interrupción de la red no significa que la tarea no se ejecute. Consultar el estado de la interacción antes de volver a intentarlo; si el servidor ha aceptado los resultados de la herramienta, el envío repetido puede hacer que la operación de escritura se ejecute dos veces.

Agregue claves idempotentes para cada herramienta de escritura. La clave consta de ID de interacción, ID de llamada de herramienta y recurso de destino, y el ejecutor devuelve el primer resultado cuando encuentra la misma clave.

1

idempotency_key = interaction_id + tool_call_id + target

Si el SDK oficial no expone una interfaz de consulta de estado, deje la operación de escritura en la etapa de confirmación humana y no vuelva a intentarlo automáticamente en un estado incierto.

Vista previa del registro de actualización de la versión

Cada vez que se actualiza el SDK, se guardan la diferencia del archivo de bloqueo, los cambios en el campo de solicitud, los cambios en el campo de respuesta y una grabación exitosa. Primero reproduzca la tarea de prueba fija y luego abra el almacén real.

En particular, verifique si se ha cambiado el nombre de los parámetros de llamada de la herramienta, si se ha aumentado la enumeración de estado y si el nuevo SDK puede continuar con la interacción anterior. Cuando la tarea no se pueda continuar, deje que la tarea anterior finalice de forma natural y no cambie de versión durante la operación.

Una prueba de inyección de fallas

Haga que la herramienta de lectura devuelva un tiempo de espera para confirmar que el agente no interpreta el tiempo de espera como una inexistencia del archivo. Haga que el comando de prueba devuelva un código de salida de 1 y un stderr vacío para confirmar que aún falla. Deje que la herramienta de escritura devuelva “Ejecutado pero se perdió la respuesta” para confirmar que el mecanismo idempotente puede evitar la segunda escritura.

Finalmente revoque la clave de prueba y vuelva a ejecutar la misma tarea. El sistema debería detenerse durante la fase de autenticación y no solicitar más permisos de archivos.

Crear registros de auditoría locales para Interacción

Los registros de auditoría no guardan el código fuente completo ni las indicaciones, solo los metadatos necesarios para las operaciones de posicionamiento. La estructura recomendada es la siguiente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
  "interaction_id": "int_example",
  "started_at": "2026-07-27T03:00:00Z",
  "model": "replace-with-current-model",
  "repository": "demo-api",
  "base_commit": "8c18d4a",
  "tool_policy": "readonly-v2",
  "tool_calls": 7,
  "write_approved": false,
  "result": "needs_review"
}

repository` Utilice alias internos para evitar escribir nombres de clientes en registros centralizados. Los fragmentos de código fuente solo se guardan en archivos adjuntos de tareas con permisos más estrictos y se establecen tiempos de vencimiento independientes.

Los parámetros aún deben volver a verificarse después de la aprobación manual

Puede haber una diferencia horaria entre los parámetros mostrados en la interfaz de aprobación y los parámetros recibidos por el ejecutor. Las rutas canónicas, los argumentos de comando y los hashes de contenido se recalculan antes de la ejecución; cualquier cambio invalida la aprobación original.

1

approval = hash(tool_name + normalized_arguments + target_revision)

El Agente debe regenerar la diferencia cuando la rama de destino cambia mientras espera la aprobación. No aplique silenciosamente parches antiguos a nuevas versiones de código.

Dejar un estado continuable al salir

Archivos de salida que se han leído, hipótesis que aún no se han verificado, la última invocación exitosa de la herramienta y el estado del árbol de trabajo cuando se alcanza el presupuesto, se agota el tiempo de espera o se cancela manualmente.

La siguiente ejecución parte de estos hechos y no requiere volver a escanear todo el almacén. Si el árbol de trabajo contiene modificaciones no confirmadas, depende de los humanos decidir si continuar, guardar el parche o descartarlo, y el Agente no lo limpiará por sí solo.