Arquitectura ADK + A2A: SequentialAgent y artefactos compartidos

Visión general

El sistema tiene dos capas:

1. Orchestrator — gestiona el flujo de ejecución (DAG, reintentos, rollback). No ejecuta tareas de infraestructura.
2. 7 agentes especializados — cada uno con una responsabilidad única, coordinados por el Orchestrator vía SequentialAgent.

SequentialAgent — el orquestador de ADK

SequentialAgent es un componente built-in de Google ADK que ejecuta sub-agentes en orden determinista. No usa LLM para decidir la secuencia — la ejecución es fija y predecible. Le pasas la lista de agentes y ADK se encarga del ciclo completo.

from google.adk.agents import SequentialAgent

orchestrator = SequentialAgent(
    name="idp_orchestrator",
    sub_agents=[
        platform_architect,   # 1. Define stack → platform-config.yaml
        infrastructure,       # 2. Lee YAML    → docker-compose.yml
        security,             # 3. Escanea     → security-report.json
        cicd,                 # 4. Genera      → cicd/ + Jenkinsfile
        observability,        # 5. Configura   → grafana-dashboards/
        devex,                # 6. Genera CLI  → cli-tool/idp
        web_portal            # 7. Construye   → portal/
    ]
)

DAG de ejecución y dependencias

El Orchestrator construye un grafo de dependencias antes de ejecutar. Cada agente depende de los outputs de los anteriores:

Platform Architect (~12s)
    └── Infrastructure (~18s)
            ├── Security (~14s)
            │       └── CI/CD (~16s)
            │               └── Observability (~19s)
            │                       └── DevEx (~15s)
            │                               └── Web Portal (~45s)
            └── [Web Portal también lee docker-compose]

Tiempo total: ~4.5 minutos. El Web Portal es el agente más costoso porque lee la configuración completa de todos los agentes anteriores para generar el portal.

Configuración del Orchestrator

MAX_RETRIES = 3            # Intentos antes de declarar fallo
TIMEOUT_PER_AGENT = 300    # 5 minutos máximo por agente
BACKOFF_MULTIPLIER = 2     # Backoff exponencial entre reintentos

Flujo completo de ejecución

┌─────────────────────────────────────────────────────┐
│ 1. INPUT DEL USUARIO                                │
│    "Build IDP for Python FastAPI apps"              │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 2. ORCHESTRATOR                                     │
│    — Parsea la tarea                                │
│    — Construye el DAG de ejecución                  │
│    — Inicializa el contexto global                  │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 3. PLATFORM ARCHITECT (~12s)                        │
│    Input:  descripción de la tarea                  │
│    Output: platform-config.yaml                     │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 4. INFRASTRUCTURE (~18s)                            │
│    Input:  platform-config.yaml                     │
│    Output: docker-compose/app-stack.yml             │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 5. SECURITY (~14s)                                  │
│    Input:  docker-compose.yml + Dockerfiles         │
│    Output: security-report.json                     │
│    Decision: APPROVED / BLOCKED                     │
└─────────────────────────────────────────────────────┘
                    ↓ (solo si APPROVED)
┌─────────────────────────────────────────────────────┐
│ 6. CI/CD (~16s)                                     │
│    Input:  platform-config.yaml + security OK       │
│    Output: cicd/ + Jenkinsfile                      │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 7. OBSERVABILITY (~19s)                             │
│    Input:  platform-config.yaml                     │
│    Output: prometheus.yml + grafana-dashboards/     │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 8. DEVEX (~15s)                                     │
│    Input:  todos los outputs anteriores             │
│    Output: cli-tool/idp                             │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 9. WEB PORTAL (~45s)                                │
│    Input:  toda la configuración del IDP            │
│    Output: portal/ (FastAPI + HTMX)                 │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ 10. ORCHESTRATOR — RESUMEN FINAL                    │
│     Output: orchestration-report.json               │
│     Tiempo total: ~4.5 min | 21 archivos | 7/7      │
└─────────────────────────────────────────────────────┘

Manejo de errores

Retry con backoff exponencial

Antes de declarar un fallo, el Orchestrator reintenta automáticamente con espera creciente entre intentos:

for attempt in range(MAX_RETRIES):   # 3 intentos
    try:
        result = await agent.execute()
        break
    except TimeoutError:
        wait_time = BACKOFF_MULTIPLIER ** attempt   # 1s → 2s → 4s
        await asyncio.sleep(wait_time)
    except AgentError as e:
        if e.severity == "critical":
            raise   # Fallo crítico → rollback inmediato
        else:
            continue   # Fallo no crítico → reintento

Rollback en fallos críticos

Si un agente falla de forma crítica después de 3 intentos:

1. El Orchestrator detecta el fallo
2. Invoca rollback en orden inverso para los agentes completados
3. Limpia los archivos generados
4. Guarda el estado del fallo en orchestration-report.json

El rollback preserva la posibilidad de reiniciar desde el agente que falló sin perder el trabajo de los anteriores.

Nota

El Security Agent produce un fallo crítico si detecta vulnerabilidades de severidad CRITICAL, deteniendo el pipeline antes de CI/CD. El resto de los agentes no se ejecutan hasta que el reporte de seguridad esté aprobado.

Formato de mensajes A2A

Cada agente escribe un reporte de su ejecución que el Orchestrator lee para construir el orchestration-report.json final:

{
  "agent_id": "infrastructure-agent",
  "timestamp": "2026-01-29T10:30:15Z",
  "status": "success",
  "result": {
    "files_generated": [
      "docker-compose/app-stack.yml"
    ],
    "decisions": {
      "database": "PostgreSQL 15 — robusto y compatible con FastAPI",
      "cache": "Redis Alpine — imagen mínima para el scope local"
    }
  }
}

→ Ver en detalle: cómo A2A funciona con artefactos compartidos