curiositech/windags-skills

Formatos de Intercâmbio entre Agentes

Você é um especialista nas estruturas de dados que os agentes usam para se comunicar. Você entende formatos de transmissão desde FIPA-ACL até MCP e A2A, e pode projetar envelopes de mensagens, cartões de capacidade, payloads de tarefas e sinais de erro que são tanto analisáveis por máquina quanto amigáveis para LLMs.

PONTOS DE DECISÃO

Árvore de Seleção de Protocolo

Cenário de comunicação do agente?
├── Agente único chamando ferramentas?
│   ├── Ferramentas são processos locais → MCP sobre stdio
│   └── Ferramentas são serviços remotos → MCP sobre HTTP/SSE ou OpenAI function calling
├── Comunicação agente-para-agente?
│   ├── Precisa de descoberta + ciclo de vida de tarefa + assíncrono → Protocolo A2A
│   ├── Simples requisição/resposta → JSON-RPC 2.0 customizado
│   └── Integração com framework existente → Formato nativo do framework
└── Saída estruturada do LLM?
    ├── Payload legível por máquina (APIs, esquemas) → Schema-first (Zod/JSON Schema)
    └── Conteúdo criativo/exploratório → Validação após análise (validate-after)

Decisão de Rigidez de Esquema

Se o tipo de payload for:
├── Parâmetros de chamada de ferramenta → Sempre schema-first (quebra sem estrutura)
├── Cartões de capacidade do agente → Sempre schema-first (descoberta precisa de confiabilidade)
├── Dados de transferência de tarefa → Sempre schema-first (automação requer estrutura)
├── Sinais de erro/repetição → Sempre schema-first (lógica de repetição programática)
├── Saída de texto criativo → Sempre validate-after (esquema mata a criatividade)
├── Resultados de análise → Validate-after com extração alternativa
└── Conteúdo misto → Usar array de Partes: schema-first para DataPart, validate-after para TextPart

Decisão de Streaming vs Lote

Se a experiência do usuário exigir:
├── Saída progressiva (voltada para o usuário) → Streaming (SSE/WebSocket)
├── Tarefas de longa duração (>30s) → Streaming com atualizações de status
├── Pipelines agente-para-agente → Lote (tratamento de erro mais limpo)
├── Rastreamento de custos crítico → Lote (contagem de tokens conhecida antecipadamente)
├── Recuperação no meio do fluxo necessária → Lote (tratamento de erro em streaming é complexo)
└── Integração simples → Lote (requisição/resposta HTTP)

MODOS DE FALHA

Deriva de Esquema (Schema Drift)

Sintomas: Erros de validação em tempo de execução entre agentes que funcionavam antes, compilação TypeScript bem-sucedida mas falha em tempo de execução Diagnóstico: Incompatibilidade de versão entre definições de esquema, um agente atualizou o esquema sem coordenar Correção: Adicionar campo de versão explícito a todos os esquemas; implementar verificação de compatibilidade retroativa; usar registro de esquemas para coordenação

Perda de Mensagem

Sintomas: Conversas parecem incompletas, agentes repetem indefinidamente, ocorre processamento duplicado Diagnóstico: Nenhum mecanismo de desduplicação, IDs de correlação ausentes, problemas de rede sem recuperação Correção: Adicionar IDs de mensagem UUID; implementar rastreamento de mensagens já vistas; usar conversationId para encadeamento; adicionar lógica de repetição com backoff exponencial

Estouro da Janela de Contexto

Sintomas: Tarefas do agente falham com "contexto muito longo", conversas truncadas, resultados de ferramentas incompletos Diagnóstico: Nenhuma contagem de tokens nas transferências, acumulação ilimitada de contexto, sumarização ausente Correção: Estimar tokens por Parte; implementar orçamento de contexto; adicionar sistema de prioridade descartável; comprimir com resumos

Rigidez de Análise (Parsing Rigidity)

Sintomas: Agente produz JSON malformado, tarefas criativas produzem respostas genéricas, altas taxas de repetição Diagnóstico: Schema-first aplicado a conteúdo exploratório, validação excessivamente rigorosa, nenhuma degradação gradual Correção: Usar validate-after para conteúdo criativo; implementar alternativas de extração; afrouxar restrições para tarefas exploratórias

Torre de Babel de Protocolo

Sintomas: Cada par de agentes precisa de tradução personalizada, complexidade de integração explode, sobrecarga de manutenção Diagnóstico: Cada equipe inventou seu próprio formato de transmissão, nenhuma padronização, síndrome do "Não Inventado Aqui" Correção: Adotar JSON-RPC 2.0 como padrão de transmissão; usar A2A para multi-agente; implementar adaptadores de formato para sistemas legados

EXEMPLOS PRÁTICOS

Exemplo 1: Transferência de Tarefa com Limites de Janela de Contexto

Cenário: Agente de pesquisa (contexto de 32k) transfere para agente de geração de código (contexto de 128k) com 50k tokens de dados de pesquisa.

Processo de Decisão:

1. Verificar orçamento de contexto do agente receptor: 128k - 8k (sistema) - 8k (saída) = 112k disponíveis
2. Dados de pesquisa (50k) cabem, mas aplicar orçamento de contexto mesmo assim para robustez
3. Estruturar transferência com descarte por prioridade para contexto não crítico

// Agente de pesquisa prepara a transferência
const contextoTransferencia: ContextHandoff = {
  context: [
    { kind: 'text', text: resumo, mimeType: 'text/markdown' },
    { kind: 'data', data: descobertasCriticas, schema: FindingsSchema },
    { kind: 'text', text: notasDetalhadas, mimeType: 'text/plain' }
  ],
  estimatedTokens: 50000,
  droppable: [
    { partIndex: 2, priority: 1, tokenEstimate: 30000 }, // Notas detalhadas primeiro
    { partIndex: 0, priority: 2, tokenEstimate: 15000 }  // Resumo se necessário
  ],
  summary: "Principais descobertas: limites de taxa de API, padrões assíncronos necessários",
  summaryTokens: 500
};

// Agente de geração de código recebe e faz o orçamento
const orcamento = calculateContextBudget(128000);
if (contextoTransferencia.estimatedTokens > orcamento.available) {
  // Descartar contexto de baixa prioridade
  let orcamentoRestante = orcamento.available;
  const contextoFinal = contextoTransferencia.context.filter((part, index) => {
    const descartavel = contextoTransferencia.droppable?.find(d => d.partIndex === index);
    if (descartavel && descartavel.tokenEstimate > orcamentoRestante) {
      return false; // Descartar esta parte
    }
    orcamentoRestante -= descartavel?.tokenEstimate || 1000;
    return true;
  });
}

Erro de novato: Passaria dados de pesquisa brutos sem estimativas de token, causando estouro de contexto a jusante. Percepção de especialista: Estrutura a transferência com orçamento explícito e degradação gradual.

Exemplo 2: Escolha de Protocolo A2A vs MCP

Cenário: Construindo um sistema de processamento de documentos com agente OCR, agente de análise e agente de formatação.

Processo de Decisão:

1. Múltiplos agentes precisam descobrir uns aos outros → Descarta OpenAI function calling
2. Agentes executam em servidores diferentes, precisam de ciclo de vida de tarefa assíncrono → Protocolo A2A vence sobre MCP
3. Precisam de comunicação bidirecional e status de tarefa → Confirma escolha do A2A

// Documento flui através do pipeline de agentes
const cartaoOCR: AgentCard = {
  agentId: 'ocr-service-v2',
  name: 'Leitor de Documentos OCR', 
  url: 'https://ocr.company.com',
  skills: [{
    id: 'extrair-texto',
    inputSchema: { /* esquema PDF/imagem */ },
    outputSchema: { /* esquema de texto estruturado */ }
  }],
  capabilities: {
    streaming: true,  // Tarefas longas de OCR precisam de atualizações de status
    pushNotifications: true,  // Notificar quando OCR for concluído
    stateTransitionHistory: true  // Rastrear progresso pelo pipeline
  }
};

// Submissão de tarefa para o agente OCR
const tarefaOCR: Task = {
  id: generateTaskId(),
  state: 'submitted',
  messages: [{
    id: generateId(),
    timestamp: new Date().toISOString(),
    sender: { agentId: 'document-processor' },
    recipient: { agentId: 'ocr-service-v2' },
    conversationId: processamentoDocumentoId,
    parts: [
      { kind: 'file', name: 'contrato.pdf', content: conteudoBase64, mimeType: 'application/pdf' }
    ]
  }],
  artifacts: [],
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

Erro de novato: Escolheria MCP porque "é mais simples" sem considerar os requisitos assíncronos bidirecionais. Percepção de especialista: Reconhece que o A2A é necessário para descoberta de serviços, ciclo de vida de tarefas e orquestração multi-agente.

Exemplo 3: Recuperação de Erro com Lógica de Repetição

Cenário: Agente de análise falha durante o processamento devido a limitação de taxa, precisa de repetição inteligente.

Processo de Decisão:

1. Detectar tipo de erro a partir de códigos de erro estruturados
2. Verificar sinalização de repetível e parâmetros de backoff
3. Implementar backoff exponencial com jitter
4. Escalar para humano após repetições máximas

// Agente retorna erro estruturado
const erroLimitacaoTaxa: AgentError = {
  code: 'RATE_LIMITED',
  message: 'Cota da API excedida. Tente novamente em 60 segundos.',
  retryable: true,
  retryAfterMs: 60000,
  maxRetries: 3,
  details: {
    quotaType: 'requests_per_minute',
    resetTime: '2025-01-08T10:15:00Z'
  }
};

// Agente chamador implementa lógica de repetição
async function chamarAgenteComRepeticao(agent: AgentCard, task: Task, tentativa = 1): Promise<Task> {
  try {
    return await chamarAgente(agent, task);
  } catch (error) {
    if (error instanceof AgentError && error.retryable && tentativa <= error.maxRetries) {
      // Backoff exponencial com jitter
      const atrasoBase = error.retryAfterMs || 1000;
      const jitter = Math.random() * 0.1 * atrasoBase;
      const atraso = atrasoBase * Math.pow(2, tentativa - 1) + jitter;
      
      await sleep(atraso);
      return chamarAgenteComRepeticao(agent, task, tentativa + 1);
    } else {
      // Não repetível ou tentativas máximas excedidas
      return {
        ...task,
        state: 'failed',
        artifacts: [{
          id: generateId(),
          name: 'relatorio-erro',
          parts: [{ kind: 'error', ...error }],
          createdAt: new Date().toISOString(),
          index: 0
        }]
      };
    }
  }
}

Erro de novato: Repetiria imediatamente sem backoff, ou desistiria após a primeira falha. Percepção de especialista: Usa códigos de erro estruturados para repetição inteligente com backoff adequado e escalonamento.

GATES DE QUALIDADE

• Todo envelope de mensagem inclui id, conversationId e timestamp ISO-8601 únicos
• Partes usam união discriminada com campo kind para segurança de tipo
• Cartões de Agente são publicados em URL .well-known/agent.json detectável
• Objetos de erro incluem booleano retryable e enum code tipado
• Transferências de contexto incluem estimativas de token e descarte baseado em prioridade
• Todos os esquemas validam ida e volta: serializar → desserializar → igual ao original
• Conteúdo binário usa referências URI, não incorporação base64
• Compatibilidade retroativa mantida entre versões de esquema
• Eventos de streaming incluem números de sequência monotônicos para ordenação
• Nenhum dado sensível em metadados de mensagem (usar cabeçalhos de autenticação adequados)

LIMITES DE NÃO APLICAÇÃO

Esta skill NÃO deve ser usada para:

• Semântica de conversa: O que os agentes dizem uns aos outros → Use protocolos-conversa-agente
• Topologia de orquestração: Como os agentes estão conectados → Use coordenacao-multi-agente
• Configuração de infraestrutura: Implantação de runtime de agente → Use infraestrutura-agente-2026
• Frameworks de agente único: Construção de agentes individuais → Use engenheiro-ia
• Design de API: Projetar APIs REST/GraphQL → Use padroes-design-api

Delegar para:

• Lógica de validação de esquema → Use padroes-avancados-typescript para tipos Zod/marcados
• Transporte de rede → Use arquitetura-sistemas para configuração HTTP/WebSocket
• Fluxos de autenticação → Use padroes-auth para implementação OAuth2/JWT