A2A Protocol

A2A Protocol Integration Guide

Companion del AI-First Engineering Framework v7.4.0

Version: 1.0.0 | Fecha: Marzo 2026 Fuentes: Google A2A Spec (2025), Linux Foundation (2025-2026), Framework MCP Integration Guide

1. Que es A2A y cuando usarlo

Agent2Agent (A2A) es un protocolo abierto creado por Google (Abril 2025) y donado a la Linux Foundation, que estandariza la comunicacion entre agentes AI de distintos proveedores, frameworks y organizaciones.

A2A vs MCP: complementarios, no competidores

┌───────────────────────────────────────────────┐
│               Tu Sistema AI                    │
│                                                │
│  ┌────────┐    A2A Protocol    ┌────────┐     │
│  │Agent A │◄──────────────────►│Agent B │     │
│  └───┬────┘  agent↔agent       └───┬────┘     │
│      │ MCP (agent↔tools)           │ MCP      │
│      ▼                             ▼          │
│  ┌────────┐                   ┌────────┐      │
│  │ Tools  │                   │ Tools  │      │
│  └────────┘                   └────────┘      │
└───────────────────────────────────────────────┘

Aspecto	MCP	A2A
Relacion	Agent ↔ Tools/Resources	Agent ↔ Agent
Proposito	Dar capacidades al agente	Coordinar trabajo entre agentes
Descubrimiento	.well-known/mcp.json	.well-known/agent.json
Transporte	JSON-RPC sobre stdio/HTTP	HTTP + JSON-RPC, SSE
Estado	Stateless	Stateful (Tasks con lifecycle)
Creador	Anthropic (2024)	Google (2025) → Linux Foundation

Cuando usar cada uno

Escenario	Protocolo
Agente necesita buscar en base de datos	MCP
Agente necesita que otro agente analice datos	A2A
Agente necesita leer archivos de configuracion	MCP
Dos agentes negocian un plan de trabajo	A2A
Agente delega sub-tarea a agente de QA	A2A

---

2. Conceptos clave

Primitiva	Descripcion
Agent Card	Metadata publica del agente: identidad, capacidades, autenticacion
Task	Unidad de trabajo con lifecycle (created → working → completed/failed/cancelled)
Message	Comunicacion dentro de una Task entre agentes
Artifact	Resultado producido por el agente (archivos, datos estructurados)
Part	Componente atomico de un Message o Artifact (texto, archivo, datos)
Streaming	Actualizaciones en tiempo real via SSE durante ejecucion de Task
Push Notification	Notificacion asincrona de cambio de estado de Task

Modelo de interaccion

Client Agent                          Server Agent
     │  1. GET /.well-known/agent.json     │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│  2. Agent Card
     │  3. POST /tasks/create              │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│  4. Task {status: working}
     │  5. GET /tasks/{id}                 │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│  6. Task {status: completed, artifacts}

---

3. Agent Card

El Agent Card es el documento de identidad de un agente A2A. Se publica en /.well-known/agent.json para discovery automatico.

Campo	Tipo	Req	Descripcion
name	string	Si	Nombre del agente
description	string	Si	Que hace el agente
version	string	No	Version semver
url	string	No	URL base del agente
capabilities	array	No	Capacidades con schemas de I/O
skills	array	No	Habilidades categorizadas
authentication	object	No	Tipo de auth requerida
supported_protocols	array	No	Protocolos: a2a, mcp, rest, grpc
constraints	object	No	Limites: RPM, concurrencia, tamano
provider	object	No	Organizacion, contacto, docs URL

Ejemplo de Agent Card

{
  "name": "data-analyst-agent",
  "description": "Agente de analisis de datos y generacion de reportes",
  "version": "1.2.0",
  "url": "https://mi-agente.ejemplo.com",
  "capabilities": [{
    "name": "analyze_dataset",
    "description": "Analiza un dataset y produce insights",
    "input_schema": { "type": "object", "properties": { "data_url": { "type": "string" } } },
    "output_schema": { "type": "object", "properties": { "insights": { "type": "array" } } }
  }],
  "authentication": { "type": "oauth2", "required": true },
  "supported_protocols": ["a2a", "rest"],
  "skills": [
    { "id": "statistical-analysis", "name": "Analisis Estadistico", "description": "Regresion, correlacion" }
  ],
  "constraints": { "rate_limit_rpm": 60, "max_concurrent_tasks": 5, "max_message_size": 10485760 },
  "provider": { "organization": "Mi Empresa", "contact": "ai-team@miempresa.com" }
}

---

4. Task Lifecycle

Estados

created → working → completed
                  → failed
                  → cancelled

Estado	Descripcion
created	Task recibida, pendiente de inicio
working	Agente procesando la tarea
completed	Tarea terminada con exito, artifacts disponibles
failed	Tarea fallida con mensaje de error
cancelled	Tarea cancelada por cliente o servidor

Operaciones

Operacion	Metodo	Endpoint
Crear	POST	/tasks/create
Consultar	GET	/tasks/{id}
Cancelar	POST	/tasks/{id}/cancel
Enviar mensaje	POST	/tasks/{id}/messages
Streaming	GET	/tasks/{id}/stream (SSE)

Streaming (tareas de larga duracion)

GET /tasks/{id}/stream
Accept: text/event-stream

event: status
data: {"status": "working", "progress": "Analizando 50,000 registros..."}

event: artifact
data: {"name": "resultado.json", "parts": [{"type": "text", "text": "..."}]}

event: status
data: {"status": "completed"}

---

5. Seguridad

Modelo de amenazas

Amenaza	Mitigacion	OWASP
Suplantacion de identidad	Verificacion Agent Card + TLS	ASI-03
Inyeccion de prompts via mensajes	Input validation + sanitizacion	ASI-01
Exfiltracion de datos via artifacts	Clasificacion de datos + DLP	ASI-07
Denegacion de servicio	Rate limiting + circuit breakers	ASI-09
Escalacion de privilegios	Autorizacion granular por capability	ASI-03

Esquemas de autenticacion

Tipo	Uso recomendado
oauth2	Produccion, multi-tenant
bearer	APIs internas, service-to-service
api_key	Desarrollo, integraciones simples
none	Solo desarrollo local (nunca produccion)

Checklist de seguridad

seguridad_a2a:
  transporte:
    - tls_obligatorio: true
    - certificados_validos: true
  autenticacion:
    - tipo_configurado: true         # oauth2 | bearer | api_key
    - credenciales_rotadas: true
    - tokens_con_expiracion: true
  autorizacion:
    - capabilities_restringidas: true # Solo exponer lo necesario
    - scopes_por_cliente: true
    - audit_log_habilitado: true
  input_validation:
    - schemas_validados: true
    - tamano_maximo: true            # max_message_size en constraints
    - sanitizacion_prompts: true
  rate_limiting:
    - rpm_configurado: true
    - concurrent_tasks_max: true
    - circuit_breaker: true

---

6. Mapping al framework

F04 — Architecture: Agent Cards como componentes

Artefacto F04	Relacion con A2A
ai_partition_map.yaml	Definir que particiones se exponen como agentes A2A
integration_map.yaml	Registrar integraciones A2A como tipo a2a
a2a_agent_cards.yaml	Nuevo: catalogo de agent cards del proyecto

F05 — Contracts: Agent Cards SON contratos

Aspecto del contrato	Campo en Agent Card
Operaciones	capabilities[].name + description
Schema de entrada	capabilities[].input_schema
Schema de salida	capabilities[].output_schema
Versionado	version (semver)
Autenticacion	authentication
Limites de uso	constraints

Regla: cambios breaking en Agent Cards requieren version major.

F08 — Security: Auditoria de Agent Cards

Check	Que verificar
Auth configurada	authentication.type != "none" en produccion
Rate limiting	constraints.rate_limit_rpm > 0
Capabilities minimas	Solo exponer lo necesario
Input schemas	Toda capability con input_schema
TLS	url comienza con https://
Provider	provider.organization y contact presentes

F09 — Operations: Monitoreo A2A

Metrica	Alerta
a2a_tasks_created	Spike > 2x promedio
a2a_tasks_failed	> 5% del total
a2a_task_duration_p95	> SLO definido
a2a_messages_per_task	> 20 (posible loop)
a2a_auth_failures	> 10 en 5 minutos

---

7. Integracion con MCP

En un sistema bien arquitectado, MCP conecta agentes con herramientas y A2A conecta agentes entre si:

┌─────────────────────────────────────────────────┐
│                  Factory OS                      │
│                                                  │
│  ┌───────────┐   A2A    ┌───────────┐   A2A     │
│  │ FAB: Arch │◄────────►│ FAB: Build│◄────────┐ │
│  └─────┬─────┘          └─────┬─────┘         │ │
│        │ MCP                  │ MCP      ┌────▼┐│
│        ▼                      ▼          │ FAB ││
│  ┌──────────┐          ┌──────────┐      │ QA  ││
│  │MCP: Docs │          │MCP: Git  │      └──┬──┘│
│  │MCP: Search│         │MCP: Deploy│        │MCP│
│  └──────────┘          └──────────┘        ▼   │
│                                      ┌────────┐ │
│                                      │MCP:Test│ │
│                                      └────────┘ │
└─────────────────────────────────────────────────┘

Paso	Protocolo	Accion
Orchestrator delega arquitectura	A2A	Task a Arch Agent
Arch Agent consulta framework docs	MCP	Tool: search_framework_docs
Arch Agent devuelve ADR	A2A	Artifact: adr_001.md
Orchestrator delega build	A2A	Task a Build Agent
Build Agent usa Git tools	MCP	Tools: git_commit, run_tests

---

8. Template de Agent Card YAML

Usar en project/F04_architecture/a2a_agent_cards.yaml:

project: "mi-proyecto"
version: "1.0.0"

agents:
  - name: "mi-agente-principal"
    description: "Descripcion de lo que hace el agente"
    version: "1.0.0"
    url: "https://mi-agente.ejemplo.com"
    capabilities:
      - name: "procesar_solicitud"
        description: "Procesa una solicitud y devuelve resultado"
        input_schema:
          type: "object"
          properties:
            solicitud: { type: "string" }
          required: ["solicitud"]
        output_schema:
          type: "object"
          properties:
            resultado: { type: "string" }
            confianza: { type: "number" }
    authentication:
      type: "oauth2"
      required: true
    supported_protocols: ["a2a", "mcp"]
    skills:
      - id: "analisis"
        name: "Analisis de Datos"
        description: "Capacidad de analizar datasets"
    constraints:
      rate_limit_rpm: 60
      max_concurrent_tasks: 5
      max_message_size: 10485760
    provider:
      organization: "Mi Organizacion"
      contact: "equipo-ai@miorg.com"
      documentation_url: "https://docs.miorg.com/agentes"

---

9. Patron de implementacion

Paso 1: Definir el Agent Card

Crear project/F04_architecture/a2a_agent_cards.yaml con las capacidades del agente.

Paso 2: Publicar el Agent Card

# Endpoint .well-known/agent.json (ejemplo FastAPI)
@app.get("/.well-known/agent.json")
async def agent_card():
    with open("project/F04_architecture/a2a_agent_cards.yaml") as f:
        cards = yaml.safe_load(f)
    return cards["agents"][0]

Paso 3: Implementar endpoints A2A

# Endpoints basicos A2A (ejemplo conceptual)
@app.post("/tasks/create")
async def create_task(req: TaskCreate):
    task = {"id": generate_id(), "status": "created", "messages": [req.message]}
    process_task_async(task["id"])
    return task

@app.get("/tasks/{task_id}")
async def get_task(task_id: str):
    return tasks.get(task_id)

@app.post("/tasks/{task_id}/cancel")
async def cancel_task(task_id: str):
    tasks[task_id]["status"] = "cancelled"
    return tasks[task_id]

Paso 4: Validar y registrar

# Validar Agent Card contra schema
python3 baseline/scripts/artifact-validator.py -f project/F04_architecture/a2a_agent_cards.yaml

Registrar en project/F04_architecture/integration_map.yaml:

integrations:
  - id: "INT-A2A-001"
    name: "Agent A2A Principal"
    type: "bidirectional"
    protocol: "a2a"
    endpoint: "https://tu-agente.com"
    timeout_ms: 30000
    circuit_breaker: true

---

10. Interoperabilidad con Google Agent Development Kit (ADK)

Que es Google ADK

Google Agent Development Kit (ADK) es un framework open-source (lanzado en 2025) para construir agentes AI que son nativamente compatibles con el protocolo A2A. ADK proporciona:

• Scaffolding de agentes con Agent Card auto-generada
• Runtime A2A integrado (servidor HTTP con endpoints /tasks/* y /.well-known/agent.json)
• Orquestacion multi-agente con delegacion de tareas entre agentes ADK y no-ADK
• Herramientas integradas (Google Search, Code Execution, MCP bridges)

ADK simplifica la creacion de agentes que pueden participar en ecosistemas A2A sin implementar el protocolo manualmente.

Como los FABs pueden exponer Agent Cards para discovery

Un Fullstack Agent Builder (FAB) puede exponerse como agente A2A publicando su Agent Card en /.well-known/agent.json. El mapeo natural es:

Concepto FAB	Campo Agent Card A2A
Nombre del FAB (ej: fab-arch)	name
Fases ADLC asignadas (ej: F01-F04)	skills[].id → fase, skills[].description → alcance
Modelo base (ej: Claude Opus)	Metadata en description
Permisos (.claude/settings.json)	constraints + authentication
MCP tools configurados	capabilities[] — una por herramienta expuesta

# Ejemplo: FAB expuesto como agente A2A
agents:
  - name: "fab-architect"
    description: "FAB especializado en fases F01-F04: estrategia, dominio, conocimiento, arquitectura"
    version: "1.0.0"
    url: "https://factory.ejemplo.com/agents/fab-architect"
    capabilities:
      - name: "generate_architecture"
        description: "Genera ADRs y mapas de arquitectura desde requerimientos"
        input_schema:
          type: "object"
          properties:
            requirements: { type: "string" }
            track: { type: "string", enum: ["full", "lean", "solo"] }
          required: ["requirements"]
        output_schema:
          type: "object"
          properties:
            adrs: { type: "array" }
            architecture_map: { type: "object" }
      - name: "review_contracts"
        description: "Revisa contratos F05 contra arquitectura definida"
        input_schema:
          type: "object"
          properties:
            contracts_path: { type: "string" }
    skills:
      - id: "f01-strategy"
        name: "Estrategia"
        description: "Problem statement, stakeholder analysis, human-agent responsibility"
      - id: "f02-domain"
        name: "Dominio"
        description: "Domain model, bounded contexts, ubiquitous language"
      - id: "f03-knowledge"
        name: "Conocimiento"
        description: "Knowledge graph, RAG pipeline design"
      - id: "f04-architecture"
        name: "Arquitectura"
        description: "ADRs, integration maps, AI partition maps"
    authentication:
      type: "bearer"
      required: true
    supported_protocols: ["a2a", "mcp"]
    constraints:
      rate_limit_rpm: 30
      max_concurrent_tasks: 3
      max_message_size: 5242880
    provider:
      organization: "Factory OS"
      contact: "factory-ops@ejemplo.com"

Como testear interoperabilidad A2A

Para validar que un FAB puede interoperar con agentes ADK (o cualquier agente A2A):

1. Mock A2A Server — Simular un agente remoto para probar el cliente:

# mock_a2a_server.py — Servidor A2A minimo para testing
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

AGENT_CARD = {
    "name": "mock-agent",
    "description": "Agente mock para testing A2A",
    "version": "1.0.0",
    "capabilities": [{"name": "echo", "description": "Devuelve el input"}],
    "authentication": {"type": "none"},
}

TASKS = {}

class A2AHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/.well-known/agent.json":
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps(AGENT_CARD).encode())
        elif self.path.startswith("/tasks/"):
            task_id = self.path.split("/")[-1]
            task = TASKS.get(task_id, {"status": "not_found"})
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps(task).encode())

    def do_POST(self):
        if self.path == "/tasks/create":
            content_len = int(self.headers.get("Content-Length", 0))
            body = json.loads(self.rfile.read(content_len)) if content_len else {}
            task_id = f"task-{len(TASKS) + 1}"
            TASKS[task_id] = {
                "id": task_id,
                "status": "completed",
                "artifacts": [{"type": "text", "text": f"Echo: {body}"}],
            }
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps(TASKS[task_id]).encode())

# Usar: python mock_a2a_server.py → escucha en localhost:8080
if __name__ == "__main__":
    HTTPServer(("localhost", 8080), A2AHandler).serve_forever()

2. Validacion de Agent Card — Verificar que el Agent Card cumple el schema:

# Validar contra el JSON Schema del framework
python3 baseline/scripts/artifact-validator.py \
  -f project/F04_architecture/a2a_agent_cards.yaml

# Verificar discovery endpoint
curl -s http://localhost:8080/.well-known/agent.json | python3 -m json.tool

3. Test de interaccion completa — Ciclo create → poll → artifacts:

# Crear tarea
curl -X POST http://localhost:8080/tasks/create \
  -H "Content-Type: application/json" \
  -d '{"message": {"parts": [{"type": "text", "text": "Analizar requerimientos"}]}}'

# Consultar estado
curl -s http://localhost:8080/tasks/task-1

Ejemplo practico: FAB como agente A2A con fases ADLC

En un escenario Factory OS, cada FAB puede exponerse como agente A2A donde sus skills mapean directamente a fases del ADLC:

┌─────────────────────────────────────────────────────────┐
│                    Factory OS + A2A                       │
│                                                          │
│  ┌──────────────┐  A2A Task   ┌──────────────┐          │
│  │ Coordinator  │────────────►│ FAB Architect │          │
│  │ (Client)     │  "disenar   │ (Server A2A)  │          │
│  │              │   arch para │ skills: F01-F04│         │
│  │              │   feature X"│               │          │
│  │              │◄────────────│ Artifact: ADR │          │
│  │              │  completed  │               │          │
│  │              │             └──────────────┘           │
│  │              │  A2A Task   ┌──────────────┐          │
│  │              │────────────►│ FAB Builder   │          │
│  │              │  "implement │ (Server A2A)  │          │
│  │              │   segun ADR"│ skills: F06   │          │
│  │              │◄────────────│ Artifact: PR  │          │
│  └──────────────┘  completed  └──────────────┘          │
│                                                          │
│  Discovery: cada FAB publica /.well-known/agent.json     │
│  Coordinacion: A2A Tasks con lifecycle completo           │
│  Herramientas: cada FAB usa MCP internamente             │
└─────────────────────────────────────────────────────────┘

El flujo seria:

1. Coordinator descubre FABs disponibles via Agent Cards
2. Crea una A2A Task con los requerimientos como mensaje
3. El FAB ejecuta su flujo ADLC (F01→F04) internamente usando MCP para tools
4. Devuelve Artifacts (ADRs, contratos, codigo) al Coordinator
5. El Coordinator delega la siguiente fase a otro FAB via A2A

Limitaciones y trabajo pendiente para soporte runtime completo

Area	Estado actual	Lo que falta
Agent Card	Soportado via template YAML	Publicacion automatica desde .fab-config.yaml
Discovery	Manual (YAML estatico)	Registro dinamico en Factory OS (service mesh A2A)
Task lifecycle	No implementado en FABs	Runtime A2A (HTTP server) en cada FAB
Streaming	No soportado	SSE para tareas de larga duracion (builds, deploys)
Autenticacion	Solo documentada	Integracion con OAuth2/mTLS del Factory OS
ADK bridge	No existe	Wrapper para que FABs consuman agentes ADK como peers
Multi-factory	No soportado	Federation de Agent Cards entre factories independientes

Proximos pasos recomendados:

1. Implementar un runtime A2A minimo en fab-factory.sh que exponga Agent Cards
2. Agregar un bridge ADK en scripts/ para descubrir/invocar agentes ADK externos
3. Extender fab-coordinator.py para usar A2A Tasks en vez de file-locking para coordinacion
4. Integrar discovery automatico con el MCP server del framework

---

11. Referencia

Recursos oficiales

Recurso	URL
A2A Protocol Spec (Google)	https://github.com/google/A2A
A2A en Linux Foundation	https://www.linuxfoundation.org/projects/a2a
MCP Protocol Spec	https://modelcontextprotocol.io

Documentos del framework

Documento	Ruta
MCP Integration Guide	framework/guides/MCP_Integration_Guide.md
Multi-Agent Orchestration	framework/guides/Multi_Agent_Orchestration_Guide.md
OWASP Agentic Security	framework/guides/OWASP_Agentic_Security_Guide.md
Context Engineering	framework/guides/Context_Engineering_Guide.md

Schemas

Schema	Ruta
Agent Card	scripts/schemas/a2a_agent_card.schema.json
Integration Map	scripts/schemas/integration_map.schema.json

Glosario

Termino	Definicion
Agent Card	Documento JSON con metadata publica de un agente
Task	Unidad de trabajo con lifecycle en A2A
Message	Comunicacion entre agentes dentro de una Task
Artifact	Resultado/entregable producido por una Task
Part	Componente atomico de un Message o Artifact
Capability	Habilidad declarada con schemas de I/O
Client Agent	Agente que inicia una Task
Server Agent	Agente que ejecuta una Task