Skip to content

Plano de Implementação — Protocolo A2A (Agent-to-Agent)

Visão Geral

Este documento detalha o plano para implementar e evoluir o protocolo A2A no projeto iFriend, permitindo que agentes externos conversem com os agentes iFriend.

Estado Atual (v1.0)

✅ Funcionalidades Implementadas

Componente Arquivo Status
Módulo A2A Core ifriend_agent/a2a.py ✅ Pronto
Middleware JWT Auth A2AJWTAuthMiddleware ✅ Pronto
Agent Card (6 skills) a2a.py:_build_agent_card ✅ Pronto
Feature Flag ENABLE_A2A em feature_flags.py ✅ Pronto
Integração FastAPI unified_bot.py:254-271 ✅ Pronto
Testes Unitários ifriend_agent/tests/test_a2a.py ✅ Pronto
Task Persistence ifriend_agent/a2a/task_persistence.py ✅ Pronto
Exemplos de Uso examples/a2a_client_example.py ✅ Pronto

⚠️ Funcionalidades Parciais

Componente Status Observação
Streaming (SSE) ⚠️ Habilitável Controlled via ENABLE_A2A_STREAMING env var
Task Persistence ⚠️ CloudSQL TTL default: 24h

Funcionalidades Planejadas

Phase 1 — Core A2A (v1.0) — ✅ COMPLETO

  • [x] Exposição do root_agent via JSON-RPC 2.0
  • [x] Autenticação JWT com role verification
  • [x] Agent Card público (discovery)
  • [x] Feature flag ENABLE_A2A
  • [x] Task persistence (CloudSQL)
  • [x] Exemplos de cliente

Phase 2 — Streaming & Enhancement (v1.1) — 🔄 EM PROGRESSO

  • [x] Streaming capability no AgentCard
  • [ ] SSE streaming endpoint
  • [ ] Task cancellation support
  • [ ] Push notifications setup

Phase 3 — Enterprise Features (v1.2) — 📋 PLANEJADO

  • [ ] Agent Registry (discovery de outros agentes)
  • [ ] A2A Client (chamar agentes externos)
  • [ ] Multi-agent orchestration
  • [ ] Metrics & observability

Variáveis de Ambiente

A2A Protocol

Variável Default Descrição
ENABLE_A2A false Habilita endpoint A2A
ENABLE_A2A_STREAMING false Habilita streaming SSE
A2A_BASE_URL — URL pública do endpoint (para AgentCard)
A2A_REQUIRED_ROLE ROLE_A2A_USER Role JWT obrigatória
A2A_USE_HTTPS false Forçar HTTPS no AgentCard
A2A_TASK_TTL_HOURS 24 TTL de tasks em horas

Arquitetura

                    ┌─────────────────┐
                    │  Agente Externo │
                    │   (client A2A)  │
                    └────────┬────────┘
                             │
                             │ HTTPS + JWT (Bearer)
                             │ Authorization: Bearer <token>
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI (unified_bot.py)                │
│                    app.mount("/a2a", a2a_app)              │
└─────────────────────────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
              ▼                             ▼
    ┌─────────────────┐          ┌─────────────────┐
    │ Agent Card     │          │  JSON-RPC 2.0   │
    │ /.well-known/   │          │  /a2a/          │
    │ agent-card.json│          │                 │
    │ ( público )    │          │  - message/send │
    └─────────────────┘          │  - tasks/get   │
                                 │  - tasks/cancel│
                                 └────────┬────────┘
                                          │
                                          ▼
                                ┌─────────────────┐
                                │  A2AJWTAuth    │
                                │  Middleware    │
                                │  - JWT verify  │
                                │  - Role check  │
                                └────────┬────────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  to_a2a()       │
                                │  (ADK)          │
                                └────────┬────────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  root_agent     │
                                │  (iFriend)      │
                                └─────────────────┘

    ┌─────────────────────────────────────────────┐
    │  Task Persistence (CloudSQL)                │
    │  a2a_tasks table (auto-created)              │
    └─────────────────────────────────────────────┘

Integração no Código

Startup (unified_bot.py)

if get_flag("ENABLE_A2A"):
    from ifriend_agent.a2a import create_a2a_app

    a2a_app = create_a2a_app(
        runner=runner,
        jwt_manager=jwt_manager,
        host="0.0.0.0",
        port=int(os.environ.get("PORT", 8080)),
        enable_task_persistence=True,
    )
    app.mount("/a2a", a2a_app)

Cliente Externo

import requests

payload = {
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "parts": [{"type": "text", "text": "Quero experiências em SP"}]
        }
    }
}

headers = {"Authorization": "Bearer <JWT_WITH_ROLE_A2A_USER>"}

resp = requests.post(
    "https://agents.theifriend.com/trip/a2a/",
    json=payload,
    headers=headers
)

Testes

Testes Unitários

cd ifriend_agent
pytest tests/test_a2a.py -v

Teste Manual

export A2A_JWT_TOKEN="eyJ..."
export A2A_BASE_URL="http://localhost:8080/a2a"
python examples/a2a_client_example.py

Checklist de Deploy

  • [ ] Habilitar ENABLE_A2A=true no environment
  • [ ] Configurar A2A_BASE_URL (URL pública do agente)
  • [ ] Garantir que CloudSQL está configurado (para task persistence)
  • [ ] Verificar que JWT provider emite role ROLE_A2A_USER
  • [ ] Configurar CORS se agentes externos forem de outros domínios

Próximos Passos

  1. Habilitar streaming: Set ENABLE_A2A_STREAMING=true e testar
  2. Adicionar task cancellation: Já suportado pelo ADK, verificar
  3. Criar Agent Registry: Para discovery de outros agentes
  4. Implementar A2A Client: Para chamar agentes externos da iFriend
  5. Adicionar métricas: Monitoring de requests A2A

Referências