1. Visão Geral da Arquitetura

A plataforma AIQGEN utiliza uma arquitetura de microserviços distribuída, projetada para alta disponibilidade, escalabilidade e conformidade com regulamentações financeiras brasileiras.

1.1 Diagrama de Arquitetura

┌───────────────────────────────────────────────────────────────────────────────┐
│                          CAMADA DE APRESENTAÇÃO                               │
│   • Apps Web/Mobile • Core Banking • CRM • APIs Parceiros                     │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                  API GATEWAY + POLICY ENGINE (PDP/PEP)                         │
│   • Autenticação • Rate Limiting • Routing                                     │
│   • Consentimento LGPD • Data Masking • Auditoria                              │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── ORQUESTRADOR DE AGENTES IA ─────────────────────────┐
│ Coordena agentes especializados e resolve fluxos multi-agente                  │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── CAMADA DE AGENTES IA ───────────────────────────────┐
│ • Agente Assessor • Agente Compliance IA                                       │
│ Cada agente:                                                                   │
│   ┌───────────────┐   ┌──────────────────────┐   ┌──────────────────────┐      │
│   │ Reasoning     │   │ MCP Client + Planner │   │ Knowledge Base (RAG) │      │
│   │ Guardrails    │   │ - Descobre Tools     │   │ - Normas, docs, FAQs │      │
│   │ HITL/Fallback │   │ - Chama via MCP      │   │ - Vector DB          │      │
│   └───────────────┘   └──────────────────────┘   └──────────────────────┘      │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── CAMADA MCP (TOOLING HUB) ──────────────────────────┐
│ MCP Router/Hub                                                                 │
│  • AuthZ/Scopes • Versioning • Circuit Breakers • Quotas                       │
│  • Logging/Tracing • Metrics                                                   │
│                                                                                │
│ Tools expostos (do Core ou externos):                                          │
│   - MarketData Tool (cotações, FX)                                             │
│   - Trading Tool (ordens)                                                      │
│   - KYC/AML Tool                                                               │
│   - Compliance Tool ◄── via Core                                               │
│   - Rules Tool ◄── via Core                                                    │
│   - Risk Model Tool ◄── via Core                                               │
│   - RAG/VectorDB Tool (documentos/normas)                                      │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── CAMADA DE DADOS & INTEGRAÇÕES ─────────────────────┐
│ • PostgreSQL (clientes, transações)                                           │
│ • Redis (cache) • S3/Blob (documentos)                                        │
│ • Open Finance • Bacen • CVM • Bureaus de Crédito                             │
│ • Feature Store • Event Bus (Kafka) • KMS/Secret Manager                      │
│ • Consent/Data Governance Layer (LGPD, Open Finance consent store)            │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────── CAMADA DE SERVIÇOS CORE ───────────────────────────┐
│ Serviços principais (fontes de verdade):                                      │
│   • Compliance Engine (Suitability, Bacen, CVM)                               │
│   • Rules Engine (políticas customizáveis)                                    │
│   • Risk/ML Engine (inferência online)                                        │
│                                                                               │
│ Serviços de plataforma diretos:                                               │
│   • ML/AI Engine (treinamento, batch scoring)                                 │
│   • Analytics Engine (dashboards, relatórios, BI)                             │
│   • Model Registry / MRM (gestão de modelos, drift, fairness, auditoria)      │
└───────────────────────────┬───────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                          SAÍDA PARA O CLIENTE                                 │
│   • JSON estruturado, insights, recomendações, alertas ou validações          │
│   • Explicabilidade + Evidências + IDs de normas/políticas                    │
└───────────────────────────────────────────────────────────────────────────────┘

1.2 Componentes Principais

API Gateway + Policy Engine

Ponto único de entrada com autenticação OAuth 2.0, rate limiting, validação LGPD e auditoria completa.

Orquestrador de Agentes IA

Coordena agentes especializados, gerencia fluxos multi-agente e otimiza performance.

Agentes IA Especializados

Cada agente possui três componentes:

Reasoning Engine: Lógica de decisão, guardrails e escalação humana
MCP Client: Descoberta e invocação de tools externos
Knowledge Base: Base de conhecimento com normas e documentos

MCP Hub (Tooling Hub)

Hub centralizado que expõe tools para os agentes: dados de mercado, compliance, risco, trading, etc.

Camada de Dados

PostgreSQL (dados), Redis (cache), S3 (arquivos), Vector DB (conhecimento), Kafka (eventos).

Serviços Core

Compliance Engine, Rules Engine, Risk/ML Engine, Analytics Engine e Model Registry.

1.3 MCP Hub - Tools Disponíveis

Hub centralizado que expõe tools para os agentes IA via protocolo MCP.

Tool	Descrição	Fonte
market_data	Cotações, FX, índices em tempo real	APIs de mercado
trading	Envio de ordens, consulta de posições	Core Banking
kyc_aml	Verificação de identidade e AML	Bureaus de crédito
compliance	Validação de regras CVM/Bacen	Compliance Engine
rules	Execução de regras customizáveis	Rules Engine
risk_model	Scoring e análise de risco	Risk/ML Engine
rag_vectordb	Busca em documentos e normas	Vector DB

Funcionalidades: Descoberta automática, versionamento, circuit breakers, quotas, observabilidade completa.

1.4 Arquitetura dos Agentes IA

Cada agente possui três componentes que trabalham em conjunto:

Reasoning Engine

Lógica de decisão, guardrails de segurança, escalação humana e estratégias de fallback.

MCP Client

Descoberta automática de tools, planejamento de execução e agregação de resultados.

Knowledge Base (RAG)

Vector database com normas, documentos técnicos, FAQs e busca semântica.

Fluxo de Processamento

text

1. Recebe requisição → 2. Analisa contexto → 3. Descobre tools
4. Consulta conhecimento → 5. Executa lógica → 6. Invoca tools
7. Agrega resultados → 8. Aplica validações → 9. Retorna resposta

1.5 Camada de Dados & Integrações

Armazenamento

PostgreSQL: Dados transacionais e perfis de clientes
Redis: Cache distribuído e sessões
S3/Blob: Documentos e arquivos de auditoria
Vector DB: Embeddings para busca semântica

Feature Store & Event Bus

Feature Store: Features para ML em tempo real
Kafka: Eventos assíncronos e streaming

Integrações Externas

Sistema	Protocolo	Dados
Open Finance Brasil	OAuth 2.0	Contas, transações, investimentos
Bacen	API Key	Regulamentações, comunicados
CVM	API Key	Normas, produtos, suitability
Bureaus de Crédito	OAuth 2.0	Score, histórico, consultas
APIs de Mercado	API Key	Cotações, FX, índices

Governança de Dados

Consent Management: Gestão de consentimentos LGPD
Data Lineage: Rastreabilidade de dados pessoais
Data Masking: Anonimização e pseudonimização
KMS/Secret Manager: Gerenciamento seguro de chaves

1.6 Escalabilidade

A plataforma escala horizontalmente usando AWS Elastic Beanstalk:

Auto-scaling: Instâncias escalam automaticamente baseado em CPU (70%), memória (80%) e requisições/segundo (> 500 req/s por instância)

Mínimo: 2 instâncias por agente (alta disponibilidade)
Máximo: 20 instâncias por agente (picos de demanda)
Latência P99: < 200ms para 99% das requisições
Throughput: > 5.000 requisições/segundo por ambiente

1.7 Serviços Core

Fontes de verdade da plataforma que fornecem capacidades fundamentais:

Serviços Principais

Compliance Engine: Suitability CVM, regras Bacen, monitoramento regulatório
Rules Engine: Políticas customizáveis, versionamento, hot deployment
Risk/ML Engine: Scoring em tempo real, model serving, A/B testing

Serviços de Plataforma

ML/AI Engine: Treinamento, batch scoring, model serving, AutoML
Analytics Engine: Dashboards, relatórios, BI, analytics em tempo real
Model Registry: Versionamento, drift detection, fairness monitoring

2. Referência de API

A API AIQGEN expõe agentes IA especializados para interação direta com usuários finais. Base URL para produção:

Base URL Produção: https://api.aiqgen.com/v1

Base URL Sandbox: https://sandbox-api.aiqgen.com/v1

2.1 Agente Assessor de Investimentos

O Agente Assessor é um assistente financeiro especializado em orientação de investimentos, análise de perfil de investidor e adequação de produtos conforme regulamentações CVM.

2.2 Autenticação

A API utiliza OAuth 2.0 (Client Credentials) e API Keys para autenticação.

bash

# OAuth 2.0
curl -X POST https://api.aiqgen.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials",
    "scope": "advisor:read advisor:write"
  }'

# API Key (alternativa)
curl https://api.aiqgen.com/v1/agents/advisor/interact \
  -H "X-API-Key: aiq_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json"

2.3 Endpoints do Agente Assessor

Interação Geral

POST /agents/advisor/interact

Interação aberta com o assistente financeiro em linguagem natural

Análise de Perfil

POST /agents/advisor/analyze-profile

Análise estruturada de perfil de investidor e suitability CVM

Resumo do Cliente

GET /agents/advisor/summary/{customerId}

Resumo consolidado da posição e recomendações do cliente

Exemplo: Interação Geral

json

{
  "customerId": "clt_9f8e7d6c5b4a3",
  "query": "Quais investimentos são adequados para meu perfil?",
  "context": {
    "sessionId": "sess_123",
    "timestamp": "2025-09-30T14:23:45.678Z"
  }
}

Exemplo: Análise de Perfil

json

{
  "customerId": "clt_9f8e7d6c5b4a3",
  "profile": {
    "idade": 35,
    "renda_mensal": 15000.00,
    "patrimonio": 500000.00,
    "objetivos": ["aposentadoria", "reserva_emergencia"],
    "experiencia_investimentos": "intermediaria",
    "horizonte_temporal": 240
  }
}

Resposta de Sucesso

json

{
  "status": "success",
  "data": {
    "customerId": "clt_9f8e7d6c5b4a3",
    "response": "Com base no seu perfil, recomendo uma carteira diversificada...",
    "recommendations": [
      {
        "product": "Fundo Multimercado Moderado",
        "allocation": 40.0,
        "risk": "moderado",
        "justification": "Adequado ao seu perfil de risco moderado"
      }
    ],
    "compliance": {
      "suitable": true,
      "norm": "CVM 539/2013",
      "documents_required": ["termo_adesao", "questionario_suitability"]
    },
    "metadata": {
      "agent": "advisor",
      "timestamp": "2025-09-30T14:23:45.678Z",
      "latency_ms": 187
    }
  }
}

2.4 Códigos de Erro

Código HTTP	Error Code	Descrição	Ação Recomendada
400	INVALID_REQUEST	Parâmetros inválidos ou faltantes	Verifique a documentação e corrija os parâmetros
401	UNAUTHORIZED	Token inválido ou expirado	Renove o token de autenticação
403	FORBIDDEN	Sem permissão para este recurso	Verifique os scopes do token
404	NOT_FOUND	Recurso não encontrado	Verifique o ID do recurso
429	RATE_LIMIT_EXCEEDED	Limite de requisições excedido	Aguarde antes de nova tentativa (veja header Retry-After)
500	INTERNAL_ERROR	Erro interno do servidor	Tente novamente. Se persistir, contate suporte
503	SERVICE_UNAVAILABLE	Serviço temporariamente indisponível	Aguarde e tente novamente

Exemplo de Resposta de Erro

json

{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Parâmetro 'renda_mensal' é obrigatório",
    "details": {
      "field": "renda_mensal",
      "constraint": "required",
      "received": null
    },
    "request_id": "req_abc123xyz789",
    "timestamp": "2025-09-30T14:30:00.000Z"
  }
}

Documentação em Desenvolvimento

As seções 3-11 estão sendo finalizadas. Por enquanto, você pode:

Solicitar Acesso Beta Contato Técnico

Documentação Técnica API AIQGEN

1. Visão Geral da Arquitetura

1.1 Diagrama de Arquitetura

1.2 Componentes Principais

API Gateway + Policy Engine

Orquestrador de Agentes IA

Agentes IA Especializados

MCP Hub (Tooling Hub)

Camada de Dados

Serviços Core

1.3 MCP Hub - Tools Disponíveis

1.4 Arquitetura dos Agentes IA

Reasoning Engine

MCP Client

Knowledge Base (RAG)

Fluxo de Processamento

1.5 Camada de Dados & Integrações

Armazenamento

Feature Store & Event Bus

Integrações Externas

Governança de Dados

1.6 Escalabilidade

1.7 Serviços Core

Serviços Principais

Serviços de Plataforma

2. Referência de API

2.1 Agente Assessor de Investimentos

2.2 Autenticação

2.3 Endpoints do Agente Assessor

Interação Geral

Análise de Perfil

Resumo do Cliente

Exemplo: Interação Geral

Exemplo: Análise de Perfil

Resposta de Sucesso

2.4 Códigos de Erro

Exemplo de Resposta de Erro

Documentação em Desenvolvimento