Investigación: ADK Agents en Producción con Usuarios Reales

ADK Agents en Producción: Investigación Técnica

Contexto: 7 agentes ADK deployados en Cloud Run como servidores A2A independientes, cada uno expone POST /tasks/send (JSON-RPC 2.0). Existe orchestrator_a2a.py en Python que los encadena. Necesitamos exponerlo a usuarios reales.

---

1. ADK como MCP Server

¿Qué es posible?

Sí, es oficialmente soportado. ADK permite dos direcciones de integración con MCP:

• ADK consume MCP: el agente usa tools de servidores MCP externos (patrón más documentado)
• ADK expone como MCP: envolver tools de ADK en un MCP server para que clientes externos (Claude Desktop, Cursor, etc.) las consuman

Implementación técnica

ADK usa FastMCP internamente. El patrón para exponer tools ADK:

from mcp.server.lowlevel import Server
from mcp import types as mcp_types
from google.adk.tools.function_tool import FunctionTool
from google.adk.tools.mcp_tool.conversion_utils import adk_to_mcp_tool_type

app = Server("my-adk-mcp-server")
adk_tool = FunctionTool(my_function)

@app.list_tools()
async def list_mcp_tools() -> list[mcp_types.Tool]:
    return [adk_to_mcp_tool_type(adk_tool)]

@app.call_tool()
async def call_mcp_tool(name: str, arguments: dict):
    result = await adk_tool.run_async(args=arguments, tool_context=None)
    return [mcp_types.TextContent(type="text", text=json.dumps(result))]

Transportes disponibles

• stdio: Para desarrollo local y Claude Desktop (proceso local)
• Streamable HTTP / SSE: Para producción multi-cliente vía HTTP
• Sidecar en GKE: Patrón Kubernetes con contenedores separados

Cómo lo consumiría Claude Desktop

{
  "mcpServers": {
    "mis-agentes-adk": {
      "command": "python",
      "args": ["my_adk_mcp_server.py"]
    }
  }
}

Para server remoto en Cloud Run con Streamable HTTP, Claude Desktop configura la URL directamente.

Limitación clave

Este patrón expone tools individuales (funciones), no el flujo completo del orquestador con sesiones y estado. Para exponer el orquestador de 7 agentes como un tool MCP, habría que envolver el orchestrator_a2a.py como una función.

Valoración para el video

Angulo interesante pero secundario. Útil para mostrar “cualquier cliente MCP puede usar tus agentes” pero no es la arquitectura de producción principal para usuarios web.

---

2. A2A + Orquestador con Frontend Real

Patrón recomendado por Google: Next.js + FastAPI + A2A

El patrón documentado en codelabs oficiales (InstaVibe, Deep Research Tool):

Usuario → Next.js / React frontend
              ↓ HTTP
         FastAPI / ADK API server (adk api_server)
              ↓ A2A Protocol (JSON-RPC 2.0)
         Orchestrator agent (Cloud Run)
              ↓ A2A Protocol
         7 agentes especializados (Cloud Run)

adk api_server: el puente clave

El comando adk api_server (o en producción, el servidor FastAPI integrado) expone:

Endpoint	Método	Función
/list-apps	GET	Verificar apps disponibles
/apps/{app}/users/{user_id}/sessions/{session_id}	POST	Crear sesión
/apps/{app}/users/{user_id}/sessions/{session_id}	PATCH	Actualizar estado
/run	POST	Ejecutar agente, respuesta completa JSON
/run_sse	POST	Ejecutar agente con streaming SSE
/docs	GET	Swagger UI automático

El flag --with_ui en el deploy incluye también la web UI de ADK (solo para dev/testing).

Streamlit: opción simple

adk api_server lanza los agentes + FastAPI. Streamlit se conecta a /run o /run_sse.

Problema: Streamlit es síncrono, el A2A SDK es async. Requiere run en thread separado o workaround. Funciona pero no es elegante.

FastAPI + React/Next.js: opción production-grade

Patrón usado en los codelabs oficiales de Google (Deep Research Tool, InstaVibe):

[Next.js + React] → [ADK API Server en Cloud Run] → [Orchestrator A2A] → [7 agentes]

Ventajas:

• SSE streaming nativo (/run_sse)
• Visualización de paralelismo (indicadores pulsantes por agente)
• Estado compartido entre frontend y agente vía AG-UI
• Full control sobre UX

AG-UI Protocol: el protocolo más reciente (2025-2026)

Google ADK se integra oficialmente con AG-UI (Agent-Generative UI), desarrollado en partnership con CopilotKit.

Arquitectura AG-UI:

React (CopilotKit hooks)
    ↓ AG-UI Protocol (streaming events)
ADK Middleware (FastAPI en puerto 8000)
    ↓ ADK internals
Orchestrator → 7 agentes A2A

Frontend en React/Next.js:

// Estado compartido bidireccional con el agente
const { state, setState } = useCoAgent<AgentState>({ name: "my_agent" })

// Render de tool calls como UI reactiva
useRenderToolCall({
  name: "search_agent_result",
  render: ({ args }) => <ResultCard data={args} />
})

// Chat integrado
<CopilotSidebar defaultOpen={true} />

Por qué es relevante para el video: muestra cómo cada tool call de los agentes puede renderizarse como un componente React en tiempo real.

GitHub: https://github.com/ag-ui-protocol/ag-ui

Valoración para el video

Este es el patrón más rico visualmente. ADK API Server + Next.js/AG-UI permite mostrar los 7 agentes ejecutando en paralelo con indicadores visuales reales.

---

3. ADK Agent Engine en Vertex AI

¿Qué es?

Vertex AI Agent Engine es un runtime completamente gestionado para agentes. A diferencia de Cloud Run (tú gestionas el contenedor), Agent Engine gestiona:

• Infraestructura de ejecución
• Sesiones persistentes (automático, no requiere configuración)
• Memoria a corto y largo plazo
• Observabilidad: dashboard de tokens, latencia, error rates, tool calls
• Playground integrado para testing
• Escala global automática

Comando de deploy

adk deploy agent_engine \
  --project=$PROJECT_ID \
  --region=$LOCATION_ID \
  --display_name="Mi Orquestador" \
  orchestrator_agent/

Esto envuelve el agente en reasoning_engines.AdkApp y lo despliega en el runtime gestionado.

Interacción programática post-deploy

import vertexai
agent_engine = vertexai.agent_engines.get(
  'projects/123/locations/us-central1/reasoningEngines/RESOURCE_ID'
)
# Endpoint REST:
# https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT}/
#   locations/{LOCATION}/reasoningEngines/{RESOURCE_ID}:query

Agent Engine vs Cloud Run: cuándo usar cada uno

Criterio	Agent Engine	Cloud Run
Gestión infraestructura	Completamente gestionado	Tú gestionas el contenedor
Sesiones	Automáticas, persistentes	Debes configurarlas explícitamente
Memoria long-term	Incluida (Memory Bank)	No incluida
Dashboard observabilidad	Incluido (tokens, latencia, traces)	Necesitas configurarlo
Costo	Más caro (servicio gestionado)	Más barato, escala a zero
Flexibilidad	Menos (entorno opinionado)	Total
Multi-agente A2A	Orquestador en AE, subagentes en CR	Todo en CR
Producción enterprise	Ideal	Válido con más configuración

Patrón híbrido (recomendado en codelabs InstaVibe)

Orchestrator → Vertex AI Agent Engine
Subagentes (7) → Cloud Run (A2A servers)
Sessions → Agent Engine Sessions (compartidas)

El Cloud Run service account necesita roles/aiplatform.user para llamar al Agent Engine.

Limitación actual

Agent Engine no incluye el ADK API Server ni la web UI por defecto. Para exponer a usuarios finales desde Agent Engine, necesitas un frontend que llame vía REST al endpoint de Vertex AI, con auth de Vertex AI (no trivial para usuarios públicos).

Valoración para el video

Excelente para mostrar la capa enterprise/managed. El dashboard de observabilidad es visualmente impresionante. Pero la exposición a usuarios finales requiere un proxy intermedio.

---

4. Patrón Recomendado por Google (end-to-end)

Según documentación oficial y codelabs 2025-2026

El patrón canónico de Google para producción con usuarios reales es:

[Usuario Web]
     ↓ HTTPS
[Frontend: Next.js / React]
     ↓ HTTP/SSE
[ADK API Server en Cloud Run]  ← adk deploy cloud_run --with_ui
     ↓ A2A Protocol
[Orchestrator Agent en Cloud Run o Agent Engine]
     ↓ A2A Protocol (JSON-RPC 2.0)
[Agente 1...N en Cloud Run]
     ↓
[Tools: MCP servers, APIs, DBs]

Comando de deploy completo

adk deploy cloud_run \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --service_name=orchestrator-service \
  --with_ui \
  orchestrator_agent/

Esto despliega:

1. Imagen Docker en Artifact Registry
2. Cloud Run service con ADK API Server
3. Endpoints /run, /run_sse, sesiones, Swagger
4. Web UI opcional en la raíz (dev/testing)

Para el escenario con 7 agentes ya deployados

Como ya tienes orchestrator_a2a.py que llama a los 7 agentes via HTTP:

1. Adaptar orchestrator_a2a.py a ADK Agent si no lo está (o crear un thin ADK wrapper)
2. Deploy del orquestador como ADK API Server en Cloud Run
3. Frontend Next.js que llama a /run_sse para streaming
4. Opcionalmente AG-UI si quieres UI reactiva per-agent

---

5. Autenticación en Producción

Capas de auth que existen

A. Auth entre agentes (agent-to-agent)

Para las llamadas Cloud Run → Cloud Run (A2A entre agentes):

# Service account con roles/run.invoker en el servicio destino
headers = {"Authorization": f"Bearer {get_id_token()}"}
MCPToolset(connection_params=StreamableHTTPConnectionParams(
    url=agent_url,
    headers=headers
))

Google Cloud maneja esto con Workload Identity o service accounts.

B. Auth de usuarios finales → Frontend

Opciones:

Opción	Caso de uso
Unauthenticated Cloud Run	Demo público, tutoriales, testing
Firebase Auth + JWT	Aplicación con usuarios registrados
Google IAP (Identity-Aware Proxy)	Empleados internos, B2B
API Key custom	Integraciones programáticas
OAuth 2.0	Apps de terceros accediendo en nombre del usuario

C. Auth del frontend → ADK API Server

Opción más simple para producción inicial (videos públicos):

# Deploy con acceso público
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$LOCATION_ID \
  --service_name=my-agent \
  orchestrator/
# Cuando pregunte: "Allow unauthenticated? → y"

Opción con auth (producción real):

# Deploy privado, requiere Identity Token
export TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" \
     -X POST https://my-service.run.app/run \
     -d '{"app_name":"orchestrator","user_id":"user1",...}'

D. Secret Manager para credenciales de los agentes

gcloud secrets add-iam-policy-binding GOOGLE_API_KEY \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

E. Auth en A2A Protocol (v0.2+)

El protocolo A2A v0.2 incluye esquemas de auth basados en OpenAPI:

• API Keys
• HTTP Bearer tokens
• OAuth 2.0 machine-to-machine
• OpenID Connect

Permite definir roles distintos: WebSearch client, Monitoring client, Gateway client, Host Agent.

Recomendación para el video

Para demostración en video: Cloud Run sin auth (--allow-unauthenticated) + rate limiting básico en el frontend. Simple, funciona, no requiere que el espectador gestione tokens.

Para producción real post-video: Firebase Auth → JWT → Cloud Run authenticated endpoint.

---

Resumen: Opciones rankeadas por fit para el video

Opción A: ADK API Server + Next.js (RECOMENDADA PRINCIPAL)

Stack: orchestrator_a2a.py → ADK API Server (Cloud Run) → Next.js frontend

• Patrón oficial de Google, documentado en codelabs
• /run_sse da streaming real
• Puedes mostrar los 7 agentes ejecutando en tiempo real
• Auth flexible (público para demo)
• Complejidad: Media. Requiere pequeño frontend Next.js

Opción B: ADK API Server + AG-UI + CopilotKit (RECOMENDADA SI QUIERES UI RICA)

Stack: ADK → FastAPI middleware AG-UI → React + CopilotKit hooks

• Cada tool call de agente se puede renderizar como UI reactiva
• Estado bidireccional frontend-agente
• Visualmente impresionante para un video técnico
• Partnership oficial Google + CopilotKit
• Complejidad: Alta. Requiere conocer React/CopilotKit

Opción C: ADK API Server + Streamlit (MÁS RÁPIDO DE IMPLEMENTAR)

Stack: orchestrator_a2a.py → ADK API Server → Streamlit

• ~100 líneas de código para una UI funcional
• El problema del async se resuelve con asyncio.run() en thread
• No es la solución más elegante pero funciona
• Complejidad: Baja

Opción D: Agent Engine (PARA MOSTRAR LA CAPA ENTERPRISE)

Stack: Orquestador en Vertex AI Agent Engine + subagentes en Cloud Run

• Dashboard de observabilidad impresionante visualmente
• Sesiones automáticas, memoria integrada
• Muestra la diferencia entre “deploy rápido” vs “enterprise managed”
• Complejidad: Media-alta. Auth de Vertex AI para usuarios externos requiere proxy

Opción E: Exponer como MCP Server (PARA ÁNGULO CLAUDE DESKTOP)

Stack: ADK tools wrapped en MCP Server → Claude Desktop / Cursor

• Muestra interoperabilidad del ecosistema
• Claude Desktop puede llamar tus agentes como tools
• Complejidad: Baja para local, media para producción remota
• Limitación: No es para usuarios web generales, es para devs con Claude Desktop

---

Recomendación final para el video

Narrativa sugerida para el video técnico:

1. Mostrar el problema: adk web es solo dev local, no sirve para usuarios reales
2. Capa 1 - Mínimo viable: adk api_server + Streamlit (10 minutos para tener algo funcionando)
3. Capa 2 - Producción real: ADK API Server en Cloud Run + Next.js con SSE streaming
4. Capa 3 - Enterprise: Mover orquestador a Agent Engine, dashboard de observabilidad
5. Bonus - Ecosistema: Exponer como MCP Server para Claude Desktop

El arco narrativo es la escalera de complejidad: de dev local → producción básica → producción enterprise → interoperabilidad con otros LLM clients.

---

Recursos clave

• Documentación oficial ADK deploy
• Agent Engine deploy
• ADK Runtime API Server
• MCP Tools (exponer ADK como MCP)
• AG-UI Integration
• InstaVibe codelab (patrón completo multi-agente)
• Deep Research Tool con A2A + Next.js
• AG-UI GitHub
• ADK + FastAPI + MCP blog
• End-to-End ADK + BigQuery MCP + Agent Engine (Mar 2026)