Los 7 agentes: Dockerfile, agent.json y tools

3 cosas nuevas por agente

Para pasar de un agente local a un servidor A2A independiente en Cloud Run, cada agente necesita exactamente 3 cosas nuevas: un Dockerfile propio, un archivo agent.json y tools que acepten contexto via parámetro.

1. Dockerfile propio

Cada agente tiene su propio Dockerfile optimizado para Cloud Run:

FROM python:3.13-slim

WORKDIR /app

# Instalar uv (recomendado por Google para Cloud Run)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Copiar archivos de dependencias primero (cache de Docker)
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Copiar código del agente
COPY . .

# Puerto estándar de Cloud Run
EXPOSE 8080

# --a2a habilita los endpoints del protocolo A2A
CMD ["uv", "run", "adk", "api_server", "--a2a", "--port", "8080"]

3 decisiones clave:

• python:3.13-slim — no Alpine. grpcio (dependencia de ADK) no compila con musl libc, solo con glibc. Alpine usa musl y rompe el build.
• uv — no pip. Google recomienda uv para Cloud Run por velocidad de instalación y lockfile reproducible.
• --a2a flag — habilita los endpoints del protocolo A2A (/.well-known/agent.json, /run, etc.). Sin este flag, el servidor ignora las rutas A2A.

2. agent.json

Cada agente necesita un archivo agent.json que describe sus capacidades. Ejemplo para Platform Architect:

{
  "name": "Platform Architect",
  "description": "Analyzes project requirements and defines the complete technology stack, infrastructure decisions, and architectural patterns for the IDP.",
  "url": "http://localhost:8080",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "analyze_and_design",
      "name": "Analyze and Design Platform",
      "description": "Analyzes project requirements and produces a comprehensive platform configuration with technology choices, infrastructure patterns, and architectural decisions.",
      "tags": ["architecture", "design", "platform", "stack"]
    }
  ]
}

Este archivo es obligatorio para el protocolo A2A. Si falta, el servidor ADK arranca sin error pero ignora silenciosamente al agente — no aparece en /.well-known/agent.json y no responde a /run.

El array skills sigue el patrón de Agent Skills: describe qué sabe hacer el agente para que otros agentes (o el orquestador) puedan descubrirlo.

3. Tools que aceptan contexto

Cada tool necesita un parámetro context_json para recibir el contexto acumulado de los agentes anteriores:

Antes (local):

def generate_infrastructure() -> dict:
    config = load_yaml('/app/outputs/platform-config.yaml')
    # genera Docker Compose basado en config

Después (Cloud Run):

def generate_infrastructure(context_json: str = "") -> dict:
    if context_json:
        config = json.loads(context_json)
    else:
        config = load_yaml('/app/outputs/platform-config.yaml')
    # genera Docker Compose basado en config

El parámetro tiene default vacío para mantener compatibilidad con ejecución local. Si context_json tiene contenido, lo parsea. Si no, hace fallback a disco. Este patrón se repite en 6 de los 7 agentes — Platform Architect no lo necesita porque es el primero de la cadena.

adk deploy cloud_run vs Dockerfile propio

ADK incluye un comando para deploy rápido, pero tiene limitaciones:

Aspecto	adk deploy cloud_run	Dockerfile propio
Python	3.11	3.13
Package manager	pip	uv con lockfile
Dockerfile	Temporal, generado al vuelo	Versionado en el repo
Uso ideal	Demos rápidas, pruebas	Producción

adk deploy cloud_run es útil para probar un agente rápidamente. Para producción, el Dockerfile propio te da control total sobre versiones, dependencias y reproducibilidad.

Estructura de carpetas

Cada agente es un directorio independiente con todo lo necesario para construir su contenedor:

platform_architect/
├── Dockerfile
├── agent.json
├── agent.py
├── pyproject.toml
├── uv.lock
└── __init__.py

Los 7 agentes siguen esta misma estructura. Cada uno es un proyecto Python independiente con su propio pyproject.toml y uv.lock.

---

Siguiente paso: Deploy — 7 servicios en Cloud Run →