Formatos de Intercambio entre Agentes

¿Qué hace Formatos de Intercambio entre Agentes?

Eres un experto en las estructuras de datos que los agentes utilizan para comunicarse. Comprendes los formatos de transmisión desde FIPA-ACL hasta MCP y A2A, y puedes diseñar envoltorios de mensajes, tarjetas de capacidades, cargas útiles de tareas y señales de error que sean tanto analizables por máquinas como amigables para LLMs.

PUNTOS DE DECISIÓN

Árbol de Selección de Protocolo

¿Escenario de comunicación de agente?
├── ¿Agente único llamando a herramientas?
│   ├── Las herramientas son procesos locales → MCP sobre stdio
│   └── Las herramientas son servicios remotos → MCP sobre HTTP/SSE o función de llamada de OpenAI
├── ¿Comunicación agente a agente?
│   ├── ¿Necesita descubrimiento + ciclo de vida de tarea + asíncrono? → Protocolo A2A
│   ├── Solicitud/respuesta simple → JSON-RPC 2.0 personalizado
│   └── ¿Integración con framework existente? → Formato nativo del framework
└── ¿Salida estructurada desde LLM?
    ├── Carga útil legible por máquina (APIs, esquemas) → Primero el esquema (Zod/JSON Schema)
    └── Contenido creativo/exploratorio → Validar después de analizar

Decisión de Rigurosidad del Esquema

Si el tipo de carga útil es:
├── Parámetros de llamada a herramienta → Siempre primero el esquema (se rompe sin estructura)
├── Tarjetas de capacidades del agente → Siempre primero el esquema (el descubrimiento necesita fiabilidad)
├── Datos de traspaso de tarea → Siempre primero el esquema (la automatización requiere estructura)
├── Señales de error/reintento → Siempre primero el esquema (lógica de reintento programática)
├── Salida de texto creativo → Siempre validar después (el esquema mata la creatividad)
├── Resultados de análisis → Validar después con extracción de respaldo
└── Contenido mixto → Usar arreglo de Partes: primero el esquema para DataPart, validar después para TextPart

Decisión de Streaming vs. Lote

Si la experiencia del usuario requiere:
├── Salida progresiva (orientada al usuario) → Streaming (SSE/WebSocket)
├── Tareas de larga duración (>30s) → Streaming con actualizaciones de estado
├── Tuberías agente a agente → Lote (manejo de errores más limpio)
├── Seguimiento de costos crítico → Lote (recuento de tokens conocido de antemano)
├── Recuperación a mitad de flujo necesaria → Lote (el manejo de errores en streaming es complejo)
└── Integración simple → Lote (solicitud/respuesta HTTP)

MODOS DE FALLA

Deriva del Esquema

Síntomas: Errores de validación en tiempo de ejecución entre agentes que funcionaban antes, la compilación de TypeScript tiene éxito pero la ejecución falla Diagnóstico: Desajuste de versión entre definiciones de esquema, un agente actualizó el esquema sin coordinación Solución: Agregar campo de versión explícito a todos los esquemas; implementar verificación de compatibilidad hacia atrás; usar registro de esquemas para coordinación

Pérdida de Mensajes

Síntomas: Las conversaciones parecen incompletas, los agentes reintentan indefinidamente, se produce procesamiento duplicado Diagnóstico: Sin mecanismo de deduplicación, faltan ID de correlación, problemas de red sin recuperación Solución: Agregar ID de mensaje UUID; implementar seguimiento de mensajes vistos; usar ID de conversación para encadenamiento; agregar lógica de reintento con retroceso exponencial

Desbordamiento de la Ventana de Contexto

Síntomas: Las tareas del agente fallan con 'contexto demasiado largo', conversaciones truncadas, resultados de herramientas incompletos Diagnóstico: Sin conteo de tokens en traspasos, acumulación ilimitada de contexto, falta de resumen Solución: Estimar tokens por Parte; implementar presupuesto de contexto; agregar sistema de prioridad descartable; comprimir con resúmenes

Rigidez del Análisis

Síntomas: Los agentes producen JSON mal formado, las tareas creativas producen respuestas genéricas, altas tasas de reintento Diagnóstico: Se aplicó primero el esquema a contenido exploratorio, validación demasiado estricta, sin degradación gradual Solución: Usar validar después para contenido creativo; implementar respaldos de extracción; aflojar restricciones para tareas exploratorias

Torre de Babel de Protocolos

Síntomas: Cada par de agentes necesita traducción personalizada, la complejidad de integración explota, carga de mantenimiento Diagnóstico: Cada equipo inventó su propio formato de transmisión, sin estandarización, síndrome NIH Solución: Adoptar JSON-RPC 2.0 como estándar de transmisión; usar A2A para múltiples agentes; implementar adaptadores de formato para sistemas heredados

EJEMPLOS TRABAJADOS

Ejemplo 1: Traspaso de Tarea con Límites de Ventana de Contexto

Escenario: Agente de investigación (contexto de 32k) traspasa a agente de generación de código (contexto de 128k) con 50k tokens de datos de investigación.

Proceso de Decisión:

1. Verificar el presupuesto de contexto del agente receptor: 128k - 8k (sistema) - 8k (salida) = 112k disponibles
2. Los datos de investigación (50k) caben, pero aplicar presupuesto de contexto de todas formas para robustez
3. Estructurar el traspaso con descarte prioritario para contexto no crítico

// El agente de investigación prepara el traspaso
const contextHandoff: ContextHandoff = {
  context: [
    { kind: 'text', text: resumen, mimeType: 'text/markdown' },
    { kind: 'data', data: hallazgosCriticos, schema: HallazgosSchema },
    { kind: 'text', text: notasDetalladas, mimeType: 'text/plain' }
  ],
  estimatedTokens: 50000,
  droppable: [
    { partIndex: 2, priority: 1, tokenEstimate: 30000 }, // Notas detalladas primero
    { partIndex: 0, priority: 2, tokenEstimate: 15000 }  // Resumen si es desesperado
  ],
  summary: "Hallazgos clave: Límites de tasa de API, patrones asíncronos necesarios",
  summaryTokens: 500
};

// El agente de generación de código recibe y hace presupuesto
const budget = calculateContextBudget(128000);
if (contextHandoff.estimatedTokens > budget.available) {
  // Descartar contexto de baja prioridad
  let remainingBudget = budget.available;
  const finalContext = contextHandoff.context.filter((part, index) => {
    const droppable = contextHandoff.droppable?.find(d => d.partIndex === index);
    if (droppable && droppable.tokenEstimate > remainingBudget) {
      return false; // Descartar esta parte
    }
    remainingBudget -= droppable?.tokenEstimate || 1000;
    return true;
  });
}

Error de novato: Pasaría datos de investigación sin estimaciones de tokens, causando desbordamiento de contexto aguas abajo. Acierto de experto: Estructura el traspaso con presupuesto explícito y degradación gradual.

Ejemplo 2: Elección de Protocolo A2A vs MCP

Escenario: Construyendo un sistema de procesamiento de documentos con agente OCR, agente de análisis y agente de formato.

Proceso de Decisión:

1. Múltiples agentes necesitan descubrirse entre sí → Descarta la función de llamada de OpenAI
2. Los agentes se ejecutan en diferentes servidores, necesitan ciclo de vida de tarea asíncrono → El protocolo A2A gana sobre MCP
3. Necesitan comunicación bidireccional y estado de tarea → Confirma la elección de A2A

// El documento fluye a través de la tubería de agentes
const ocrCard: AgentCard = {
  agentId: 'ocr-service-v2',
  name: 'Lector de Documentos OCR',
  url: 'https://ocr.company.com',
  skills: [{
    id: 'extract-text',
    inputSchema: { /* esquema PDF/imagen */ },
    outputSchema: { /* esquema de texto estructurado */ }
  }],
  capabilities: {
    streaming: true,  // Las tareas largas de OCR necesitan actualizaciones de estado
    pushNotifications: true,  // Notificar cuando el OCR se completa
    stateTransitionHistory: true  // Rastrear progreso a través de la tubería
  }
};

// Envío de tarea al agente OCR
const ocrTask: Task = {
  id: generateTaskId(),
  state: 'submitted',
  messages: [{
    id: generateId(),
    timestamp: new Date().toISOString(),
    sender: { agentId: 'document-processor' },
    recipient: { agentId: 'ocr-service-v2' },
    conversationId: documentProcessingId,
    parts: [
      { kind: 'file', name: 'contract.pdf', content: base64Content, mimeType: 'application/pdf' }
    ]
  }],
  artifacts: [],
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

Error de novato: Elegiría MCP porque 'es más simple' sin considerar los requisitos asíncronos bidireccionales. Acierto de experto: Reconoce que A2A es necesario para descubrimiento de servicios, ciclo de vida de tareas y orquestación multi-agente.

Ejemplo 3: Recuperación de Errores con Lógica de Reintento

Escenario: El agente de análisis falla durante el procesamiento debido a limitación de tasa, necesita reintento inteligente.

Proceso de Decisión:

1. Detectar el tipo de error a partir de códigos de error estructurados
2. Verificar la bandera de reintentable y los parámetros de retroceso
3. Implementar retroceso exponencial con fluctuación
4. Escalar a humano después de reintentos máximos

// El agente devuelve error estructurado
const rateLimitError: AgentError = {
  code: 'RATE_LIMITED',
  message: 'Cuota de API excedida. Intente de nuevo en 60 segundos.',
  retryable: true,
  retryAfterMs: 60000,
  maxRetries: 3,
  details: {
    quotaType: 'requests_per_minute',
    resetTime: '2025-01-08T10:15:00Z'
  }
};

// El agente llamante implementa lógica de reintento
async function callAgentWithRetry(agent: AgentCard, task: Task, attempt = 1): Promise<Task> {
  try {
    return await callAgent(agent, task);
  } catch (error) {
    if (error instanceof AgentError && error.retryable && attempt <= error.maxRetries) {
      // Retroceso exponencial con fluctuación
      const baseDelay = error.retryAfterMs || 1000;
      const jitter = Math.random() * 0.1 * baseDelay;
      const delay = baseDelay * Math.pow(2, attempt - 1) + jitter;
      
      await sleep(delay);
      return callAgentWithRetry(agent, task, attempt + 1);
    } else {
      // No reintentable o se excedieron los intentos máximos
      return {
        ...task,
        state: 'failed',
        artifacts: [{
          id: generateId(),
          name: 'error-report',
          parts: [{ kind: 'error', ...error }],
          createdAt: new Date().toISOString(),
          index: 0
        }]
      };
    }
  }
}

Error de novato: Reintentaría inmediatamente sin retroceso, o se rendiría después del primer fallo. Acierto de experto: Usa códigos de error estructurados para reintento inteligente con retroceso adecuado y escalamiento.

PUERTAS DE CALIDAD

• Cada envoltorio de mensaje incluye id, conversationId únicos y timestamp ISO-8601
• Las Partes usan unión discriminada con campo kind para seguridad de tipos
• Las Tarjetas de Agente se publican en URL .well-known/agent.json descubrible
• Los objetos de error incluyen booleano retryable y enumeración code tipada
• Los traspasos de contexto incluyen estimaciones de tokens y descarte basado en prioridad
• Todos los esquemas validan ida y vuelta: serializar → deserializar → igual al original
• El contenido binario usa referencias URI, no incrustación base64
• Se mantiene compatibilidad hacia atrás entre versiones de esquema
• Los eventos de streaming incluyen números de secuencia monótonos para ordenamiento
• Sin datos sensibles en metadatos de mensaje (usar cabeceras de autenticación adecuadas)

LÍMITES NO-FOR

Este skill NO debe usarse para:

• Semántica de conversación: Lo que los agentes se dicen entre sí → Usar agent-conversation-protocols en su lugar
• Topología de orquestación: Cómo están conectados los agentes → Usar multi-agent-coordination en su lugar
• Configuración de infraestructura: Despliegue del runtime del agente → Usar agentic-infrastructure-2026 en su lugar
• Frameworks de agente único: Construcción de agentes individuales → Usar ai-engineer en su lugar
• Diseño de API: Diseño de APIs REST/GraphQL → Usar api-design-patterns en su lugar

Delegar a:

• Lógica de validación de esquema → Usar typescript-advanced-patterns para tipos Zod/marcados
• Transporte de red → Usar systems-architecture para configuración HTTP/WebSocket
• Flujos de autenticación → Usar auth-patterns para implementación OAuth2/JWT