Skip to content

A2A — Para Desenvolvedores

Visão Geral

Este documento cobre duas áreas:

  1. como chamar agentes externos (iFriend como cliente A2A)
  2. como o servidor A2A funciona (iFriend como provedor A2A)

Parte 1: Chamando Agentes Externos (iFriend → Parceiro)

A iFriend pode chamar agentes externos usando o A2AClientManager.

Via Environment Variable

# JSON com agentes registrados
export A2A_EXTERNAL_AGENTS='{
  "turismobot": {
    "url": "https://turismobot.example.com/a2a/",
    "auth_token": "token-do-parceiro",
    "name": "TurismoBot",
    "description": "Agente de pacotes turísticos"
  }
}'

Via Código

from runtime.a2a.client import get_a2a_client_manager

manager = get_a2a_client_manager()
manager.register_agent(
    agent_id="turismobot",
    url="https://turismobot.example.com/a2a/",
    auth_token="token-do-parceiro",
    name="TurismoBot",
)

Usando nas Tools

from ifriend_agent.tools.a2a_client_tools import (
    listar_agentes_a2a,
    chamar_agente_a2a,
    consultar_task_a2a,
)

# Listar agentes disponíveis
agents = await listar_agentes_a2a(tool_context)

# Chamar agente externo
result = await chamar_agente_a2a(
    agent_id="turismobot",
    mensagem="Quais pacotes para Buenos Aires?",
    session_id="sess-123",
)

Habilitando no root_agent

Essas tools só ficam disponíveis para o root_agent (e portanto para o LLM decidir usá-las) se ENABLE_A2A_CLIENT=true — ver ifriend_agent/agent_builder.py e ifriend_agent/config/feature_flags.py. Desabilitada por padrão até haver um agente externo real configurado via A2A_EXTERNAL_AGENTS.

Para testar localmente sem depender do agente externo real (ex: antes do Agent Card do Agentforce estar disponível), suba um agente A2A de teste independente e valide o roundtrip completo:

# Terminal 1 — sobe um agente A2A de teste (fora da iFriend)
python examples/a2a_echo_agent.py --port 8766

# Terminal 2 — valida chamada direta à tool + (opcional) via root_agent/LLM
python examples/a2a_outbound_roundtrip_test.py
ENABLE_A2A_CLIENT=true python examples/a2a_outbound_roundtrip_test.py --via-agent

Parte 2: Servidor A2A (iFriend como Provedor)

Arquitetura

flowchart TD
    REQ["Request HTTP"] --> MW["A2AAuthMiddleware<br/>JWT Bearer + role ROLE_A2A_USER<br/>ou X-Client-Id/Secret/Integrator-Id (OAuth)"]
    MW -->|"request.state.a2a_auth"| CB["IfriendCallContextBuilder<br/>(remove X-Client-Secret dos headers)"]
    CB --> H["DefaultRequestHandler (a2a-sdk)"]
    H --> EX["IfriendA2aAgentExecutor"]
    EX --> RC["ifriend_request_converter<br/>user_id + state_delta (jwt_context / api_auth)"]
    RC --> ADK["ADK Agent (root_agent)"]

Não há API Gateway/Apigee na frente do Cloud Run em produção — o endpoint A2A é exposto diretamente, protegido pelo A2AAuthMiddleware (ver "Parte 3" abaixo). O OAuth de integrador usa o servidor OAuth da própria API iFriend; o rascunho create_a2a_app_oauth2 / runtime/a2a/auth/ (servidor OAuth2 próprio) continua não montado e é outra coisa.

Endpoints

O servidor A2A usa JSON-RPC 2.0 sobre HTTP. Todos os métodos são POST para o mesmo endpoint:

Path Método Descrição
/.well-known/agent-card.json GET Agent Card (público, sem auth)
/ POST JSON-RPC: message/send, message/stream, tasks/get, tasks/cancel

Métodos JSON-RPC suportados:

Método Descrição
message/send Envia mensagem e inicia/continua task (multi-turn)
message/stream Envia mensagem com streaming SSE (se ENABLE_A2A_STREAMING=true)
tasks/get Consulta resultado de task existente
tasks/cancel Cancela task em andamento

Handler

A integração é feita no unified_bot.py:

from runtime.a2a.server import create_a2a_app

if get_flag("ENABLE_A2A"):
    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)

Nota: O create_a2a_app usa A2AStarletteApplication.add_routes_to_app() diretamente (não o to_a2a() do ADK, que registra rotas via startup event — incompatível com app.mount()).

Contexto do chamador (extensão caller-context/v1)

O contrato para parceiros está em Para Parceiros → Contexto do chamador. A implementação tem três peças:

Peça Arquivo O que faz
Agent Card runtime/a2a/server.py (_caller_context_extension) Declara a extensão (AgentExtension, required=False, schema em params) e application/json nos input modes
Normalizador de body runtime/a2a/body_normalizer.py (A2ABodyNormalizerMiddleware, ASGI puro) Converte payload estilo protobuf/v1 para v0.3 antes da validação pydantic da a2a-sdk. O v0.3 passa intacto. Depois de entregar o body, delega o receive original (senão quebra o SSE de message/stream)
Request converter runtime/a2a/context_converter.py (ifriend_request_converter, via A2aAgentExecutorConfig) Chama o conversor padrão do ADK, extrai o contexto (DataPart > message.metadata > params.metadata), grava state_delta = {a2a_inbound_context, message_metadata: {source: "a2a", a2a_caller}} (o a2a_inbound_context só quando veio contexto, para não apagar o do 1º turno) e troca o DataPart por uma linha de resumo para o LLM

No agente:

  • before_agent_callback_combined popula {a2a_inbound_hint?} no prompt do orquestrador (ifriend_agent/config/a2a_inbound.py), com a regra "sem handoff, não peça de novo os dados já enviados".
  • O Trip não cumprimenta nem se apresenta ("Olá, sou ..."): quem cumprimenta o cliente é o agente chamador. O Trip responde direto ao pedido; a uma mensagem só de saudação, pergunta como pode ajudar com a viagem.
  • escalar_agentforce devolve status="origem_a2a" quando message_metadata.source == "a2a".

Para capturar um payload real, dá para ligar DEBUG só no logger a2a.server.apps.jsonrpc.jsonrpc_app (ele loga Request body). Cuidado: o body contém PII.

Generative UI (extensão generative-ui/v1) — opcional

O contrato para parceiros está em Para Parceiros → Reative os cards de busca de produto. Por padrão, A2A é tratado como "canal só texto" (is_plain_text_channel, ifriend_agent/config/channel.py) — nenhum agente emite blocks. Esta extensão reativa os blocks só para a busca de produto (busca_produtos/busca_produtos_qdrant), sem alterar o resto do canal só-texto (sem cumprimento, sem handoff, sem PDF/anexo).

Peça Arquivo O que faz
Agent Card runtime/a2a/server.py (_generative_ui_extension) Declara a extensão (AgentExtension, required=False)
Request converter runtime/a2a/context_converter.py (ifriend_request_converter) Checa GENERATIVE_UI_EXTENSION_URI in request.requested_extensions e grava message_metadata.generative_ui (recalculado a cada turno — o chamador deve mandar o header em toda mensagem)
Gate de domínio ifriend_agent/config/channel.py (blocks_enabled) True fora do canal só-texto; no canal só-texto, só com message_metadata.generative_ui=True. Chamado por busca_produtos_tool.py e busca_produtos_qdrant_tool.py no lugar de is_plain_text_channel
Prompt get_plain_text_channel_hint (channel.py) Com o opt-in, remove a instrução de nunca citar cards/repetir a lista em texto — só para busca de produto; as demais regras do canal só-texto continuam

Confirmado por teste (não só leitura de código, ver TestA2AGenerativeUIOptIn em ifriend_agent/tests/test_a2a_integration.py): o DataPart com os blocks, uma vez emitido pelo agente, chega ao chamador em Task.history tanto via message/send quanto message/stream, sem precisar de nenhum event_converter customizado — a2a-sdk's TaskManager.save_task_event já empurra toda mensagem de status intermediária (inclusive a do function_response com os blocks) para Task.history conforme os eventos seguintes chegam.

Escopo atual: só busca de produto. exibir_opcoes_produtos_tool.py/build_options_block_tool.py (cotação/orçamento) continuam sempre em modo texto no A2A, independente desta extensão.

Configurações

Variável Default Descrição
ENABLE_A2A false Habilita endpoint A2A
ENABLE_A2A_STREAMING false Habilita streaming SSE
A2A_BASE_URL — URL pública para Agent Card
A2A_REQUIRED_ROLE ROLE_A2A_USER Role mínima requerida
A2A_TASK_TTL_HOURS 24 TTL de tasks
ENABLE_A2A_OAUTH false Aceita o modo OAuth de integrador (requer ENABLE_A2A); ligado em stage e produção pelos cloudbuild*.yaml
IFRIEND_OAUTH_BASE_URL https://oauth.theifriend.com Servidor OAuth da API iFriend (stage: https://stage.oauth.theifriend.com)

Parte 3: Autenticação

O A2AAuthMiddleware (runtime/a2a/server.py) escolhe o modo por requisição. O OAuth é um modo a mais: o JWT continua funcionando e tem prioridade sempre que houver Authorization: Bearer.

JWT (padrão) OAuth de integrador
Quando Header Authorization: Bearer presente ENABLE_A2A_OAUTH=true, sem Bearer e com X-Client-Id
Cliente envia Authorization: Bearer <jwt> X-Client-Id, X-Client-Secret, X-Integrator-Id
Validação Assinatura/expiração + role A2A_REQUIRED_ROLE POST {IFRIEND_OAUTH_BASE_URL}/oauth2/token (client_credentials)
Chave no session.state jwt_context (mesmo formato dos outros canais, UserContext.to_state_dict()) api_auth = {type: "oauth", api_token, token_exp, integrator_id, client_id}
Tools chamam a API com Authorization: Bearer <jwt> (+ X-Context-Partner se houver partner_code) X-API-TOKEN: <access_token> + X-Integrator-Id
user_id da sessão sub do JWT oauth:{integrator_id}:{client_id}:{context_id}
Acesso a PDF/proposta/roteiro Pelas roles do JWT (ROLE_A2A_USER não é privilegiada) Liberado (mesmo acesso de affiliate)

JWT Bearer

O parceiro recebe uma conta de serviço (email/senha) provisionada pela iFriend com a role ROLE_A2A_USER, chama POST /authentication_token na API iFriend (mesmo endpoint usado internamente pelo próprio agente — ifriend_agent/tools/booking/auth.py) e envia o JWT como Authorization: Bearer <token>. O middleware valida assinatura, expiração e a role.

OAuth de integrador (API clients iFriend)

Para integradores que já usam a API iFriend com client_id/client_secret/integrator_id. O cliente não chama endpoint de token: manda os três headers em toda requisição.

  • IFriendOAuthTokenProvider (runtime/a2a/auth/ifriend_oauth.py) troca as credenciais por um access token (form-urlencoded, grant_type=client_credentials, resposta {access_token, expires_in}). O token fica em cache LRU (até 1000 credenciais), com chave sha256(client_id:client_secret) e um lock por chave; é renovado faltando 60s para expirar. Falhas nunca vão para o cache.
  • Respostas do middleware: faltou X-Client-Secret/X-Integrator-Id → 401 Missing header(s): ...; OAuth recusou (4xx) → 401 Invalid client credentials; OAuth fora do ar / 5xx / resposta inválida → 503 Authentication service unavailable.
  • O client_secret nunca vai para o session.state nem para os logs; o IfriendCallContextBuilder também o remove da cópia de headers que a a2a-sdk guarda no ServerCallContext.
  • No IFriendAPIClient, a precedência é use_system_auth → api_auth → jwt_context → sem auth. Tools com use_system_auth=True continuam com o JWT de sistema (API_EMAIL/API_PASSWORD) nos dois modos. Num 401 com X-API-TOKEN, o client tenta de novo sem auth (não dá para renovar o token ali — o client não tem o secret; o próximo turno A2A já chega com token novo).
  • O Agent Card anuncia os dois modos: securitySchemes com bearerAuth + clientId/clientSecret/integratorId (APIKeySecurityScheme, in: header) e security = Bearer ou os três headers.

Propagação para as tools e isolamento de sessão

A2AAuthMiddleware guarda a credencial validada em request.state.a2a_auth → IfriendCallContextBuilder copia para o ServerCallContext.state → ifriend_request_converter (configurado em A2aAgentExecutorConfig(request_converter=...)) define o user_id e manda um state_delta sempre com as duas chaves (jwt_context e api_auth, a do outro modo como None), para nenhuma credencial de um turno anterior sobrar na sessão.

Como o user_id é atrelado ao dono da credencial, um contextId não dá acesso à sessão de outro chamador (antes, o ADK usava A2A_USER_{context_id} e o jwt_context nem chegava às tools).

ADK fixado em 1.25.1: A2aAgentExecutorConfig é importado de google.adk.a2a.executor.a2a_agent_executor — o módulo google.adk.a2a.executor.config só existe em versões mais novas. Se o import quebrar, o unified_bot.py loga o erro e sobe sem o A2A (todas as rotas /a2a respondem 404).

⚠️ Rascunho não implantado: servidor OAuth2 próprio (create_a2a_app_oauth2)

runtime/a2a/auth/ (auth_server.py, middleware.py, registry.py, models.py) implementa um servidor OAuth2 completo (POST /token com client_credentials, GET /jwks, escopos, rate limit por cliente) e create_a2a_app_oauth2() em server.py monta esse fluxo — mas nenhum dos dois é chamado por unified_bot.py. É código real, testável isoladamente, mas não é o que responde em https://agents.theifriend.com/trip/a2a/ hoje. Não confundir com o OAuth de integrador acima, que usa o servidor OAuth da API iFriend e está no ar.


Estrutura do Módulo

runtime/a2a/
├── server.py              # create_a2a_app (EM PRODUÇÃO) + create_a2a_app_oauth2 (rascunho, não montado)
│   ├── A2AAuthMiddleware — JWT Bearer ou OAuth de integrador (alias antigo: A2AJWTAuthMiddleware)
│   ├── IfriendCallContextBuilder — leva a credencial ao ServerCallContext, sem o X-Client-Secret
│   ├── ifriend_request_converter — user_id do dono + state_delta (jwt_context / api_auth)
│   ├── _build_agent_card() — Agent Card com skills + security schemes
│   └── create_a2a_app() — Starlette app com add_routes_to_app()
├── executor.py            # IfriendA2aAgentExecutor — cancel() cooperativo (vendor lança NotImplementedError)
├── context_converter.py   # request_converter: contexto do chamador → session.state (extensão caller-context/v1)
├── body_normalizer.py     # middleware ASGI: payload protobuf/v1 → v0.3
├── client.py              # A2AClientManager + A2AClient (iFriend chamando agentes externos)
├── task_persistence.py    # CloudSQLTaskStore — persistência de tasks (task store real, não in-memory)
├── auth/
│   ├── ifriend_oauth.py   # IFriendOAuthTokenProvider — EM PRODUÇÃO (OAuth de integrador, cache de token)
│   ├── auth_server.py     # ⚠️ OAuth2 token server próprio — nunca montado
│   └── middleware.py      # ⚠️ A2AOAuth2Middleware — nunca montado

ifriend_agent/tools/a2a_client_tools.py   # habilitado via ENABLE_A2A_CLIENT
├── listar_agentes_a2a
├── chamar_agente_a2a
└── consultar_task_a2a

Testes

# a partir da raiz do repo (os testes importam ifriend_agent.* e runtime.*)
pytest ifriend_agent/tests/test_a2a.py -v                # auth middleware + agent card (app Starlette fake)
pytest ifriend_agent/tests/test_a2a_integration.py -v     # rotas JSON-RPC reais via create_a2a_app() (ASGI in-process)
pytest ifriend_agent/tests/test_a2a_oauth.py -v           # OAuth de integrador + propagação de jwt_context/api_auth e isolamento de sessão
pytest ifriend_agent/tests/test_a2a_caller_context.py -v  # contexto do chamador (DataPart/metadata/protobuf, persistência entre turnos) + Agent Card
pytest ifriend_agent/tests/test_a2a_inbound_hint.py -v    # hint do orquestrador para chamadas A2A
pytest ifriend_agent/tests/test_a2a_client.py -v          # A2AClient (inclui conformidade de schema com o a2a-sdk real)
pytest ifriend_agent/tests/test_a2a_client_tools.py -v    # camada de tools ADK (listar/chamar/consultar)

Rode estes testes com o ADK da versão fixada em ifriend_agent/requirements.txt (1.25.1). Se o seu ambiente local tiver uma versão mais nova do google-adk, imports que só existem nela passam nos testes e quebram no container.


Environment Variables

Variável Default Descrição
ENABLE_A2A false Habilita o servidor A2A como provedor
ENABLE_A2A_STREAMING false Habilita streaming SSE nas respostas
A2A_BASE_URL — URL pública para o Agent Card (ex: https://agents.theifriend.com/a2a)
A2A_REQUIRED_ROLE ROLE_A2A_USER Role JWT mínima para acessar os endpoints A2A
A2A_TASK_TTL_HOURS 24 TTL de tasks persistidas
ENABLE_A2A_OAUTH false Aceita OAuth de integrador (X-Client-Id/X-Client-Secret/X-Integrator-Id) — requer ENABLE_A2A
IFRIEND_OAUTH_BASE_URL https://oauth.theifriend.com Servidor OAuth da API iFriend (stage: https://stage.oauth.theifriend.com)
ENABLE_A2A_CLIENT false Habilita as tools de A2A client no root_agent (chamar agentes externos)
A2A_CLIENT_TIMEOUT 60 Timeout do cliente A2A em segundos
A2A_EXTERNAL_AGENTS {} JSON de agentes externos registrados