backlog para criação da RI

2026-11-05 22:14:11 +00:00 · 2026-09-11 14:03:12 -03:00
parent 8825063fa0
commit be5690d1c8
3 changed files with 1715 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -2,12 +2,13 @@
 ## Reference Architecture para acesso agêntico governado por Client-Bound Entitlements

 **Status:** Working Draft v0.2  
-**Publicação:** 3 de setembro de 2026  
 **Escopo:** Arquitetura corporativa para publicar, descobrir, personalizar, orquestrar e executar capacidades empresariais por meio de MCP, com um MCP Gateway atuando como Policy Enforcement Point (PEP), o MCP Client definindo o limite máximo de privilégio e o Service Orchestrator calculando a Next Best Action (NBA) dentro desse limite.

 ## Reference implementation

-A implementação executável desta arquitetura está em [`RI/`](RI/README.md), com gateway MCP, PEP/PDP, OPA, Keycloak, serviços de exemplo, testes adversariais e ambiente Docker Compose.
+A implementação executável desta arquitetura está planejada para [`RI/`](RI/README.md) — diretório a ser criado a partir do backlog estruturado em [`docs/RI-PLANNING.md`](docs/RI-PLANNING.md) — com gateway MCP, PEP/PDP sobre OPA (Rego v1), Keycloak como Identity Provider (OAuth 2.1/OIDC), serviços de exemplo, testes adversariais e ambiente Docker Compose.
+
+> **Nota de implementação (v0.2+).** A camada de orquestração de agentes (LangGraph) e de observabilidade de LLM (Langfuse) da RI adota como referência operacional o projeto open-source *Agent Platform OCI*, de Christiano Hoshikawa — ver §6.2, §6.12, §35.1 e §43.5 para as anotações correspondentes, e `docs/research/hoshikawa-agent-platform-oci.md` para a análise completa.

 ### Novidades da v0.2

@@ -578,6 +579,8 @@ Guardrails são defense-in-depth, não substitutos do PEP.

 O Orchestrator decide **qual ação tentar**. O PEP/PDP decide **se aquela ação pode ser executada**, e o backend continua decidindo sobre seus próprios recursos.

+> **Nota de implementação.** Na prática, este papel é frequentemente cumprido por uma plataforma de orquestração multiagente externa e independente do bus — por exemplo, um framework baseado em LangGraph com múltiplos backends de agente e um supervisor global de roteamento entre eles (ver `Agent Platform OCI`, §43.5). Quando isso ocorre, cada backend/agente dessa plataforma deve se conectar ao Enterprise MCP Service Bus como um MCP Client distinto (§6.3), nunca como uma extensão de confiança do Gateway. A relação entre este papel e o Service Orchestrator (§6.12) desta arquitetura é de escolha modular, não de sobreposição: ver §6.12 para os dois modos de integração possíveis.
+
 ---

 ### 6.3 MCP Client
@@ -903,8 +906,12 @@ Responsabilidades:
 - correlacionar decisão, chamada MCP, execução e resultado;
 - recalcular ou degradar com segurança quando uma ação for negada ou indisponível.

+> **Nota de implementação.** O termo NBA usado nesta arquitetura cobre também a escolha de uma **Next Best Offer (NBO)** quando o universo de `FilteredOfferings` (§6.11) inclui ofertas comerciais, benefícios ou campanhas, e não apenas ações transacionais. A "função de decisão versionada" citada acima é deliberadamente pluggable — pode ser um conjunto de regras determinístico ou incorporar um modelo de IA de ranking/recomendação — desde que opere estritamente sobre `FilteredOfferings`, nunca ampliando o universo permitido (Axiom 11).
+
 O Orchestrator não pode emitir credenciais de maior privilégio, alterar entitlement, suprimir a reautorização de `tools/call` ou substituir a decisão do backend.

+> **Nota de implementação — dois modos de integração.** Esta arquitetura não impõe onde o cálculo de NBA/NBO deve residir. **Modo A (governança-somente):** uma plataforma de orquestração externa (§6.2) mantém sua própria lógica de decisão e consome o bus apenas para acesso governado ao Fabric. **Modo B (substituição completa):** o Service Orchestrator aqui descrito assume integralmente o cálculo de NBA/NBO, e a plataforma externa, quando existente, atua apenas como executor de dispatch via Agent Runtime (§6.13). Em ambos os modos o núcleo de segurança (§6.4, §6.5) permanece no mesmo lugar — apenas a origem da decisão de NBA/NBO muda. Modularidade e compatibilidade são, portanto, uma escolha do adotante, não uma imposição da arquitetura.
+
 ### 6.13 Agent Runtime e channel adapters

 O Agent Runtime traduz a NBA em execução coordenada. Ele gerencia sessão, contexto mínimo, lifecycle do agente, retries seguros e handoff. Channel adapters encapsulam diferenças entre experiências conversacionais, notificações proativas, mídia, campanhas e novos agentes especializados.
@@ -2115,6 +2122,8 @@ agent.role = "finance-admin"

 **Problema:** informação controlada pelo agente eleva privilégio.

+> **Nota de implementação.** Este anti-pattern não é apenas hipotético. A análise de um MCP Gateway de terceiros (projeto *Agent Platform OCI*, §43.5) encontrou exatamente esta forma: um allowlist de tools avaliado sobre um campo `agent_id` que chega como dado do payload de entrada da conversa, não como claim de uma identidade autenticada verificada independentemente — a própria documentação daquele projeto reconhece que "a política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server". O caso serve como validação prática do princípio P3 (§4): qualquer campo que o agente, o canal ou o payload de entrada possam declarar deve ser tratado como não confiável para fins de autorização, mesmo quando usado de boa-fé por um MCP Gateway aparentemente funcional.
+
 ---

 ### 35.2 Catálogo completo + deny somente na execução
@@ -2452,6 +2461,12 @@ Publicações recentes descrevem:

 Esses trabalhos mostram convergência do mercado para gateways, agregação e policy enforcement.

+### 43.5 Plataformas de orquestração multiagente
+
+Frameworks de orquestração de agentes baseados em LangGraph — como o projeto open-source **Agent Platform OCI**, de Christiano Hoshikawa (`github.com/hoshikawa2/agent_platform_oci`) — resolvem um problema complementar ao desta arquitetura: coordenação de múltiplos agentes/backends, roteamento de conversa, handoff, checkpointing de estado e observabilidade de LLM (no caso daquele projeto, via Langfuse, com uma taxonomia de eventos de negócio/operacional/guardrail). Esse tipo de plataforma tipicamente expõe seu próprio "MCP Gateway" para dar aos agentes acesso a tools, mas com um modelo de autorização simplificado — no caso analisado, um allowlist declarativo por `agent_id`, sem PDP dedicado nem separação formal entre discovery e execution authorization.
+
+A relação entre esta arquitetura e uma plataforma desse tipo não é de concorrência, mas de composição: a plataforma de orquestração cumpre o papel de Agent Host/Orchestrator (§6.2) e, opcionalmente, de Service Orchestrator (§6.12, Modo A), enquanto o Enterprise MCP Service Bus assume integralmente o papel de PEP/PDP e Fabric — cada backend de agente daquela plataforma conecta-se ao bus como um MCP Client distinto (§6.3), e o "MCP Gateway" interno da plataforma deixa de ser a fonte de autorização, sendo substituído pelo Gateway desta arquitetura. Ver §35.1 para o anti-pattern especificamente observado nesse tipo de integração, e §6.12 para o Modo B, em que o Service Orchestrator desta arquitetura substitui inteiramente a camada de decisão de NBA/NBO da plataforma externa.
+
 ---

 ## 44. Relação com governança interna de Skills/MCP
@@ -2656,17 +2671,20 @@ A visão arquitetural está consistente, mas uma implementação concreta precis
   - workload identity?
   - mTLS?
   - cloud IAM?
+   - → **Decisão adotada na RI**: OAuth 2.1 `client_credentials` via Keycloak, com mTLS/workload identity documentados como extensão de produção não implementada (`docs/RI-PLANNING.md`, ADR-019).

 2. **Qual será a granularidade dos client profiles?**
   - domínio?
   - domínio + read/write?
   - domínio + risk tier?
+   - → **Decisão adotada na RI**: domínio + risk tier (ver §17; `docs/RI-PLANNING.md`, ADR-008).

 3. **Qual engine implementará o PDP?**
   - engine próprio?
   - Cedar?
   - OPA/Rego?
   - IAM/policy service existente?
+   - → **Decisão adotada na RI**: OPA/Rego (sintaxe v1), self-hosted (`docs/RI-PLANNING.md`, ADR-025 — não confundir com o ADR-010 acima, "Global Capability Registry Governance", que é uma decisão distinta).

 4. **Quem é owner do Global Capability Registry?**

@@ -2674,16 +2692,21 @@ A visão arquitetural está consistente, mas uma implementação concreta precis
   - workload identity?
   - OBO/token exchange?
   - backend service account?
+   - → **Decisão adotada na RI**: token exchange (RFC 8693) quando o backend suportar OIDC, senão service account isolado por adapter (`docs/RI-PLANNING.md`, ADR-020).

 6. **Quais tools exigirão human approval?**

 7. **Como policy revocation invalidará caches?**
+   - → **Decisão adotada na RI**: invalidação disparada por evento de revogação/mudança de política, com TTL curto como rede de segurança adicional (`docs/RI-PLANNING.md`, EP-04-T03/EP-05-T03).

 8. **Qual será o modelo de federation entre domain MCP servers?**
+   - → **Escopo da RI**: federação completa fica fora de escopo — a RI demonstra 2 domínios (Sales, Finance), suficiente para provar segmentação/blast-radius (`docs/RI-PLANNING.md`, lacuna G9).

 9. **Como impedir bypass em ambientes híbridos/multi-cloud?**
+   - → **Escopo da RI**: a RI roda 100% local via Docker Compose; ambientes híbridos/multi-cloud ficam fora de escopo (`docs/RI-PLANNING.md`, lacuna G10).

 10. **Como separar dev/test/prod client identities e entitlements?**
+    - → **Decisão adotada na RI**: overlay de configuração por ambiente (`config/env/{dev,ci}.yaml`), sem infraestrutura cloud real (`docs/RI-PLANNING.md`, P10).

 ---

@@ -2711,6 +2734,8 @@ ADR-016: Agent Runtime Dispatch and Handoff Contract
 ADR-017: End-to-End Decision and Execution Correlation
 ```

+> **Nota de implementação.** A RI estende esta lista com ADR-018 em diante — decisões de tecnologia concreta (stack Python/YAML, engine do PDP, Identity Provider, downstream identity, referência de implementação Python/LangGraph/Langfuse, posicionamento frente a plataformas de orquestração externas) necessárias para transformar estes 17 ADRs conceituais em uma implementação executável. Ver `docs/RI-PLANNING.md`, seção 8.4, para a lista completa (ADR-001 a ADR-025) e `docs/research/hoshikawa-agent-platform-oci.md` para a pesquisa que fundamenta ADR-022 a ADR-024.
+
 ---

 ## 50. Axiomas da arquitetura
--- a/docs/RI-PLANNING.md
+++ b/docs/RI-PLANNING.md
--- a/docs/research/hoshikawa-agent-platform-oci.md
+++ b/docs/research/hoshikawa-agent-platform-oci.md
@@ -0,0 +1,135 @@
+# Pesquisa: Agent Platform OCI (Christiano Hoshikawa) como referência Python/LangGraph/Langfuse
+
+> Fonte: https://github.com/hoshikawa2/agent_platform_oci (README + SPEC-001, 002, 003, 004, 007, 012, 018). Analisado em 2026-09-11 para fechar as lacunas G2/G8 do [`../RI-PLANNING.md`](../RI-PLANNING.md). Referenciado por ADR-022/ADR-023.
+>
+> **Escopo desta pesquisa**: extrair o padrão *operacional* de LangGraph/Langfuse/MCP daquele projeto para a camada de implementação Python da nossa RI. O núcleo de segurança (PEP/PDP/Client-Bound Entitlement) da nossa arquitetura permanece 100% definido pelo `README.md` na raiz deste repositório — nunca pelo projeto pesquisado aqui.
+
+---
+
+## 1. Padrão LangGraph
+
+**StateGraph — nós e shape do state.** O grafo por backend é fixo e corporativo:
+
+```text
+START → input_guardrails → routing_decision → [agente(s) de domínio] → output_supervisor
+      → output_guardrails → judge → supervisor_review → persist → END
+routing_decision → handoff → routing_decision   (aresta condicional de retorno)
+```
+
+`AgentState` é um `TypedDict(total=False)` com: `user_text, sanitized_input, response_text, tenant_id, agent_id, channel, session_id, conversation_key, message_id, route, intent, context, business_context, tool_arguments, mcp_tools, mcp_results, rag_context, rag_metadata, guardrails, judges, metadata, errors`, mais `active_transaction`/`last_transaction` na extensão transacional (contrato durável de estado, sobrevive a checkpoint/resume).
+
+Registrar um novo agente é mecânico: import da classe → instanciar no `__init__` do workflow (recebendo dependências compartilhadas: telemetry, tool_router, rag_service, cache, observer, memory) → wrapper assíncrono com span de telemetria → `builder.add_node(...)` → entrada em `add_conditional_edges("routing_decision", ...)` → ligação ao `output_supervisor`.
+
+**Duas camadas de roteamento, explicitamente separadas:**
+- **Supervisor/router local do backend** — decide o fluxo interno de um agente (`routing.yaml`, `ROUTING_MODE=router|supervisor`).
+- **Global Supervisor / Agent Gateway** — serviço deployável separado que decide **qual backend inteiro** trata a conversa (`GLOBAL_ROUTING_MODE=router|supervisor|hybrid`, `backends.yaml`). Roteamento HTTP entre backends, não é um segundo LangGraph.
+
+**Checkpointing**: providers `memory` (testes), `sqlite` (dev local), `mongodb` (distribuído), `autonomous` (produção OCI). Contrato: `{conversation_key, checkpoint_id, state, pending_writes, created_at}`.
+
+**Handoff**: intra-backend via aresta condicional `routing_decision → handoff → routing_decision`; inter-backend via `metadata.handover_backend` na resposta, detectado pelo Agent Gateway, que mantém `global_session_id` separado de `backend_session_id`.
+
+---
+
+## 2. Padrão Langfuse
+
+**Taxonomia IC / NOC / GRL** (não é "Informational Context" — é evento de **negócio/jornada**, **operacional** e **guardrail**, respectivamente):
+
+| Família | Significado | Exemplos |
+|---|---|---|
+| IC | evento de negócio/jornada do agente | `IC.GATEWAY_RECEIVED`, `IC.AGENT_STARTED/COMPLETED`, `IC.MCP_CACHE_HIT/MISS/SET/BYPASS/NOT_STORED`, `IC.MCP_TOOL_DEDUPED`, `IC.GLOBAL_BACKEND_SELECTED` |
+| NOC | erro/indisponibilidade/timeout/degradação | `NOC.RUNTIME_FAILED`, `NOC.MCP_TIMEOUT`, `NOC.LLM_FAILED` |
+| GRL | governança/guardrail/bloqueio/sanitização | `GRL.INPUT_BLOCKED`, `GRL.OUTPUT_BLOCKED`, `GRL.MASK_APPLIED` |
+
+Regra prática: não criar evento por linha de código — só para decisões relevantes.
+
+**Instrumentação híbrida**: spans técnicos automáticos por nó do grafo; chamadas LLM capturadas automaticamente via `ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=true` (providers compatíveis com OpenAI); eventos de negócio (IC/NOC/GRL) sempre manuais via `_emit_ic/_emit_noc/_emit_grl`, **fail-open** (observer ausente/com erro nunca quebra a jornada). Modo de trace `LANGFUSE_TRACE_MODE=verbose|compact`.
+
+**Prompt management**: **não usa** o CMS de prompts do Langfuse — versiona prompt localmente em YAML (`prompt_policy.yaml`, campos `id`/`version`). Langfuse entra como fonte de dados para avaliação em lote (`EvaluationRun.source=langfuse`, apps `evals/offline`/`evals/certification`), não como o motor de julgamento síncrono (esse é um nó do próprio grafo, usando profile LLM `judge`).
+
+**Setup local (docker-compose)**: `langfuse-web`, `langfuse-worker`, PostgreSQL, ClickHouse, Redis, MinIO, mais MongoDB (memória do framework, não do Langfuse). Portas: Web/API 3005, MinIO S3 9090/Console 9091, MongoDB 27017, Postgres 5433, Redis 6379, ClickHouse 8124/9002. Fluxo: `docker compose up -d` → criar org/projeto → gerar par de chaves `pk-lf-.../sk-lf-...` em Settings > API Keys → configurar `.env` do backend.
+
+---
+
+## 3. Padrão de integração MCP
+
+**MCP Gateway**: app deployável único — `/v1/tools`, `/v1/tools/{name}`, `/v1/tools/{name}/invoke`, `/v1/servers`, `/health`, `/ready`. Contratos `ToolInvocation`/`ToolResult` carregando `tenant_id`, `agent_id`, `business_context`, `metadata.request_id/trace_id`.
+
+**MCP Parameter Mapping** (`mcp_parameter_mapping.yaml`): traduz chaves canônicas de negócio (`customer_key`, `contract_key`, `session_key`) para o nome de parâmetro esperado por cada tool.
+
+**Cache MCP com eventos Langfuse**: chave `tenant_id:agent_id:tool_name:hash(arguments)`, só tools idempotentes, TTL por tool. Fluxo de eventos: miss → `IC.MCP_CACHE_MISS → IC.MCP_TOOL_EXECUTING → IC.MCP_TOOL_EXECUTED → IC.MCP_CACHE_SET`; hit → só `IC.MCP_CACHE_HIT`.
+
+**FastMCP** como padrão de servidor MCP oficial:
+```python
+from mcp.server.fastmcp import FastMCP
+mcp = FastMCP("telecom_mcp_server")
+
+@mcp.tool()
+def consultar_fatura(msisdn: str | None = None) -> dict: ...
+
+mcp.run(transport="streamable-http")
+```
+
+### ⚠️ Achado crítico: autorização rasa e potencialmente insegura
+
+O bloco `authorization` do MCP Gateway deles é um **allowlist estático por `agent_id`**:
+
+```yaml
+authorization:
+  default_policy: deny
+  agents:
+    telecom_contas:
+      allowed_tools: [consultar_fatura, consultar_pagamentos]
+```
+
+O campo `agent_id` que governa essa allowlist **chega como dado do payload de entrada da conversa** (`GatewayRequest`/`ToolInvocation`), não como claim de uma identidade de MCP Client autenticada e verificada independentemente. A própria SPEC-004 deles admite: *"a política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server."* Não há PDP/OPA/Cedar, não há `policy_decision_id`/`entitlement_version`, não há separação discovery/execution como dois enforcement points deliberadamente independentes.
+
+**Isto é estruturalmente o anti-padrão que o ADR-001 da nossa RI proíbe** ("autorização por role autodeclarado do agente"). Ver ADR-023 para a decisão de como reaproveitar a engenharia de proxy sem herdar esse problema.
+
+---
+
+## 4. Convenções de configuração YAML
+
+| Arquivo | Propósito |
+|---|---|
+| `agents.yaml` | Registro de agentes (agent_id, paths de config isolada, metadados de domínio) |
+| `routing.yaml` | Intents, keywords/examples/priority, `mcp_tools` por intent, `state_policies` |
+| `tools.yaml` | Catálogo de tools: server destino, schema de args, cache, `allowed_agents` |
+| `guardrails.yaml` | Guardrails de entrada/saída habilitáveis por código |
+| `judges.yaml` | Critérios de avaliação pós-resposta (deterministic/llm), threshold, sample_rate |
+| `llm_profiles.yaml` | Perfis de modelo/temperatura por componente (router, judge, supervisor, RAG) |
+| `identity.yaml` | Aliases de nomes de canal → chaves canônicas de negócio (Identity Resolver) |
+| `mcp_parameter_mapping.yaml` | Tradução de chave canônica → nome de parâmetro esperado por tool |
+| `mcp_servers.yaml` (+ `.docker.yaml`) | Endereços/transporte dos MCP servers (local vs. Docker) |
+| `backends.yaml` | Cadastro de backends de agente + regras de roteamento global do Agent Gateway |
+| `prompt_policy.yaml` | Prompt base/persistente do agente, versionado (`id`, `version`) |
+| `tool_policies.yaml` | Classifica tool como `read_only`/`transactional`, exige confirmação |
+| `authorization` (bloco em config do MCP Gateway) | Allowlist de tools por `agent_id` — **não reaproveitar como fonte de autorização** (ver seção 3) |
+
+---
+
+## 5. Modelo de segurança/identidade (SPEC-018) — compatibilidade
+
+- **Autenticação de workload** (5 modos: config_file/instance_principal/workload_identity/resource_principal/api_key) — trata de como o *framework* se autentica perante recursos OCI (Vault, GenAI, ADB). **Ortogonal** ao nosso problema de entitlement de tools.
+- **Autorização** — listada como 5 perguntas a responder, sem PDP formal; na prática resolvida pelo allowlist raso descrito na seção 3.
+- **Secrets, proteção de dados, segurança de canal** — compatíveis/complementares, não tocam em entitlement.
+- **Auditoria** — bom modelo de trilha (usuário/canal, agent_id, tenant_id, tool, modelo, guardrail, judge score, trace_id), mas sem equivalente a `decisionId`/`policyDecisionId`/`entitlementVersion` (nossos ADR-017), porque não existe PDP separado gerando essas decisões.
+
+**Onde é claramente compatível/ortogonal**: `identity.yaml`/`BusinessContext` — normalização de identidade de **negócio** (cliente final, contrato), nunca decide autorização de tool. Adotável sem tensão com o núcleo de segurança.
+
+**Veredito**: SPEC-018 não deve ser usada como spec de segurança normativa para a nossa RI — mistura autenticação de workload com autorização de tool sem separar os dois problemas nem propor um PDP.
+
+---
+
+## 6. Deployment
+
+Não é amarrado a OCI na camada de aplicação — roda 100% local via Docker Compose com serviços genéricos self-hostáveis (Redis, MongoDB, PostgreSQL, ClickHouse, MinIO, Langfuse). Integrações OCI (GenAI, ADB, Vault, workload identity) são opções plugáveis entre várias, não requisito de desenvolvimento.
+
+---
+
+## Recomendações de reuso (aplicadas na RI via ADR-022/ADR-023)
+
+**Adotar como estão** (não tocam no núcleo de segurança): `identity.yaml`/BusinessContext · taxonomia IC/NOC/GRL + EventEnvelope · setup local do Langfuse via docker-compose · `ConversationSummaryMemory` · heurística RAG-vs-MCP (§30.3-30.4 do Hoshikawa: sistemas → MCP, documentos → RAG) · `mcp_parameter_mapping.yaml` · FastMCP como padrão de servidor MCP.
+
+**Adotar com adaptação**: a *forma* de proxy do MCP Gateway (catálogo, `ToolInvocation`/`ToolResult`, cache com eventos, retry/timeout/circuit breaker) — mas a decisão ALLOW/DENY é sempre delegada ao nosso PEP/PDP, nunca ao bloco `authorization` deles. A camada Agent Gateway/Global Supervisor (dois níveis de sessão, handoff) informa o desenho de EP-11/EP-12, mantendo-a estritamente como roteamento de UX/negócio, nunca como autoridade de autorização. `tool_policies.yaml` (read_only/transactional + confirmação) é conveniência conversacional, não controle de segurança.
+
+**Não copiar como fonte de verdade de segurança**: o bloco `authorization` por `agent_id` autodeclarado no payload; SPEC-018 como normativa de autorização.