Arquitetura de referência Agentic

Uma arquitetura de referência pensada explicitamente para MCP + Agentic Retail, mantendo OAuth 2.0 Client Credentials como base, adicionando as camadas necessárias para segurança, controle e governança.

Proposta estruturada em 3 níveis:

Visão geral (diagrama lógico)
Componentes e responsabilidades
Fluxos críticos (token, agente, API)

1. Arquitetura de Referência — Visão Geral

🔷 Diagrama lógico (alto nível)

┌──────────────────────────┐
│        LLM / Agent       │
│  (MCP Client / Orchestr.)│
└───────────┬──────────────┘
            │ Tool Call (contexto + intenção)
            ▼
┌──────────────────────────┐
│   Agent Gateway / Proxy  │
│  (Guardrails + Policy)   │
└───────────┬──────────────┘
            │ chamada validada
            ▼
┌──────────────────────────┐
│  Identity & Access Layer │
│  ├─ OAuth 2.0 Server     │
│  ├─ Token Introspection  │
│  └─ Agent Identity       │
└───────────┬──────────────┘
            │ token válido
            ▼
┌──────────────────────────┐
│     API Gateway          │
│  ├─ Rate limit           │
│  ├─ Quotas contextuais   │
│  ├─ mTLS (opcional)      │
│  └─ Audit / Logs         │
└───────────┬──────────────┘
            │ request autorizada
            ▼
┌──────────────────────────┐
│   Correios APIs (REST)   │
│   └─ Rastreamento (SRO)  │
└──────────────────────────┘

2. Componentes essenciais (o que cada bloco faz)

2.1 LLM / Agente (MCP)

Responsabilidade:

Raciocínio
Decisão
Geração de chamadas de ferramenta

Boas práticas:

❌ Nunca armazenar client_secret
✅ Nunca falar direto com OAuth
✅ Usar apenas o Agent Gateway

📌 O agente não é confiável por definição.

2.2 Agent Gateway / Tool Proxy (camada crítica)

👉 Este é o componente mais importante em ambientes agentic

Funções:

Validar intenção da chamada
Enriquecer contexto
Aplicar políticas antes da API

Exemplos de controles:

Máximo de objetos por chamada
Bloqueio de loops
Validação de parâmetros
Allowlist de endpoints

📌 Aqui se “domestica” o agente.

2.3 Identity & Access Layer

OAuth 2.0 (permanece)

Fluxo: Client Credentials
Um client_id por:
- agente ou
- tipo de agente

Token JWT com claims adicionais:

{

“iss”: “correios.oauth”,

“client_id”: “agent-retail-01”,

“agent_id”: “rastreamento-autonomo”,

“use_case”: “agentic_retail”,

“scope”: “rastreamento.read”,

“env”: “prod”

}

📌 OAuth autentica quem, não por quê — por isso os claims.

2.4 API Gateway

Controles obrigatórios:

Rate limit por:
- client_id
- agent_id
- use_case
Quotas temporais
Circuit breaker
Logs estruturados

Controles opcionais (alto rigor):

mTLS entre gateway ↔ backend
IP allowlist

2.5 APIs Correios (Rastreamento)

Permanecem inalteradas
Continuam protegidas por OAuth
Não “sabem” que são chamadas por agentes

3. Fluxos críticos

3.1 Fluxo de Token (machine-to-machine)

Agent Gateway
   |
   | client_id + secret
   v
OAuth Server
   |
   | access_token (JWT)
   v
Agent Gateway (cache)

✅ Token nunca vai para o LLM
✅ Token nunca aparece no prompt

3.2 Fluxo de chamada agentic (controlado)

LLM decide → "consultar rastreamento"

↓
Agent Gateway valida:
- uso permitido?
- volume aceitável?
- contexto correto?

↓
API Gateway aplica:
- rate limit
- quotas

↓
API Correios

3.3 Fluxo de bloqueio (exemplo real)

Agente entra em loop de consultas

Agent Gateway detecta padrão
Chamada bloqueada
Evento auditado
Agente recebe resposta neutra

✅ OAuth continua válido
✅ Negócio protegido

4. O que esta arquitetura resolve

Risco	Resolvido?
Vazamento de token	⚠️ Mitigado
Uso fora de contexto	✅
Loop agentic	✅
Abuso legítimo	✅
Falta de rastreabilidade	✅
OAuth insuficiente	✅ Complementado

5. Avaliação final (parecer)

“A arquitetura proposta mantém OAuth 2.0 Client Credentials como base de identidade e autorização, acrescentando camadas de controle contextual, identidade de agente e governança de uso, tornando-a adequada para cenários MCP e Agentic Retail sem necessidade de alteração do core de APIs.”

Hybrid Retail