ADR 0005: Arquitetura de Proxy de Telemetria de Agentes

Status

Aceito

Contexto

Precisamos monitorar a performance e custos (tokens) de cada agente do IA Swarm no Dashboard Administrativo do SaaS. O agent-hub reside em um domínio separado e possui chaves de API internas que não podem ser expostas ao frontend. Além disso, precisamos garantir que clientes vejam apenas seus próprios dados de telemetria (isolamento multi-tenant).

Decisão

Implementar uma camada de proxy no backend-worker (SaaS Backend) que atua como ponte segura entre o saas-frontend e o agent-hub.

1. Proxy no Backend: O backend-worker expõe a rota /manager/telemetry/analytics.
2. Segurança: Este endpoint exige autenticação administrativa (verifyJwt) e utiliza a INTERNAL_API_KEY para falar com o agent-hub.
3. Multi-tenancy: O código do proxy encaminha o clientId (se presente) para o agent-hub, que filtra os logs do D1 antes de retornar a agregação.
4. Resiliência: O logging de telemetria no agent-hub é assíncrono (usando executionCtx.waitUntil) para evitar que falhas ou lentidão no registro afetem o tempo de resposta das APIs de IA.

Consequências

• Positivas:
  • Proteção completa de chaves internas do Hub.
  • Facilidade de consumo pelo frontend sem lidar com CORS complexos.
  • Isolamento de dados por cliente nativamente suportado.
• Negativas:
  • Pequena latência adicional introduzida pela camada de proxy.
  • Dependência do SaaS Backend estar operacional para visualização de métricas de IA.