Integração A2A — Para Parceiros¶

O que é o protocolo A2A?¶

O Agent-to-Agent (A2A) é um protocolo que permite que seu agente de IA se comunique com o agente iFriend através de JSON-RPC 2.0 sobre HTTP.

Quando usar?¶

Seu agente de IA precisa de informações de turismo que a iFriend possui
Você quer que seus usuários façam reservas de experiências
Você quer oferecer serviços da iFriend como parte do seu ecossistema
Você quer integrar o iFriend com seu sistema de agentes (OpenAI Agents, LangGraph, CrewAI, Semantic Kernel, etc.)

Arquitetura de Segurança¶

A iFriend usa uma arquitetura de segurança em camadas:

Partner Agent
    |
    | HTTPS + OAuth2/JWT
    v
API Gateway (ESPv2/Apigee)
    |
    | Internal Service Account
    v
Cloud Run (privado, autenticação requerida)
    |
    v
Google ADK Agent (iFriend)

Por que essa arquitetura?¶

Cloud Run privado: O serviço iFriend não é acessível diretamente pela internet
API Gateway: Valida autenticação, aplica rate limit, audit logging
Service Account interna: O gateway chama o Cloud Run usando identidade do GCP
Parceiro nunca acessa Cloud Run diretamente: Maior segurança

Quick Start¶

1. Obtenha as credenciais¶

Entre em contato com a equipe iFriend para receber:

A2A_API_URL — URL do endpoint da API
CLIENT_ID — Identificador do seu cliente
CLIENT_SECRET — Segredo para geração de token
JWKS_URL — URL das chaves públicas para validação (opcional)

2. Obtenha o Agent Card (úblico)¶

curl https://api.ifriend.com/v1/a2a/.well-known/agent-card.json

Você receberá algo como:

{
  "name": "ifriend_agent",
  "version": "3.3.6",
  "protocolVersion": "0.2.6",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "skills": [
    {"id": "discovery", "name": "Busca de experiências"},
    {"id": "quote", "name": "Cotação de preços"},
    {"id": "booking", "name": "Reservas"},
    {"id": "payment", "name": "Pagamentos"},
    {"id": "custom_tour", "name": "Tour personalizado"},
    {"id": "booking_info", "name": "Consulta de reservas"}
  ]
}

3. Autentique e obtenha access_token¶

Usando Client Credentials (recomendado)¶

# Obter access_token
curl -X POST https://api.ifriend.com/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "scope=agent.invoke"

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agent.invoke"
}

OU usando JWT pré-assinado (para parceiros que já têm sua própria infraestrutura)¶

Se você já tem um servidor de autenticação, pode enviar um JWT próprio:

# Seu servidor gera JWT com:
# {
#   "iss": "sua-empresa",
#   "sub": "agent-id",
#   "aud": "ifriend-a2a",
#   "scope": "agent.invoke",
#   "exp": 1770000000
# }
# Assinado com sua chave privada (RS256)

Consulte a seção "Validação de JWT" para os requisitos.

4. Envie uma mensagem¶

curl -X POST https://api.ifriend.com/v1/a2a/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Quero experiências em São Paulo"}]
      },
      "session_id": "optinal-session-id"
    }
  }'

5. Receba a resposta¶

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "taskId": "task-abc123",
    "messages": [
      {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "Encontrei várias experiências em São Paulo..."
          }
        ]
      }
    ]
  }
}

Autenticação¶

Método 1: Client Credentials (Recomendado)¶

Para parceiros que não têm infraestrutura de autenticação própria:

Receba CLIENT_ID e CLIENT_SECRET da iFriend
Use o endpoint /v1/auth/token para obter access_token
Use o token nas requisições A2A

Método 2: JWT Próprio¶

Para parceiros que já têm Auth Server:

Gere um JWT com:
iss: Identificador da sua empresa (registrado na iFriend)
sub: Identificador do seu agente
aud: "ifriend-a2a"
scope: Escopos solicitados (ex: "agent.invoke")
exp: Timestamp de expiração
iat: Timestamp de emissão
Assine com RS256 usando sua chave privada
Registre sua chave pública ou JWKS_URL com a iFriend antecipadamente

Escopos Disponíveis¶

Escopo	Descrição
`agent.invoke`	Executar o agente
`agent.discovery`	Buscar experiências
`agent.quote`	Cotar preços
`agent.booking`	Criar reservas
`agent.booking_info`	Consultar reservas
`agent.payment`	Processar pagamentos
`agent.custom_tour`	Tours personalizados

Endpoints Disponíveis¶

Endpoint	Método	Descrição
`/v1/auth/token`	POST	Obter access_token
`/v1/auth/jwks`	GET	Obter chaves públicas (JWKS)
`/v1/a2a/invoke`	POST	Executar agente (message/send)
`/v1/a2a/stream`	POST	Streaming (se habilitado)
`/v1/a2a/task/{id}`	GET	Consultar task
`/v1/a2a/task/{id}`	DELETE	Cancelar task
`/v1/capabilities`	GET	Capabilities do agente

Validação de JWT (para Método 2)¶

Se usar JWT próprio, o gateway verifica:

issuer (iss): Deve ser sua empresa registrada
audience (aud): Deve ser "ifriend-a2a"
expiration (exp): Não expirado
assinatura: RS256, chave registrada
escopo (scope): Um dos escopos permitidos

Rate Limits¶

Plano	Limite
Trial	60 requisições/minuto
Basic	300 requisições/minuto
Enterprise	Customizável

Webhooks (Opcional)¶

Para receber notificações assíncronas:

# Ao registrar, defina seu webhook_url
curl -X POST https://api.ifriend.com/v1/webhooks/register \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "url": "https://seu-dominio.com/webhook",
    "events": ["task.completed", "task.failed"]
  }'

Exemplos de Código¶

Consulte Exemplos para código em Python, JavaScript, e outras linguagens.

Suporte¶

Em caso de dúvidas: suporte@ifriend.com

Renovação de Credenciais¶

Tokens de access_token expiram em 1 hora. Use refresh_token:

curl -X POST https://api.ifriend.com/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=SEU_REFRESH_TOKEN" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"