Un agente, tres implementaciones: Interactions API vs ADK vs Antigravity SDK
El mismo agente de Gemini creó tres métodos, utilizando la Interactions API, Google ADK y el Antigravity SDK, y los comparó en términos de bucles, herramientas, autenticación y despliegues en Cloud Run.
Fuentes: I built the same agent three ways: Interactions API, ADK, and the Antigravity SDK
La plataforma de Google ahora ofrece tres enfoques bastante diferentes para crear un agente funcional: la Interactions API, que representa la interfaz de la era de los agentes en la Gemini API; ADK, un framework completo; y el Antigravity SDK, el componente que sustenta la Antigravity CLI. Una forma adecuada de compararlos es crear un agente tres veces y observar qué cambia: quién controla el ciclo del agente, cómo se integran las herramientas y qué modelos funcionan. Cada versión también se envía a Cloud Run.
El agente de prueba
Cada compilación responde a un tipo de pregunta, concretamente la opinión pública sobre un tema tal como se muestra en Hacker News. Se obtiene la información de bigquery-public-data.hacker_news.full, un conjunto de datos público que abarca 49 millones de historias y comentarios, y que está desfasado en aproximadamente un día con respecto a lo que ocurre en tiempo real. Las tres versiones necesitan el mismo conjunto de capacidades: escribir SQL a partir de una pregunta sencilla, ejecutarlo y resumir las opiniones que se obtienen.
BigQuery se integra de manera diferente cada vez. La API Interactions utiliza una función escrita a mano, ADK emplea su propio conjunto de herramientas y el SDK Antigravity hace uso de MCP.
Credenciales
Hay dos tipos de credenciales involucradas:
export GOOGLE_API_KEY="..." # get this at aistudio.google.com
gcloud auth application-default login
Existen dos credenciales porque la API Interactions en esta configuración se basa en la API Gemini, la cual requiere una clave, mientras que ADK y el SDK Antigravity se dirigen directamente al proyecto en la nube y omiten por completo las claves.
Si observamos más de cerca la API Interactions: acepta ya sea model=, un modelo simple, o agent=, un agente alojado por Google cuyos bucles y herramientas accesibles se ejecutan en la plataforma. La herramienta en esta versión es una función local de Python, lo que descarta la posibilidad de utilizar un agente alojado; por lo tanto, se utiliza model= y el bucle de la herramienta permanece en el código local. La plataforma empresarial de Google (anteriormente Vertex AI) cuenta con su propia versión experimental de la API, pero probarla con varios modelos generó rechazos en todas las llamadas con model=.
La versión gratuita de BigQuery, que permite 1 TB de consultas al mes, absorbe sin problemas las consultas de demostración, cuyo tamaño oscila entre 1 y 17 GB. Las versiones utilizadas durante las pruebas fueron google-genai 2.17.0, google-adk 2.6.2 y google-antigravity 0.1.10, con el modelo gemini-3.6-flash.
Ruta uno: la API de Interacciones
Instale los paquetes con pip install google-genai google-cloud-bigquery. La herramienta consiste en una función sencilla de unas diez líneas:
def execute_sql(query: str) -> list[dict]:
client = bigquery.Client()
config = bigquery.QueryJobConfig(maximum_bytes_billed=20 * 10**9)
rows = client.query_and_wait(query, job_config=config, max_results=50)
return [{k: str(v) for k, v in dict(row).items()} for row in rows]
Ejecuta cualquier consulta SQL que genere el modelo y devuelve hasta 50 filas como diccionarios simples. maximum_bytes_billed limita una consulta a 20 GB de escaneo, por lo que nada se vuelve costoso. No hay manejo explícito de credenciales porque bigquery.Client() utiliza el inicio de sesión local de gcloud, y en Cloud Run la misma línea emplea silenciosamente la cuenta de servicio.
El modelo nunca ve el cuerpo de la función, solo lo que está declarado, por lo que la declaración incluye el esquema:
execute_sql_tool = {
"type": "function",
"name": "execute_sql",
"description": (
"Run a BigQuery Standard SQL SELECT query against "
"`bigquery-public-data.hacker_news.full`, the public Hacker News "
"dataset (stories and comments since 2006). Columns: id INT, "
"type STRING (story/comment/job/poll), title STRING (stories only), "
"text STRING (body, HTML-escaped), `by` STRING (username), score INT, "
"parent INT, descendants INT, timestamp TIMESTAMP, url STRING, "
"dead BOOL, deleted BOOL. Returns at most 50 rows."
),
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
}
El bloque parameters se mantiene pequeño: una cadena obligatoria que contiene el SQL. La descripción es más importante, ya que es el único canal a través del cual el modelo aprende el nombre de la tabla y sus columnas. Una redacción más precisa allí genera consultas mejores.
Lo que queda es el bucle de la herramienta, de alrededor de una docena de líneas:
while True:
calls = [s for s in interaction.steps if s.type == "function_call"]
if not calls:
break
results = [{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(execute_sql(**step.arguments))}],
} for step in calls]
interaction = client.interactions.create(
model=MODEL,
input=results,
system_instruction=INSTRUCTION,
tools=[execute_sql_tool],
previous_interaction_id=interaction.id,
)
Una ronda ejecuta cada paso function_call emitido por el modelo, envía las salidas como la siguiente entrada y continúa en bucle hasta que una respuesta no tenga más llamadas. Un detalle que destaca es que el historial nunca se vuelve a enviar; el servidor lo almacena y previous_interaction_id simplemente hace referencia a la ronda anterior, lo que mantiene pequeñas las solicitudes. El objeto client es la puerta de entrada del SDK a la API de Gemini, y al crearlo sin argumentos se obtiene GOOGLE_API_KEY del entorno. Al desplegarse en Cloud Run, ese mismo valor se monta como una variable de entorno desde Secret Manager. Todo lo demás, incluyendo qué SQL ejecutar y cuándo detenerse, corresponde a las decisiones del modelo.
MCP aún no es una opción aquí. La documentación de la API de Interacciones lo enumera como una limitación, indicando que Gemini 3 no soporta MCP remoto y que está por llegar.
Veredicto: la mayor cantidad de código, la menor cantidad de dependencias y control total.
Ruta dos: ADK
Instálalo con pip install google-adk google-cloud-dataplex google-cloud-bigquery.
import google.auth
from google.adk import Agent
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode
credentials, _ = google.auth.default()
toolset = BigQueryToolset(
credentials_config=BigQueryCredentialsConfig(credentials=credentials),
bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED),
)
root_agent = Agent(name="hn_opinion_agent", model=..., instruction=..., tools=[toolset])
ADK incluye una integración lista para usar con BigQuery llamada BigQueryToolset. Junto con execute_sql, ofrece herramientas de metadatos como get_table_info, que permite al agente leer el esquema directamente en lugar de recibirlo en un mensaje. Una configuración, WriteMode.BLOCKED, convierte todo en solo lectura.
No aparece ninguna clave API. El conjunto de herramientas de BigQuery exige un objeto de credenciales explícito, el cual google.auth.default() devuelve a partir del inicio de sesión local en gcloud, junto con un ID de proyecto que esta versión descarta. Por parte del modelo, una sola variable realiza la función: GOOGLE_GENAI_USE_ENTERPRISE=TRUE dirige el tráfico del modelo a través de la cuenta de Cloud. Una vez en Cloud Run, tanto las consultas como las solicitudes del modelo se realizan bajo la cuenta de servicio.
El framework ejecuta el bucle y mantiene las sesiones, incluido el historial de conversaciones a lo largo de los intercambios, en memoria aquí y en una base de datos cuando se necesita persistencia.
Veredicto: código mínimo y capacidades máximas, ya que las herramientas preconstruidas permiten al agente explorar los datos por sí mismo.
Ruta tres: el Antigravity SDK
Instálalo con pip install google-antigravity.
from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStreamableHttpServer
bigquery_mcp = McpStreamableHttpServer(
name="bigquery",
type="http",
url="https://bigquery.googleapis.com/mcp",
headers={"Authorization": f"Bearer {token}",
"x-goog-user-project": project},
enabled_tools=["execute_sql_readonly", "get_table_info", ...],
)
config = LocalAgentConfig(system_instructions=..., mcp_servers=[bigquery_mcp])
async with Agent(config) as agent:
response = await agent.chat(question)
Al arnés se le proporciona una instrucción de sistema y un servidor MCP, y una sola llamada a agent.chat() abarca la planificación, el uso de herramientas y el resumen final. Debajo se encuentra el bucle que impulsa la CLI de Antigravity, que incluye sus herramientas de archivo y shell.
Se accede a BigQuery a través de MCP, por medio de bigquery.googleapis.com/mcp, un endpoint gestionado por Google que solo acepta OAuth (obtenido mediante gcloud auth print-access-token). La lista enabled_tools funciona como una lista de permisos de las herramientas MCP que el agente puede utilizar. Tanto execute_sql como execute_sql_readonly están disponibles en el endpoint, y al activar solo la segunda opción se evita que este agente escriba datos. La autenticación de modelos coincide con ADK, utilizando la cuenta de Cloud en una laptop y la cuenta de servicio en Cloud Run.
Existen dos consideraciones antes de elegirlo:
- Los modelos están limitados a Gemini. El IDE Antigravity también ofrece Claude y GPT-OSS, funciones que faltan en el SDK, aunque un servidor local compatible con OpenAI como Ollama puede servir como alternativa.
- El ID del proyecto debe indicarse en las instrucciones del sistema. Cada herramienta en el endpoint alojado requiere un argumento
projectIdque nombre el proyecto en la nube que ejecuta la consulta, y el modelo lo completa al llamar a la herramienta.
Veredicto: una opción práctica para contar con un agente que también puede editar archivos y ejecutar comandos de shell.
Despliegue en Cloud Run
Los tres se pueden desplegar en Cloud Run. Lo que difiere es la cantidad de código que se debe escribir para el servicio.
- API de interacciones: basta con un pequeño wrapper de FastAPI alrededor del bucle. Dado que el servidor almacena la conversación, el servicio en sí no mantiene ningún estado, y quienes lo llaman solo devuelven
previous_interaction_id. El problema es que esta API aún no puede autenticarse como cuenta de servicio, lo que la convierte en el único servicio que necesita una clave API, la cual proviene de Secret Manager. - ADK: no hay nada que configurar en el lado del servidor.
adk api_serverlo ejecuta localmente, mientras queadk deploy cloud_rungenera el servidor, el contenedor y la configuración de despliegue. Hay dos aspectos importantes a tener en cuenta. Primero, los paquetes adicionales del conjunto de herramientas (bigquery y dataplex) deben incluirse en el archivo requirements.txt de la carpeta del agente. Segundo, las variables de entorno no se transfieren durante el despliegue, por lo queGOOGLE_GENAI_USE_ENTERPRISEdebe añadirse posteriormente al servicio. Existe una opción completamente gestionada, Agent Runtime, para quienes no desean mantener ningún servicio. - Antigravity SDK: es necesario envolver manualmente a
agent.chat()y empaquetarlo como una imagen de contenedor. Solo hay un cambio relevante al servir: el encabezado MCP Authorization ya no puede provenir del inicio de sesión gcloud de una computadora portátil, por lo que el token debe generarse y renovarse desde la cuenta de servicio.
Restringir el acceso no requiere mucho esfuerzo. Al desplegar con --no-allow-unauthenticated se limita el acceso a quienes cuentan con permisos IAM. Para una llamada de prueba, adjunte un token de identidad con curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" o inicie gcloud run services proxy; en el caso de los navegadores, agregue IAP al principio.
La configuración de identidades fue prácticamente gratuita. Un servicio Cloud Run siempre se ejecuta bajo alguna identidad, y a menos que se indique lo contrario, se trata de la cuenta de servicio de cómputo predeterminada del proyecto. Una sola identidad gestionaba BigQuery para los tres servicios, así como las llamadas al modelo en ADK y Antigravity. El único permiso otorgado manualmente fue el de lectura de la clave API secreta del servicio Interactions, roles/secretmanager.secretAccessor, asociada al propio secreto.
No lo copies ciegamente, sin embargo. La cuenta predeterminada cuenta con permisos generosos y a menudo posee el rol de Editor a nivel de proyecto. Cualquier uso más allá de una demostración requiere una cuenta de servicio dedicada para cada servicio, limitada a los roles necesarios y proporcionados en el momento del despliegue mediante --service-account.
¿Cuál elegir?
ADK en Cloud Run constituye un punto de partida razonable para la mayoría de los trabajos. Ofrece un conjunto completo de herramientas y soporte para MCP, un manejo sencillo de sesiones e historial, además de la libertad de elegir cualquier modelo, no solo Gemini y Gemma. La API de Interacciones muestra cómo operan realmente los agentes, ya que el ciclo de ejecución está completamente visible. El SDK Antigravity es el más adecuado cuando un agente debe editar archivos y ejecutar comandos de shell.
Leer más
- Explicación de Gemini Spark: Tareas, habilidades, horarios, seguridad y precios — Qué hace el agente siempre activo Gemini Spark de Google en Gmail, Calendar y Docs, cómo funcionan sus capas de seguridad, cuánto cuesta, dónde está bloqueado y quién debería adoptarlo.
- Ingeniería agencial y el Outer Loop: Dónde encajan Antigravity y Agents CLI — Las especificaciones, las evaluaciones y las medidas de seguridad definen la ingeniería agencial. Un vistazo a la CLI de Agents de Google, su capa de producción en GCP y cómo Antigravity difiere de otras herramientas de programación.