⬡ CULTIVA IA · Agentes IA · Skill

Protocolos de Comunicación Multi-Agente

Guía de referencia aplicada al equipo "Pack SEO Acelerado": tipos de mensaje, flujos de aprobación de plan, secuencia de cierre graceful y antipatrones a evitar.

Proyecto: Pack SEO Acelerado
4 agentes + 1 lead
5 fases · 5 días hábiles
Skill: protocolos-comunicacion-equipos-agentes
4
tipos de mensaje
5
fases del proyecto
6
antipatrones identificados
5
pasos de cierre graceful

Equipo asignado

Lead
orchestrator-1
Coordina fases, aprueba planes, gestiona cierre
Auditor
seo-auditor-1
Crawl técnico, Core Web Vitals, keyword gaps
Writer
content-writer-1
Redacción artículos SEO (lote A, art. 1–5)
Writer
content-writer-2
Redacción artículos SEO (lote B, art. 6–10)
QA
qa-reviewer-1
Revisión calidad, coherencia marca, checklist

Fases del proyecto

1
Kick-off y descubrimiento
2
Aprobación plan auditoría
3
Handoff auditoría → redactores
4
Broadcast cambio crítico
5
Cierre graceful del equipo

Mensajes por tipo — ejemplos reales del proyecto

message Fase 1 · Kick-off → auditor
El Lead arranca el proyecto asignando al auditor el dominio objetivo.
{
  "type": "message",
  "recipient": "seo-auditor-1",
  "content": "Dominio a auditar: tiendamascotas.es.
Alcance: rastreo de 500 URLs, CWV,
keyword gaps para 'comida húmeda gato'.
Entrega estimada: 48 h.",
  "summary": "Kick-off auditoría SEO Pack"
}
message Fase 3 · Handoff auditor → writers
Auditoría completada. El Lead notifica a cada writer con su lote de palabras clave.
{
  "type": "message",
  "recipient": "content-writer-1",
  "content": "Auditoría lista en /output/seo-audit.md.
Tu lote: artículos 1-5.
Keywords principales adjuntas.
Brief de marca: tono cercano, H2s con KW.",
  "summary": "Handoff: lote A listo para redacción"
}
broadcast Fase 4 · Cambio crítico de brief
El cliente cambia el público objetivo a mitad del proyecto. Afecta a TODOS los agentes. Usar broadcast solo aquí, no para updates rutinarios.
{
  "type": "broadcast",
  "content": "CRÍTICO: El cliente ha cambiado el
target. Ahora son dueños de perros,
NO gatos. Ajustar todas las keywords
y ángulo de marca antes de continuar.",
  "summary": "Brief actualizado: target = perros"
}
plan_approval_response Fase 2 · Aprobación plan auditor
El auditor salió de plan_mode. El Lead rechaza con feedback para añadir análisis de backlinks.
{
  "type": "plan_approval_response",
  "request_id": "plan-seo-2026-001",
  "recipient": "seo-auditor-1",
  "approve": false,
  "content": "Añadir análisis de backlinks (Ahrefs
export adjunto) y sección de competitor
gap. Vuelve a plan_mode y actualiza."
}

Flujo de cierre graceful — Fase 5

Secuencia de terminación del equipo Todos los artefactos entregados · QA aprobado
1
Lead envía shutdown_request a writers
Primero los workers más periféricos: content-writer-1 y content-writer-2
{
  "type": "shutdown_request",
  "recipient": "content-writer-1",
  "content": "Artículos 1-5 entregados y aprobados. Cierre del equipo."
}
2
Writer responde shutdown_response (approve)
El writer 2 aún tiene una tarea pendiente → rechaza temporalmente.
// content-writer-1: aprueba
{ "type": "shutdown_response", "approve": true }

// content-writer-2: rechaza aún
{ "type": "shutdown_response", "approve": false,
  "content": "Aún revisando artículo 10, 5 min más." }
3
Lead espera y reintenta con writer-2
Nunca forzar. Esperar a que finalice y volver a enviar shutdown_request.
4
Shutdown a seo-auditor-1 y qa-reviewer-1
Ambos aprueban. Lead confirma que todos los agentes han terminado.
5
TeamDelete — liberar recursos del equipo
Lead llama a TeamDelete para eliminar la configuración del equipo y liberar recursos de API.

Antipatrones — errores comunes y cómo evitarlos

Antipatrón Problema en este proyecto Enfoque correcto
❌ Broadcast para updates rutinarios
 Enviar el progreso de cada artículo a todos los agentes genera 4× el coste de API innecesariamente.
✓ message directo al QA cuando un lote está listo
❌ JSON en campo content
 El auditor envía el informe como JSON dentro de "content". No es para datos estructurados.
✓ Usar TaskUpdate para subir estado; compartir archivo en /output/
❌ No comunicar al integrar
 Los writers empiezan sin esperar el handoff y usan un brief desactualizado.
✓ message explícito cuando la auditoría está lista (Fase 3)
❌ Microgestionar vía mensajes
 El Lead pide actualizaciones cada 10 minutos, bloqueando la ejecución.
✓ Check-in solo al completar hito (lote A entregado)
❌ Usar agentId como recipient
 Usar "uuid-abc-123" en lugar de "seo-auditor-1" → error o mensaje perdido.
✓ Siempre usar el nombre definido en config.json
❌ Forzar cierre con trabajo activo
 Terminar content-writer-2 antes de que guarde el artículo 10 → pérdida de trabajo.
✓ Respetar reject; esperar y reintentar shutdown

Troubleshooting — escenarios de este proyecto

⚠ seo-auditor-1 no responde mensajes
Verificar estado de su tarea. Si está idle, completó el crawl y espera nueva asignación o cierre. Si está active, está procesando → esperar.
⚠ content-writer-2 dice que no ve SendMessage
Revisar el frontmatter tools: del agente. Debe incluir SendMessage, TaskUpdate y TaskGet explícitamente.
⚠ plan_approval_request sin request_id
El auditor llamó a ExitPlanMode sin contexto correcto. Hacer que vuelva a plan_mode, complete la exploración y llame ExitPlanMode de nuevo.
⚠ Writer-1 y QA en deadlock esperándose
El Lead envía un stub parcial al writer-1 vía message directo para que pueda continuar sin esperar la revisión completa del QA.

Descubrimiento del equipo — config.json

Ruta: ~/.claude/teams/pack-seo-acelerado/config.json
{
  "members": [
    { "name": "seo-auditor-1",    "agentId": "agt-001", "agentType": "team-specialist" },
    { "name": "content-writer-1", "agentId": "agt-002", "agentType": "team-implementer" },
    { "name": "content-writer-2", "agentId": "agt-003", "agentType": "team-implementer" },
    { "name": "qa-reviewer-1",   "agentId": "agt-004", "agentType": "team-reviewer" }
  ]
}

// SIEMPRE usar "name" al hacer messaging. Nunca agentId.
Skill: protocolos-comunicacion-equipos-agentes · CULTIVA IA · Agentes-IA · v1.0.0
MIT · Uso comercial · Generado 2026-06-15