> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A Agent

> Integre agentes externos que implementam o protocolo Agent-to-Agent como agentes nativos na plataforma

## Visão Geral

O **A2A Agent** permite integrar agentes externos que implementam o protocolo Agent-to-Agent (A2A) como agentes nativos dentro da plataforma Evo AI. Utilizando o base agent do ADK, esses agentes externos podem ser usados em qualquer parte do sistema como se fossem agentes locais.

Esta funcionalidade é fundamental para criar ecossistemas híbridos, onde agentes desenvolvidos externamente ou hospedados em outros sistemas podem participar seamlessly de workflows complexos junto com agentes nativos da plataforma.

<Note>
  **Baseado no Protocolo A2A**: Implementação seguindo o [protocolo Agent-to-Agent](https://google.github.io/A2A/specification/) desenvolvido pelo Google para interoperabilidade entre agentes.
</Note>

## Características Principais

<CardGroup cols={2}>
  <Card title="Integração Transparente" icon="plug">
    Agentes externos funcionam como nativos em workflows e sub-agentes
  </Card>

  <Card title="Protocolo Padrão" icon="network-wired">
    Usa protocolo A2A para comunicação padronizada e interoperável
  </Card>

  <Card title="Base Agent ADK" icon="cube">
    Implementado sobre o base agent do ADK para máxima compatibilidade
  </Card>

  <Card title="Flexibilidade Total" icon="arrow-right-arrow-left">
    Agentes podem estar em qualquer infraestrutura ou tecnologia
  </Card>
</CardGroup>

## Quando Usar A2A Agent

<AccordionGroup>
  <Accordion icon="check" title="Cenários Ideais">
    **✅ Use A2A Agent quando:**

    * **Agentes externos**: Integrar agentes desenvolvidos fora da plataforma
    * **Sistemas legados**: Conectar sistemas existentes via protocolo A2A
    * **Especialização externa**: Usar agentes especializados de terceiros
    * **Infraestrutura distribuída**: Agentes em diferentes clouds ou datacenters
    * **Tecnologias específicas**: Agentes em Python, Node.js, ou outras linguagens

    **Exemplos práticos:**

    * Agente de análise de dados em Python hospedado externamente
    * Sistema de recomendação legado exposto via A2A
    * Agente especializado em processamento de imagens
    * Serviço de tradução de terceiros
    * Agente de validação de documentos em infraestrutura específica
  </Accordion>

  <Accordion icon="x" title="Quando NÃO usar">
    **❌ Evite A2A Agent quando:**

    * **Agentes simples**: Funcionalidade pode ser implementada nativamente
    * **Latência crítica**: Comunicação de rede adiciona overhead
    * **Dados sensíveis**: Requer processamento local por segurança
    * **Controle total**: Precisa de controle completo sobre execução
    * **Desenvolvimento inicial**: Melhor começar com agentes nativos
  </Accordion>
</AccordionGroup>

## Criando um A2A Agent

### Passo a Passo na Plataforma

<AccordionGroup>
  <Accordion icon="robot" title="1. Iniciar criação">
    1. Na tela principal do Evo AI, clique em **"New Agent"**
    2. No campo **"Type"**, selecione **"A2A Agent"**
    3. Você verá campos específicos para configuração A2A

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_creation.png" alt="Criando A2A Agent" />
  </Accordion>

  <Accordion icon="gear" title="2. Configurar informações básicas">
    **Name:** Nome do agente A2A na plataforma

    ```
    Exemplo: analisador_dados_python
    ```

    **Description:** Resumo das capacidades do agente externo

    ```
    Exemplo: Agente especializado em análise de dados complexos 
    usando bibliotecas Python avançadas, hospedado externamente
    ```

    **Goal:** Objetivo e responsabilidades do agente

    ```
    Exemplo: Realizar análises estatísticas avançadas e machine learning 
    em datasets grandes, fornecendo insights e visualizações
    ```
  </Accordion>

  <Accordion icon="network-wired" title="3. Configurar conexão A2A">
    **Endpoint URL:** URL do agente externo que implementa A2A

    ```
    Exemplo: https://data-analyzer.mycompany.com/api/v1/a2a
    ```

    **Agent ID:** Identificador do agente no sistema externo

    ```
    Exemplo: data-analyzer-v2
    ```

    **Authentication:** Método de autenticação

    ```
    Opções:
    - API Key (x-api-key header)
    - Bearer Token (Authorization header)
    - Basic Auth (username/password)
    - Custom Headers
    ```

    **API Key/Token:** Credenciais para autenticação

    ```
    Exemplo: sk-1234567890abcdef...
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_connection.png" alt="Configurando Conexão A2A" />
  </Accordion>

  <Accordion icon="file" title="4. Definir interface do agente">
    **Instructions:** Como usar o agente A2A no contexto da plataforma

    ```markdown theme={null}
    # Analisador de Dados Python Externo

    Este agente realiza análises avançadas de dados usando Python.

    ## Capacidades:
    - Análise estatística descritiva e inferencial
    - Machine learning (classificação, regressão, clustering)
    - Visualizações interativas e relatórios
    - Processamento de datasets grandes (>1GB)

    ## Como usar:
    Envie dados em formato JSON ou CSV junto com instruções específicas:
    - Tipo de análise desejada
    - Parâmetros específicos
    - Formato de saída preferido

    ## Exemplo de input:
    {
      "data": "base64_encoded_csv_data",
      "analysis_type": "regression",
      "target_column": "sales",
      "features": ["price", "marketing_spend", "season"]
    }

    ## Limitações:
    - Timeout máximo: 10 minutos
    - Tamanho máximo de dados: 100MB
    - Formatos suportados: CSV, JSON, Parquet
    ```
  </Accordion>

  <Accordion icon="gear" title="5. Configurações avançadas">
    **Timeout:** Tempo limite para chamadas ao agente externo

    ```
    Recomendado: 300-600 segundos (dependendo da complexidade)
    ```

    **Retry Policy:** Política de tentativas em caso de falha

    ```
    Opções:
    - No Retry (para operações críticas)
    - Retry Once (padrão)
    - Retry with Backoff (para falhas temporárias)
    ```

    **Health Check:** Verificação de saúde do agente externo

    ```
    - Health Check URL: /health
    - Check Interval: 60 segundos
    - Failure Threshold: 3 falhas consecutivas
    ```

    **Circuit Breaker:** Proteção contra falhas em cascata

    ```
    - Failure Rate Threshold: 50%
    - Recovery Time: 30 segundos
    - Half-Open Requests: 3
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_advanced.png" alt="Configurações Avançadas A2A" />
  </Accordion>
</AccordionGroup>

## Exemplos Práticos

### 1. Agente de Análise de Dados Python

<AccordionGroup>
  <Accordion icon="chart-bar" title="Configuração do Agente">
    **Cenário:** Integrar sistema de análise de dados Python externo

    **Configuração na plataforma:**

    **Basic Information:**

    * **Name:** `python_data_analyzer`
    * **Description:** `Agente Python para análise avançada de dados e ML`
    * **Goal:** `Fornecer insights através de análise estatística e machine learning`

    **A2A Connection:**

    * **Endpoint:** `https://analytics.company.com/api/v1/a2a/data-analyzer`
    * **Agent ID:** `data-analyzer-prod`
    * **Auth Method:** `API Key`
    * **API Key:** `da_prod_key_abc123...`

    **Advanced Settings:**

    * **Timeout:** `600 segundos` (análises podem ser demoradas)
    * **Retry Policy:** `Retry with Backoff`
    * **Health Check:** `Enabled` (`/health` endpoint)

    **Usage Instructions:**

    ```markdown theme={null}
    # Analisador de Dados Python

    Envie dados e especificações de análise:

    ## Input Format:
    {
      "dataset": "base64_csv_data",
      "analysis": {
        "type": "regression|classification|clustering|descriptive",
        "target": "column_name",
        "features": ["col1", "col2", "col3"],
        "parameters": {...}
      }
    }

    ## Output Format:
    {
      "results": {...},
      "visualizations": ["base64_plot1", "base64_plot2"],
      "insights": ["insight1", "insight2"],
      "model_metrics": {...}
    }
    ```
  </Accordion>
</AccordionGroup>

### 2. Sistema de Recomendação Legado

<AccordionGroup>
  <Accordion icon="star" title="Configuração do Agente">
    **Cenário:** Integrar sistema de recomendação existente via A2A

    **Configuração na plataforma:**

    **Basic Information:**

    * **Name:** `legacy_recommender`
    * **Description:** `Sistema de recomendação legado integrado via A2A`
    * **Goal:** `Fornecer recomendações personalizadas baseadas em histórico`

    **A2A Connection:**

    * **Endpoint:** `https://recommender.legacy-system.com/a2a`
    * **Agent ID:** `recommender-v1`
    * **Auth Method:** `Bearer Token`
    * **Token:** `Bearer eyJhbGciOiJIUzI1NiIs...`

    **Usage Instructions:**

    ```markdown theme={null}
    # Sistema de Recomendação Legado

    ## Input:
    {
      "user_id": "12345",
      "context": {
        "category": "electronics",
        "price_range": [100, 500],
        "previous_purchases": [...]
      },
      "num_recommendations": 10
    }

    ## Output:
    {
      "recommendations": [
        {
          "item_id": "item123",
          "score": 0.95,
          "reason": "Based on similar purchases"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### 3. Agente de Processamento de Imagens

<AccordionGroup>
  <Accordion icon="image" title="Configuração do Agente">
    **Cenário:** Integrar serviço especializado de processamento de imagens

    **Configuração na plataforma:**

    **Basic Information:**

    * **Name:** `image_processor`
    * **Description:** `Agente especializado em análise e processamento de imagens`
    * **Goal:** `Extrair informações, detectar objetos e processar imagens`

    **A2A Connection:**

    * **Endpoint:** `https://vision-api.imageservice.com/a2a`
    * **Agent ID:** `vision-processor`
    * **Auth Method:** `Custom Headers`
    * **Headers:** `X-API-Key: img_key_xyz789...`

    **Usage Instructions:**

    ```markdown theme={null}
    # Processador de Imagens

    ## Capabilities:
    - Object detection
    - Text extraction (OCR)
    - Image classification
    - Face recognition
    - Image enhancement

    ## Input:
    {
      "image": "base64_encoded_image",
      "operations": ["detect_objects", "extract_text"],
      "options": {
        "confidence_threshold": 0.8,
        "max_objects": 10
      }
    }

    ## Output:
    {
      "objects": [...],
      "text": "extracted text",
      "metadata": {...}
    }
    ```
  </Accordion>
</AccordionGroup>

## Integração em Workflows

### Usando A2A Agents em Sub-Agents

<AccordionGroup>
  <Accordion icon="sitemap" title="Em Sequential Agents">
    **Exemplo: Pipeline de Análise de Produto**

    ```markdown theme={null}
    Pipeline com A2A Agent:

    1. **Coletor de Dados** (Nativo)
       - Coleta informações do produto

    2. **Analisador de Imagens** (A2A Agent)
       - Processa imagens do produto
       - Extrai características visuais

    3. **Analisador de Sentimento** (Nativo)
       - Analisa reviews e comentários

    4. **Gerador de Relatório** (Nativo)
       - Combina todas as análises
    ```
  </Accordion>

  <Accordion icon="arrow-right-arrow-left" title="Em Parallel Agents">
    **Exemplo: Análise Completa de Usuário**

    ```markdown theme={null}
    Análises paralelas:

    - **Verificador de Email** (Nativo)
    - **Analisador de Crédito** (A2A Agent externo)
    - **Verificador de Documentos** (A2A Agent especializado)
    - **Checker de Antecedentes** (Nativo)

    Todos executam simultaneamente e resultados são agregados.
    ```
  </Accordion>

  <Accordion icon="recycle" title="Em Loop Agents">
    **Exemplo: Otimização de Campanha**

    ```markdown theme={null}
    Loop iterativo:

    1. **Gerador de Parâmetros** (Nativo)
    2. **Simulador de Performance** (A2A Agent Python)
    3. **Analisador de Resultados** (Nativo)
    4. **Decisor de Convergência** (Nativo)

    O A2A Agent Python usa bibliotecas especializadas para simulação.
    ```
  </Accordion>
</AccordionGroup>

## Monitoramento e Debugging

### Acompanhando Agentes A2A

<AccordionGroup>
  <Accordion icon="chart-line" title="Dashboard de Monitoramento">
    **Métricas específicas para A2A Agents:**

    * **Latência de rede**: Tempo de comunicação com agente externo
    * **Taxa de sucesso**: Percentual de chamadas bem-sucedidas
    * **Health status**: Status de saúde do agente externo
    * **Circuit breaker**: Estado do circuit breaker
    * **Retry attempts**: Número de tentativas por chamada

    **Visualização em tempo real:**

    ```
    A2A Agent: python_data_analyzer

    Status: 🟢 Healthy
    Endpoint: https://analytics.company.com/...

    Last 24h Metrics:
    ├── Success Rate: 98.5%
    ├── Avg Latency: 2.3s
    ├── Total Calls: 1,247
    ├── Failed Calls: 19
    └── Circuit Breaker: CLOSED

    Recent Activity:
    ├── 14:32 - Analysis completed (3.2s)
    ├── 14:30 - Analysis started
    ├── 14:28 - Health check OK
    └── 14:25 - Analysis completed (1.8s)
    ```
  </Accordion>

  <Accordion icon="bug" title="Debugging de Problemas">
    **Problemas comuns com A2A Agents:**

    **1. Timeout de Conexão**

    ```
    Sintoma: Chamadas frequentemente excedem tempo limite
    Causa: Agente externo lento ou rede instável
    Solução: Aumentar timeout ou otimizar agente externo
    ```

    **2. Falhas de Autenticação**

    ```
    Sintoma: Erro 401/403 nas chamadas
    Causa: Credenciais inválidas ou expiradas
    Solução: Verificar e atualizar API keys/tokens
    ```

    **3. Circuit Breaker Ativo**

    ```
    Sintoma: Chamadas rejeitadas automaticamente
    Causa: Taxa de falha alta ativou circuit breaker
    Solução: Verificar saúde do agente externo
    ```

    **4. Formato de Dados Incompatível**

    ```
    Sintoma: Agente externo retorna erro de formato
    Causa: Dados enviados não seguem protocolo A2A
    Solução: Validar formato de entrada/saída
    ```
  </Accordion>
</AccordionGroup>

## Configurações Avançadas

### Otimização de Performance

<AccordionGroup>
  <Accordion icon="rocket" title="Redução de Latência">
    **Estratégias para otimizar performance:**

    **Connection Pooling:**

    ```markdown theme={null}
    - Reutilize conexões HTTP
    - Configure keep-alive apropriado
    - Limite número de conexões simultâneas
    ```

    **Caching Inteligente:**

    ```markdown theme={null}
    - Cache resultados determinísticos
    - Use TTL baseado na natureza dos dados
    - Invalide cache quando necessário
    ```

    **Compression:**

    ```markdown theme={null}
    - Habilite compressão gzip/deflate
    - Comprima payloads grandes
    - Use formatos binários quando apropriado
    ```
  </Accordion>

  <Accordion icon="shield" title="Resiliência e Confiabilidade">
    **Configurações para máxima robustez:**

    **Circuit Breaker Settings:**

    ```markdown theme={null}
    - Failure Threshold: 50% (ajustar conforme SLA)
    - Recovery Time: 30s (tempo para tentar novamente)
    - Half-Open Requests: 3 (testes durante recuperação)
    ```

    **Retry Configuration:**

    ```markdown theme={null}
    - Max Retries: 3
    - Backoff Strategy: Exponential
    - Initial Delay: 1s
    - Max Delay: 30s
    ```

    **Health Check:**

    ```markdown theme={null}
    - Check Interval: 60s
    - Timeout: 10s
    - Failure Threshold: 3 consecutive failures
    ```
  </Accordion>

  <Accordion icon="lock" title="Segurança">
    **Configurações de segurança:**

    **Authentication:**

    ```markdown theme={null}
    - Use HTTPS sempre
    - Rotacione API keys regularmente
    - Implemente rate limiting
    ```

    **Data Protection:**

    ```markdown theme={null}
    - Criptografe dados sensíveis
    - Use TLS 1.3 ou superior
    - Valide certificados SSL
    ```

    **Access Control:**

    ```markdown theme={null}
    - Whitelist IPs quando possível
    - Use tokens com escopo limitado
    - Monitore tentativas de acesso
    ```
  </Accordion>

  <Accordion icon="database" title="Output Key - Compartilhamento de Estado">
    **Campo `Output Key` na interface:**

    O Output Key permite que o A2A Agent salve a resposta do agente externo em uma variável específica no estado compartilhado, tornando-a disponível para outros agentes ou processos subsequentes.

    **Como funciona:**

    * Configure o campo `Output Key` com um nome descritivo
    * A resposta do agente externo será salva automaticamente nessa variável
    * Outros agentes podem acessar usando placeholders `{{output_key_name}}`
    * Funciona em workflows, loops e sistemas multi-agente

    **Exemplos de configuração:**

    ```markdown theme={null}
    Output Key: "analise_externa"
    → Salva resposta em state.analise_externa

    Output Key: "dados_processados_ia"
    → Salva resposta em state.dados_processados_ia

    Output Key: "resultado_validacao"
    → Salva resposta em state.resultado_validacao
    ```

    **Uso em outros agentes:**

    ```markdown theme={null}
    # Nas instruções de agentes subsequentes:
    "Analise o pedido: {{user_input}} e baseie-se na análise externa: {{analise_externa}}"
    "Use os dados processados: {{dados_processados_ia}}"
    "Considere a validação: {{resultado_validacao}}"
    ```

    **Tratamento de dados A2A:**

    ```markdown theme={null}
    # O A2A Agent automaticamente:
    - Extrai o resultado do protocolo JSON-RPC 2.0
    - Converte para formato utilizável
    - Salva no estado com a chave especificada
    - Trata erros e timeouts apropriadamente
    ```

    **Boas práticas:**

    * Use snake\_case: `resposta_sistema_externo`, `dados_validados`
    * Seja específico: `analise_sentimento_api` em vez de `analise`
    * Documente formato esperado da resposta externa
    * Considere tratamento de erros no estado
    * Use nomes que identifiquem a origem externa
  </Accordion>
</AccordionGroup>

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="lightbulb" title="Design de Integração">
    **Princípios para integração eficaz:**

    * **Idempotência**: Operações devem ser seguras para retry
    * **Timeouts apropriados**: Balance entre performance e confiabilidade
    * **Error handling**: Trate falhas graciosamente
    * **Monitoring**: Monitore saúde e performance constantemente
    * **Documentation**: Documente interface e limitações claramente
  </Accordion>

  <Accordion icon="network-wired" title="Protocolo A2A">
    **Implementação correta do protocolo:**

    * **JSON-RPC 2.0**: Siga especificação rigorosamente
    * **Message IDs**: Use UUIDs únicos para rastreamento
    * **Error codes**: Implemente códigos de erro padronizados
    * **Streaming**: Suporte SSE para operações longas
    * **Context**: Mantenha contexto entre chamadas quando necessário
  </Accordion>

  <Accordion icon="shield-check" title="Operação e Manutenção">
    **Garantindo operação estável:**

    * **Health checks**: Implemente endpoints de saúde
    * **Logging**: Registre todas as interações
    * **Metrics**: Colete métricas de performance
    * **Alerting**: Configure alertas para problemas
    * **Versioning**: Gerencie versões da API cuidadosamente
  </Accordion>
</AccordionGroup>

## Casos de Uso Comuns

<CardGroup cols={2}>
  <Card title="Sistemas Legados" icon="server">
    **Modernização Gradual:**

    * Integração de sistemas existentes
    * Migração incremental para nova arquitetura
    * Preservação de investimentos anteriores
  </Card>

  <Card title="Especialização Externa" icon="star">
    **Agentes Especializados:**

    * Análise de dados avançada
    * Processamento de imagens/vídeo
    * Machine learning especializado
  </Card>

  <Card title="Infraestrutura Distribuída" icon="cloud">
    **Multi-Cloud/Híbrido:**

    * Agentes em diferentes clouds
    * Edge computing
    * Compliance e residência de dados
  </Card>

  <Card title="Terceiros" icon="handshake">
    **Serviços de Terceiros:**

    * APIs de parceiros
    * Serviços SaaS especializados
    * Integrações com fornecedores
  </Card>
</CardGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Protocolo A2A" icon="network-wired" href="/a2a-protocol">
    Entenda o protocolo Agent-to-Agent em detalhes
  </Card>

  <Card title="Agente LLM" icon="brain" href="/agents/llm">
    Aprenda sobre agentes nativos inteligentes
  </Card>

  <Card title="Configurações" icon="gear" href="/configurations/index">
    Explore configurações avançadas de agentes
  </Card>

  <Card title="Workflow Agents" icon="sitemap" href="/agents/sequential">
    Use A2A Agents em workflows complexos
  </Card>
</CardGroup>

***

O A2A Agent é essencial para criar ecossistemas híbridos e integrar agentes externos. Use-o para aproveitar sistemas existentes e especialização externa mantendo a flexibilidade da plataforma Evo AI.