Skip to content

Configuração ESPv2 para A2A

Este documento descreve como configurar o ESPv2 (Extensible Service Proxy) do GCP como API Gateway para expor o agente iFriend via protocolo A2A.

Arquitetura

Partner Agent
    |
    | HTTPS + OAuth2/JWT
    v
ESPv2 (API Gateway)
    |
    | Internal Authentication (Service Account)
    v
Cloud Run (Privado, authenticated only)
    |
    v
Google ADK Agent (iFriend)

Pré-requisitos

Recurso Descrição
Cloud Run Serviço iFriend implantado
ESPv2 API Gateway configurado
GCloud CLI Ferramenta de linha de comando
Permissões Owner ou runtimeconfig.admin no projeto

Passo 1: Implantar ESPv2

Criar o config.yaml

swagger: 2.0
info:
  title: iFriend A2A API
  description: API iFriend Agent-to-Agent
  version: 1.0.0
host: a2a-ifriend.YOUR_PROJECT_ID.region.cloud.goog
basePath: /
schemes:
  - https
securityDefinitions:
  # JWT validation via Google
  jwt:
    type: oauth2
    authorizationUrl: https://accounts.google.com/o/oauth2/auth
    flow: pass-through
    x-google-jwt-locations:
      - header: Authorization
        prefix: "Bearer "
security:
  - jwt: []
paths:
  /v1/a2a/{rpc}:
    post:
      summary: A2A Invoke
      operationId: a2aInvoke
      x-google-backend:
        address: https://ifriend-a2a-YOUR_PROJECT_ID.region.run.app
      parameters:
        - name: rpc
          in: path
          required: true
          type: string
      responses:
        "200":
          description: Success
        "401":
          description: Unauthorized

  /.well-known/agent-card.json:
    get:
      summary: Agent Card
      x-google-backend:
        address: https://ifriend-a2a-YOUR_PROJECT_ID.region.run.app
      responses:
        "200":
          description: Agent Card

Criar API Gateway

# Criar API
gcloud api-gateway apis create ifriend-a2a-api \
  --display-name="iFriend A2A API" \
  --project=YOUR_PROJECT_ID

# Criar API Config
gcloud api-gateway api-configs create ifriend-a2a-config \
  --api=ifriend-a2a-api \
  --openapi-spec=config.yaml \
  --project=YOUR_PROJECT_ID

# Criar Gateway
gcloud api-gateway gateways create ifriend-a2a-gw \
  --api=ifriend-a2a-api \
  --api-config=ifriend-a2a-config \
  --location=YOUR_REGION \
  --project=YOUR_PROJECT_ID

Passo 2: Configurar Seguridad

Option A: API Key (simples)

# Criar API key
gcloud api-gateway api-keys create ifriend-a2a-key \
  --display-name="iFriend A2A Key" \
  --project=YOUR_PROJECT_ID

Option B: OAuth2/JWT (recomendado)

# No config.yaml, adicionar security com JWT
securityDefinitions:
  bearerAuth:
    type: oauth2
    flow: pass-through
    x-google-jwt-locations:
      - header: Authorization
        prefix: "Bearer "

Option C: Service Account (para parceiros)

# Criar service account para parceiro
gcloud iam service-accounts create partner-a2a-sa \
  --display-name="Partner A2A" \
  --project=YOUR_PROJECT_ID

# Dar permissão de invoke ao Cloud Run
gcloud run services add-iam-policy-binding ifriend-a2a \
  --member=serviceAccount:partner-a2a-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/run.invoker \
  --region=YOUR_REGION \
  --project=YOUR_PROJECT_ID

Passo 3: Configurar Rate Limiting

# No config.yaml
x-google-rate-limits:
  60:  # requests per minute
  x-google-quota:
    metric: a2a-requests
    window: 60s

Passo 4: Configurar CORS (se necessário)

# Adicionar ao config.yaml
options:
  x-google-cors:
    corsEnabled: true
    accessControlExposeHeaders:
      - Authorization

URLs Finais

Após deploy, você terá:

Endpoint URL
Base URL https://[gateway-url]/
Agent Card https://[gateway-url]/.well-known/agent-card.json
A2A Invoke https://[gateway-url]/v1/a2a/invoke

Configuração de Domínio Personalizado

gcloud api-gateway gateways create ifriend-a2a-gw \
  --api=ifriend-a2a-api \
  --api-config=ifriend-a2a-config \
  --location=YOUR_REGION \
  --project=YOUR_PROJECT_ID \
  --domain=a2a.ifriend.com

Monitoramento

# Ver logs
gcloud logging read "resource.type=gateway" \
  --project=YOUR_PROJECT_ID

# Ver métricas
gcloud monitoring metrics-descriptors list \
  --filter="metric.type=.googleapis.com/api_gateway" \
  --project=YOUR_PROJECT_ID

Integração com Parceiros

Fluxo 1: API Key simples

# Parceiro usa API key
curl -X POST https://a2a.ifriend.com/v1/a2a/invoke \
  -H "x-api-key: AIzaSy..." \
  -H "Content-Type: application/json" \
  -d '{...}'

Fluxo 2: OAuth2 + JWT (recomendado)

# 1. Obter token via OAuth2
curl -X POST https://a2a.ifriend.com/v1/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=PARTNER_CLIENT_ID" \
  -d "client_secret=PARTNER_SECRET"

# 2. Usar token
curl -X POST https://a2a.ifriend.com/v1/a2a/invoke \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

Troubleshooting

Problema Solução
401 Unauthorized Verificar JWT/API key
403 Forbidden Verificar service account permissions
404 Not Found Verificar rota no config.yaml
500 Error Verificar logs do Cloud Run
Rate limit Verificar quotas no console

Referências