diff --git a/README.md b/README.md index 74c1413..d4eeac2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,23 @@ # Enterprise MCP Service Bus ## Reference Architecture para acesso agêntico governado por Client-Bound Entitlements -**Status:** Working Draft v0.1 -**Publicação:** 14 de agosto de 2026 -**Escopo:** Arquitetura corporativa para expor capacidades empresariais a agentes por meio de MCP, com um MCP Gateway atuando como Policy Enforcement Point (PEP) e com o MCP Client definindo o limite máximo de privilégio. +**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. + +### Novidades da v0.2 + +- governança de publicação/subscrição de capabilities por service owners e pipelines; +- Entitlement Manager como autoridade de cardápios MCP personalizados; +- Profile Intelligence com clusterização genérica, substituível e sem taxonomia proprietária; +- Offering Filter para intersectar catálogo, entitlement, perfil, consentimento e contexto; +- Service Orchestrator responsável pelo cálculo da NBA; +- Agent Runtime para dispatch, sessão, canais e handoff; +- rastreabilidade ponta a ponta entre perfil, entitlement, decisão, política, execução e outcome. --- @@ -20,6 +34,43 @@ O desenho tem quatro ideias centrais: 3. **O catálogo visível ao agente é uma projeção do entitlement do client.** Um `tools/list` deve devolver somente as tools permitidas àquele client. 4. **Informações controladas pelo agente podem reduzir acesso, mas nunca ampliá-lo.** Contexto, usuário, estado da conversa, RAG, resultados de tools e decisões do LLM não podem elevar o conjunto máximo de capabilities estabelecido para o MCP Client. +A arquitetura ampliada adiciona três ideias operacionais ao núcleo de segurança: + +5. **O Enterprise MCP Fabric é o eixo de publicação e subscrição de capabilities.** Service owners publicam produtos, serviços, benefícios, campanhas e operações uma vez; consumidores autorizados os descobrem e reutilizam por contratos governados. +6. **O Entitlement Manager produz cardápios MCP personalizados.** Ele cruza identidade autenticada, perfil de segurança do client/workload, políticas, risco e contexto para produzir o conjunto máximo e a visão efetiva de capabilities. +7. **O Service Orchestrator calcula a NBA.** Ele recebe contexto, identidade e limites derivados de perfil, entitlement e ofertas filtradas; combina estado de jornada, decisioning, regras e guardrails; e despacha a ação selecionada para agentes e canais. + +Essas responsabilidades formam um ciclo governado, sem transferir autorização para a camada probabilística: + +```text +service publication -> global catalog -> maximum entitlement -> filtered offerings + -> decision context -> NBA orchestration -> agent/channel execution + -> telemetry and traceability -> policy, catalog and model improvement +``` + +O contrato entre personalização e orquestração pode ser resumido como: + +```text +DecisionContext = ( + ProfileView, + AuthenticatedIdentity, + EntitlementLimits, + FilteredOfferings, + RuntimeContext +) + +NBA = Orchestrator( + DecisionContext, + JourneyState, + DecisioningModel, + Rules, + Guardrails, + Memory +) +``` + +`ProfileView` é produzido por um modelo **genérico e substituível** de segmentação ou clusterização, baseado em atributos de perfil, sinais comportamentais e contexto de jornada definidos pela organização. A arquitetura não pressupõe taxonomias, nomenclaturas de segmentos ou métodos proprietários de uma empresa específica. + A propriedade de segurança central pode ser expressa como: ```text @@ -175,6 +226,76 @@ Em um sistema tradicional, um endpoint não listado em uma UI ainda pode ser con - uma medida de melhoria de tool selection; - uma forma de governar capacidades corporativas. +### 3.3 Arquitetura de referência ampliada + +O E-MCP-BUS continua sendo a fronteira determinística e o barramento de capabilities. Ao seu redor, a arquitetura ampliada organiza quatro responsabilidades adicionais: oferta, personalização governada, orquestração e execução omnicanal. + +```mermaid +flowchart LR + subgraph Supply["OFERTA E GOVERNANÇA DE SERVIÇOS"] + Owners["Service owners"] + Pipeline["Publishing pipeline
schema • owner • risk • policy • version"] + Registry["Global Capability Registry"] + Owners --> Pipeline --> Registry + end + + subgraph Personalization["PERSONALIZAÇÃO GOVERNADA"] + Signals["Atributos de perfil
comportamento • jornada"] + Profiles["Profile Intelligence
segmentação / clusterização genérica"] + Entitlements["Entitlement Manager
maximum entitlement"] + Filter["Offering Filter
capabilities relevantes e elegíveis"] + Consent["Consentimento declarado
canal • contexto de runtime"] + DecisionContext["Decision Context
context + identity + limits"] + Signals --> Profiles --> DecisionContext + Entitlements --> Filter --> DecisionContext + Consent --> Filter + Consent --> DecisionContext + end + + subgraph Orchestration["ORQUESTRAÇÃO DE JORNADAS"] + Orchestrator["Journey & Agent Orchestrator
state • objective • NBA function"] + Decisioning["Decisioning model
rules • guardrails"] + Memory["State • memory
telemetry • traceability"] + Decisioning --> Orchestrator + Memory <--> Orchestrator + DecisionContext --> Orchestrator + end + + subgraph Runtime["AGENTES E CANAIS"] + AgentRuntime["Agent Runtime
context • session • handoff"] + Conversational["Conversational
app • web • messaging • voice"] + Proactive["Proactive
push • email • SMS"] + Media["Media and expansion
campaigns • ads • new agents"] + AgentRuntime --> Conversational + AgentRuntime --> Proactive + AgentRuntime --> Media + end + + subgraph Bus["ENTERPRISE MCP SERVICE BUS"] + Client["MCP Client
workload identity"] + Gateway["MCP Gateway / PEP
filtered discovery • enforcement"] + PDP["PDP / Policy Engine
entitlement • transaction"] + Fabric["Enterprise MCP Fabric
publish • subscribe • route • mediate • resolve"] + Client --> Gateway + Gateway <--> PDP + Gateway --> Fabric + end + + Registry --> Fabric + Registry --> Filter + PDP <--> Entitlements + Orchestrator -->|"NBA + agent dispatch"| AgentRuntime + Orchestrator --> Client + Fabric --> Systems["APIs • ESB • service mesh • functions • SaaS • data"] +``` + +O diagrama apresenta duas cadeias complementares: + +- **supply chain de capabilities:** service owner -> publishing pipeline -> registry -> fabric; +- **decision chain:** perfil + entitlement + ofertas filtradas -> decision context -> NBA -> agent/channel execution. + +O ponto de união é o contrato MCP governado. O Orchestrator consome apenas capabilities visíveis e executáveis para o MCP Client autenticado; o Gateway reautoriza cada chamada, mesmo que a NBA tenha sido produzida por um modelo ou regra aprovados. + --- ## 4. Princípios arquiteturais @@ -339,6 +460,30 @@ Regra recomendada: > **MCP exposes enterprise capabilities; it does not reimplement enterprise services.** +### P8. Relevância nunca amplia autorização + +Segmentação, clusterização, recomendação, ranking, propensity scores e decisioning podem ordenar ou reduzir o conjunto de candidatas. Eles não podem criar entitlement. + +```text +RankedCandidates(subject, context) ⊆ FilteredOfferings(subject, context) +FilteredOfferings(subject, context) ⊆ MaximumEntitlement(client) +``` + +Um cluster de perfil não é um security principal. Mudanças de cluster não concedem automaticamente acesso a novas capabilities; qualquer ampliação exige uma decisão explícita e auditável do Entitlement Manager/PDP. + +### P9. A NBA é decisão de orquestração, não decisão de autorização + +O Service Orchestrator calcula a Next Best Action combinando contexto de decisão, estado da jornada, modelo de decisioning, regras, guardrails e memória. O resultado pode selecionar uma capability, um agente, um canal e um instante de execução, mas permanece sujeito a: + +- filtered discovery; +- execution authorization; +- transaction policy; +- consentimento e limites de contato; +- human-in-the-loop quando aplicável; +- autorização final do backend. + +Uma NBA negada pelo PEP não é automaticamente substituída por execução direta ou bypass. O Orchestrator deve recalcular, degradar com segurança ou encerrar a jornada conforme política. + --- ## 5. Modelo de confiança @@ -418,14 +563,21 @@ Componente probabilístico responsável por: Responsável por: - executar ou coordenar agentes; -- manter contexto; +- receber o `DecisionContext` com perfil, identidade autenticada, limites e ofertas filtradas; +- manter estado de jornada, contexto e memória operacional; - gerenciar chamadas ao modelo; +- calcular a Next Best Action (NBA); +- combinar decisioning model, regras e guardrails; +- selecionar agente, canal e estratégia de handoff; - instanciar ou utilizar MCP Clients; - aplicar guardrails; -- implementar human-in-the-loop quando necessário. +- implementar human-in-the-loop quando necessário; +- emitir telemetria e trilha de decisão correlacionáveis com o PEP e o backend. 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. + --- ### 6.3 MCP Client @@ -559,6 +711,226 @@ Pode ser implementado como: - adapters para APIs existentes; - integração com ESB/API Management já existente. +Além do data plane, o Fabric oferece o ponto corporativo de **publicação e subscrição** de capabilities. Publicar significa registrar um contrato governado e resolvível; subscrever significa descobrir ou consumir uma projeção autorizada desse contrato. O Fabric não entrega o catálogo global indiscriminadamente a cada agente. + +--- + +### 6.8 Service owners e publishing pipelines + +Cada capability deve possuir um owner responsável por contrato, risco, política, qualidade operacional e ciclo de vida. A publicação deve ocorrer por pipeline, não por cadastro manual ad hoc em produção. + +Um pipeline de publicação deve validar pelo menos: + +- nome canônico, namespace e versão; +- descrição voltada a consumo agêntico; +- input/output schema; +- owner e domínio de negócio; +- classificação de risco e dados; +- side effects e idempotência; +- políticas de entitlement e transação; +- requirements de consentimento ou aprovação; +- adapter/backend e health checks; +- telemetria, SLOs, depreciação e rollback. + +```mermaid +flowchart LR + Owner["Service owner"] --> Manifest["Capability manifest"] + Manifest --> Pipeline["Publishing pipeline"] + Pipeline --> Schema["Schema and contract validation"] + Pipeline --> Risk["Risk and data classification"] + Pipeline --> Policy["Policy tests"] + Pipeline --> Ops["Health, SLO and telemetry checks"] + Schema --> Gate["Publication gate"] + Risk --> Gate + Policy --> Gate + Ops --> Gate + Gate -->|"approved"| Registry["Global Capability Registry"] + Registry --> Fabric["Enterprise MCP Fabric"] + Gate -->|"rejected"| Owner +``` + +Exemplo de manifesto mínimo: + +```yaml +apiVersion: enterprise.mcp/v1 +kind: Capability +metadata: + name: benefits.present + namespace: engagement + version: 1.2.0 + owner: customer-engagement +spec: + description: Present an eligible benefit to a customer in an approved channel + riskTier: medium + dataClassification: internal + sideEffects: none + idempotent: true + requiredEntitlements: + - engagement.benefits.read + transactionPolicy: + consentPurpose: personalization + allowedChannels: [app, web, email] + backend: + adapter: benefits-api + operation: GET /v2/benefits/{benefitId} + lifecycle: + status: active + sunsetAfter: 2027-09-01 +``` + +### 6.9 Entitlement Manager + +É o componente central de gestão de **cardápios MCP personalizados**. Ele materializa políticas em conjuntos de capabilities associados a identidades autenticadas de clients/workloads. + +Responsabilidades: + +- resolver `MaximumEntitlement(client)`; +- combinar perfis de segurança pré-aprovados para clients/workloads, políticas organizacionais, risco e contexto; +- produzir versões cacheáveis e revogáveis do cardápio; +- fornecer dados de decisão ao PDP; +- manter provenance: qual regra incluiu, restringiu ou removeu uma capability; +- invalidar projeções após revogação, mudança de risco ou alteração do catálogo. + +O Entitlement Manager é autoridade sobre o cardápio máximo. Ele não executa ranking de relevância, não calcula NBA e não confia em atributos autodeclarados pelo LLM. + +### 6.10 Profile Intelligence e clusterização genérica + +Profile Intelligence transforma atributos permitidos em uma visão de perfil utilizável por personalização e orquestração. A implementação pode usar regras, clustering não supervisionado, classificação supervisionada, embeddings ou uma combinação dessas técnicas. + +Fontes genéricas possíveis: + +- atributos de relacionamento e ciclo de vida; +- frequência, recência e intensidade de interação; +- afinidade por categorias de produtos ou serviços; +- histórico de respostas a jornadas; +- preferências declaradas; +- contexto temporal, geográfico ou de canal quando permitido; +- sinais de satisfação, propensão, churn ou necessidade de suporte. + +Requisitos de governança: + +- usar identificadores pseudonimizados quando possível; +- documentar features, finalidade, janela temporal e qualidade; +- evitar atributos sensíveis ou proxies sem base legal e revisão apropriada; +- versionar modelos e definições de segmentos; +- monitorar drift, estabilidade e impacto desigual; +- permitir explicações por `reason codes`; +- garantir que o resultado reduza ou ordene candidatas, nunca amplie entitlement. + +Consentimento não deve ser inferido por clusterização. Ele entra como atributo determinístico no Offering Filter, nos guardrails de decisão e na autorização transacional. + +Exemplo de saída genérica: + +```json +{ + "subjectRef": "subject:7f31c2", + "profileVersion": "profile-model-3.4", + "segments": [ + {"id": "low-engagement", "score": 0.86}, + {"id": "digital-preference", "score": 0.73} + ], + "attributes": { + "relationshipStage": "activation", + "preferredChannels": ["app", "email"], + "engagementBand": "low" + }, + "reasonCodes": ["LOW_RECENCY", "APP_AFFINITY"], + "expiresAt": "2026-09-04T12:00:00Z" +} +``` + +Os nomes acima são ilustrativos. A arquitetura não prescreve taxonomia, algoritmo, número de clusters ou atributos específicos. + +### 6.11 Offering Filter + +Produz o conjunto de capabilities e ofertas simultaneamente disponíveis, elegíveis e relevantes para o contexto corrente. Opera depois do teto de entitlement e antes do ranking da NBA. + +```text +FilteredOfferings(subject, client, context) + = ActiveCatalog + ∩ MaximumEntitlement(client) + ∩ SubjectAndContextConstraints(subject, context) +``` + +O filtro pode considerar disponibilidade, região, canal, consentimento, horário, estoque, compatibilidade, frequency caps e restrições transacionais. Uma oferta ausente do maximum entitlement nunca pode ser reintroduzida por score de perfil. + +### 6.12 Service Orchestrator + +Coordena jornadas e agentes sobre um universo previamente permitido e relevante. Seu contrato de entrada é um `DecisionContext`; sua principal saída é uma NBA acompanhada das informações necessárias ao dispatch. + +```mermaid +flowchart LR + subgraph HP["GOVERNED PERSONALIZATION"] + Profile["Profile view"] + Entitlement["Entitlement limits"] + Offerings["Filtered offerings"] + Context["Runtime context
identity • consent • channel"] + DC["Decision Context
context + identity + limits"] + Profile --> DC + Entitlement --> DC + Offerings --> DC + Context --> DC + end + + subgraph ORCH["SERVICE ORCHESTRATOR"] + Journey["Journey & Agent Orchestrator
state • objective • NBA function"] + Model["Decisioning model
rules • guardrails"] + State["State • memory
telemetry • traceability"] + DC --> Journey + Model --> Journey + State <--> Journey + end + + subgraph CHANNELS["AGENTS AND CHANNELS"] + Runtime["Agent Runtime
context • session • handoff"] + Chat["Conversational"] + Push["Proactive"] + Media["Media / campaigns"] + Journey -->|"NBA + agent dispatch"| Runtime + Runtime --> Chat + Runtime --> Push + Runtime --> Media + end +``` + +Responsabilidades: + +- manter estado e objetivo da jornada; +- calcular NBA com função de decisão versionada; +- aplicar regras de canal, frequência, consentimento, timing e pressão de contato; +- coordenar múltiplos agentes sem perder contexto; +- decidir handoff entre agentes ou para atendimento humano; +- correlacionar decisão, chamada MCP, execução e resultado; +- recalcular ou degradar com segurança quando uma ação for negada ou indisponível. + +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. + +### 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. + +Uma saída de dispatch pode ter a forma: + +```json +{ + "decisionId": "dec-01J7A6N3", + "action": "benefits.present", + "capabilityVersion": "1.2.0", + "subjectRef": "subject:7f31c2", + "channel": "app", + "agent": "engagement-assistant", + "reasonCodes": ["ELIGIBLE", "ACTIVATION_OBJECTIVE", "FREQUENCY_OK"], + "policyContext": { + "entitlementVersion": "ent-2026-09-03-17", + "consentPurpose": "personalization", + "maxContactsPerWeek": 2 + }, + "expiresAt": "2026-09-03T18:00:00Z" +} +``` + +Esse objeto representa intenção de execução. Ele não substitui o token do MCP Client nem a autorização determinística realizada pelo Gateway/PEP. + --- ## 7. Modelo de entitlement @@ -635,6 +1007,48 @@ Essa segmentação cria **blast-radius domains**. O objetivo não é necessariamente criar um client por agente, mas um client por **perfil máximo de privilégio aceitável**. +### 7.3 Do catálogo global ao cardápio personalizado + +A arquitetura distingue quatro conjuntos que não devem ser confundidos: + +| Conjunto | Pergunta respondida | Autoridade | +|---|---|---| +| `GlobalCatalog` | O que foi publicado e está operacionalmente disponível? | Registry + Fabric | +| `MaximumEntitlement` | Qual é o teto de capabilities deste MCP Client? | Entitlement Manager + PDP | +| `FilteredOfferings` | O que é permitido e aplicável ao subject/contexto atual? | Offering Filter sob política | +| `RankedCandidates` | Qual candidata é mais relevante para o objetivo da jornada? | Service Orchestrator | + +```mermaid +flowchart LR + Global["GlobalCatalog
todas as capabilities publicadas"] + Max["MaximumEntitlement
teto do MCP Client"] + Filtered["FilteredOfferings
permitidas + aplicáveis"] + Ranked["RankedCandidates
ordenadas por relevância"] + NBA["NBA
ação selecionada"] + + Identity["Authenticated workload identity"] --> Max + Policies["Entitlement policies"] --> Max + Global --> Max + + Subject["Subject attributes + consent"] --> Filtered + Runtime["Runtime context"] --> Filtered + Max --> Filtered + + Profile["Generic profile view"] --> Ranked + Journey["Journey state + objective"] --> Ranked + Filtered --> Ranked --> NBA +``` + +As relações de subconjunto são invariantes: + +```text +MaximumEntitlement(client) ⊆ GlobalCatalog +FilteredOfferings(subject, client, context) ⊆ MaximumEntitlement(client) +RankedCandidates(subject, client, context) ⊆ FilteredOfferings(subject, client, context) +``` + +Ranking altera ordem e prioridade; não altera autorização. + --- ## 8. Client-Bound Capability View @@ -758,6 +1172,67 @@ sequenceDiagram end ``` +### 10.1 Fluxo orquestrado de decisão e execução + +O fluxo a seguir conecta profile intelligence, entitlement, filtered offerings, cálculo da NBA e execução MCP sem fundir suas autoridades. + +```mermaid +sequenceDiagram + autonumber + participant X as Runtime Context + participant PI as Profile Intelligence + participant EM as Entitlement Manager + participant OF as Offering Filter + participant O as Service Orchestrator + participant AR as Agent Runtime + participant C as MCP Client + participant G as MCP Gateway / PEP + participant P as PDP + participant F as MCP Fabric + participant B as Backend + + X->>O: event + subjectRef + channel + consent + O->>PI: resolveProfile(subjectRef, context) + PI-->>O: versioned profile view + reason codes + O->>EM: resolveMaximumEntitlement(client identity) + EM-->>O: entitlement version + limits + O->>OF: filter(profile, entitlement, context) + OF-->>O: filtered offerings + O->>O: NBA = decisioning(state, objective, rules, guardrails) + O->>O: persist decision trace + O->>AR: NBA + agent dispatch + AR->>C: tools/call(capability, arguments) + C->>G: authenticated MCP request + G->>P: entitlement + transaction authorization + P-->>G: ALLOW / DENY / REQUIRE_APPROVAL + + alt ALLOW + G->>F: invoke authorized capability + F->>B: call with appropriate downstream identity + B-->>F: result + F-->>G: result + correlation + G-->>C: tool result + C-->>AR: execution result + AR-->>O: outcome + telemetry + O->>O: update state and memory + else DENY or unavailable + G-->>C: deterministic denial + C-->>AR: denied + decision reference + AR-->>O: failure + correlation id + O->>O: recalculate, safe fallback or stop + end +``` + +Exemplo genérico: + +1. Um evento de ativação chega com identidade pseudonimizada, canal atual e consentimento. +2. Profile Intelligence classifica o subject como `low-engagement` e `digital-preference`. +3. O Entitlement Manager permite apenas capabilities de consulta e apresentação de benefícios; operações de compra não pertencem ao cardápio. +4. O Offering Filter remove itens expirados, indisponíveis no canal ou incompatíveis com consentimento e frequency cap. +5. O Orchestrator escolhe `benefits.present` como NBA e despacha um agente conversacional no app. +6. O Gateway reautoriza `tools/call`; a decisão do Orchestrator, isoladamente, não concede execução. +7. Resultado e reason codes atualizam estado, memória, telemetria e trilha de auditoria. + --- ## 11. Discovery authorization versus execution authorization @@ -1418,6 +1893,13 @@ catalog_changed | Excessive privilege | omnibus client com centenas de writes | segmentation by domain/risk | | Policy drift | entitlement antigo permanece em cache | policy version + invalidation | | Backend over-trust | backend confia apenas no gateway | backend resource authorization | +| Profile poisoning | eventos manipulados alteram cluster ou score | source validation + feature lineage + anomaly detection | +| Profile drift | modelo deixa de representar o comportamento atual | versioning + drift monitoring + expiry | +| Sensitive attribute leakage | perfil expõe atributo ou proxy indevido | data minimization + purpose limitation + review | +| Decision manipulation | prompt ou tool output tenta forçar uma NBA | constrained decision context + rules + guardrails | +| Consent/frequency bypass | jornada insiste em canal ou contato bloqueado | deterministic channel policy + frequency caps | +| Stale decision replay | dispatch antigo é executado após revogação | short expiry + idempotency + reauthorization | +| Traceability gap | decisão não pode ser ligada à execução | end-to-end correlation ids + immutable audit trail | --- @@ -1725,6 +2207,34 @@ A plataforma deve suportar credenciais apropriadas ao backend sem blind token pa Tools de alto risco devem suportar aprovação adicional quando requerido. +### RF-11 — Governed publication + +Capabilities devem ser publicadas por pipeline com validação de contrato, owner, risco, políticas, versão, saúde e observabilidade. + +### RF-12 — Personalized MCP menu + +O Entitlement Manager deve produzir cardápios versionados, explicáveis, cacheáveis e revogáveis por identidade autenticada de client/workload. + +### RF-13 — Generic profile view + +Profile Intelligence deve expor um contrato genérico e substituível de atributos, segmentos ou scores, incluindo versão, expiração e reason codes. + +### RF-14 — Safe offering filtering + +O Offering Filter deve garantir que nenhuma candidata fora do Maximum Entitlement seja introduzida por perfil, cluster, score ou contexto. + +### RF-15 — NBA orchestration + +O Service Orchestrator deve calcular e registrar a NBA a partir de Decision Context, estado, objetivo, modelo, regras, guardrails e memória. + +### RF-16 — Agent dispatch and handoff + +O Agent Runtime deve suportar dispatch, sessão, correlação e handoff entre agentes, canais e atendimento humano quando aplicável. + +### RF-17 — End-to-end correlation + +Cada jornada deve correlacionar `profileVersion`, `entitlementVersion`, `decisionId`, `policyDecisionId`, `mcpRequestId`, execução downstream e outcome. + --- ## 37. Requisitos não funcionais @@ -2109,7 +2619,20 @@ Adicionar: - federation; - lifecycle automation. -### Fase 4 — Enterprise scale +### Fase 4 — Personalização e orquestração governadas + +Adicionar: + +- schema genérico e versionado de `ProfileView`; +- Entitlement Manager e cardápios personalizados; +- Offering Filter com consentimento, contexto e frequency caps; +- contrato versionado de `DecisionContext`; +- Service Orchestrator com NBA function, regras e guardrails; +- Agent Runtime e adapters para canais selecionados; +- correlação entre decisão, dispatch, chamada MCP e outcome; +- testes que comprovem que perfil, score e cluster não ampliam entitlement. + +### Fase 5 — Enterprise scale Adicionar: @@ -2179,6 +2702,13 @@ ADR-007: Gateway Bypass Prevention ADR-008: Client Segmentation by Domain and Risk ADR-009: Tool Risk Classification ADR-010: Global Capability Registry Governance +ADR-011: Capability Publication and Subscription Lifecycle +ADR-012: Entitlement Manager as Personalized MCP Menu Authority +ADR-013: Generic and Replaceable Profile Intelligence Contract +ADR-014: Profile Relevance Cannot Expand Entitlement +ADR-015: Service Orchestrator Owns NBA, Not Authorization +ADR-016: Agent Runtime Dispatch and Handoff Contract +ADR-017: End-to-End Decision and Execution Correlation ``` --- @@ -2246,10 +2776,105 @@ A compromised client must have a predictable blast radius. Every security decision must be deterministic and auditable. ``` +### Axiom 11 + +```text +Profile intelligence may rank or reduce candidates; it must never grant capabilities. +``` + +### Axiom 12 + +```text +An NBA is an orchestration intent, not an authorization decision. +``` + +### Axiom 13 + +```text +Capabilities are published once and reused only through governed subscription and enforcement. +``` + --- ## 51. Visão consolidada +### 51.1 Visão lógica ampliada + +```mermaid +flowchart TB + subgraph Supply["CAPABILITY SUPPLY"] + SO["Service owners"] --> PP["Publishing pipelines"] --> GCR["Global Capability Registry"] + end + + subgraph Personalization["GOVERNED PERSONALIZATION"] + Attr["Generic profile attributes
behavior • journey • preferences"] + PI["Profile Intelligence
versioned segments / scores"] + EM["Entitlement Manager
personalized MCP menus"] + OF["Offering Filter
eligible + contextual candidates"] + CTX["Declared consent
channel • runtime context"] + DC["Decision Context
profile • identity • limits • offerings • context"] + + Attr --> PI --> DC + EM --> OF --> DC + CTX --> OF + CTX --> DC + end + + subgraph Journey["JOURNEY AND AGENT ORCHESTRATION"] + O["Service Orchestrator
state • objective • NBA function"] + DM["Decisioning model
rules • guardrails"] + MT["State • memory
telemetry • traceability"] + DC --> O + DM --> O + MT <--> O + end + + subgraph Experience["AGENTS AND CHANNELS"] + AR["Agent Runtime
context • session • handoff"] + CA["Conversational agents"] + PA["Proactive agents"] + MA["Media, campaigns and extensions"] + O -->|"NBA + agent dispatch"| AR + AR --> CA + AR --> PA + AR --> MA + end + + subgraph EMCB["ENTERPRISE MCP SERVICE BUS"] + MC["MCP Client
authenticated workload identity"] + PEP["MCP Gateway / PEP
filtered discovery + enforcement"] + PDP2["PDP / Policy Engine
entitlement + transaction"] + REG["Capability registry view"] + AUD["Correlated audit"] + FAB["Enterprise MCP Fabric
publish • subscribe • route • mediate • resolve"] + + MC --> PEP + PEP <--> PDP2 + REG --> PEP + PEP --> AUD + PDP2 --> AUD + PEP --> FAB + end + + GCR --> REG + GCR --> FAB + GCR --> OF + PDP2 <--> EM + O --> MC + FAB --> Existing2["API Gateway • ESB • service mesh • functions • SaaS"] + Existing2 --> Records["ERP • CRM • data platforms • legacy • partner ecosystem"] + AR --> MT + AUD --> MT +``` + +Esta visão evidencia três separações essenciais: + +- **Registry/Fabric publicam e resolvem** capabilities; Entitlement Manager personaliza o que cada client pode consumir. +- **Profile Intelligence e Offering Filter qualificam candidatas**; Service Orchestrator calcula a NBA. +- **Agent Runtime executa a jornada**; MCP Gateway/PDP e backend continuam como autoridades determinísticas. + +### 51.2 Núcleo técnico e fronteiras de confiança + ```mermaid flowchart TB subgraph Agentic["UNTRUSTED / AGENTIC"] @@ -2347,26 +2972,35 @@ O MCP Gateway atua como PEP e garante que: - o backend mantenha sua própria fronteira de autorização; - um comprometimento seja contido pelo blast radius do client. -O MCP Fabric, por sua vez, cumpre papel semelhante ao de um **Enterprise Service Bus semântico para agentes**: resolve capabilities em serviços corporativos existentes, preservando governança, isolamento e integração com a infraestrutura enterprise já estabelecida. +O MCP Fabric, por sua vez, cumpre papel semelhante ao de um **Enterprise Service Bus semântico para agentes**: centraliza publicação, subscrição e resolução de capabilities sobre serviços corporativos existentes, preservando governança, isolamento e integração com a infraestrutura enterprise já estabelecida. + +Ao redor desse núcleo: + +- Profile Intelligence produz uma visão genérica, versionada e explicável do perfil; +- o Entitlement Manager governa cardápios MCP personalizados; +- o Offering Filter restringe o universo a candidatas permitidas e aplicáveis; +- o Service Orchestrator calcula a NBA dentro desse universo; +- o Agent Runtime coordena execução, sessão, canal e handoff; +- telemetria e traceability fecham o ciclo sem transformar observação em privilégio. A combinação pode ser resumida como: ```text -Agentic Experience - ↓ -MCP Client - ↓ -Client-Bound Maximum Entitlement - ↓ -MCP Gateway / PEP - ↔ -PDP / Policy Engine - ↓ -Enterprise MCP Fabric - ↓ -Existing APIs / ESB / Functions / Services - ↓ -Systems of Record +CAPABILITY SUPPLY +Service owners -> Publishing pipelines -> Global Capability Registry + -> Enterprise MCP Fabric -> Enterprise services + +DECISION AND EXECUTION +Generic Profile View +Authenticated Identity -> Entitlement Manager -> Maximum Entitlement +Runtime Context + Consent + -> Filtered Offerings + -> Decision Context = profile + identity + limits + context + -> Service Orchestrator = state + objective + NBA + -> NBA + agent dispatch + -> Agent Runtime and Channels + -> MCP Client -> MCP Gateway / PEP <-> PDP / Policy Engine + -> Enterprise MCP Fabric ``` O resultado desejado não é tornar o agente "confiável". @@ -2414,7 +3048,28 @@ Catálogo administrativo completo de capabilities governadas. Catálogo MCP filtrado de acordo com o entitlement do client autenticado. **Enterprise MCP Fabric** -Camada de integração que resolve tools MCP em serviços, APIs, funções e sistemas corporativos. +Camada de integração que suporta publicação, subscrição e resolução de tools MCP em serviços, APIs, funções e sistemas corporativos. + +**Entitlement Manager** +Componente que resolve, versiona e revoga o Maximum Entitlement e os cardápios MCP personalizados associados a clients/workloads autenticados. + +**Profile Intelligence** +Capacidade substituível que deriva segmentos, clusters, scores ou atributos de perfil a partir de dados genericamente definidos e governados. Seu resultado informa relevância, não concede autorização. + +**Offering Filter** +Componente que intersecta catálogo ativo, entitlement, restrições do subject e contexto para produzir capabilities ou ofertas elegíveis para decisão. + +**Decision Context** +Envelope versionado contendo profile view, identidade autenticada, limites de entitlement, ofertas filtradas e contexto de runtime fornecidos ao Service Orchestrator. + +**Service Orchestrator** +Componente que coordena estado e objetivo da jornada, combina modelo de decisioning, regras, guardrails e memória e calcula a Next Best Action. + +**Next Best Action — NBA** +Ação escolhida pelo Orchestrator para um contexto e objetivo de jornada. Pode indicar capability, agente, canal e timing, mas não constitui autorização de execução. + +**Agent Runtime** +Camada que executa ou coordena agentes e channel adapters a partir de um dispatch, mantendo sessão, contexto mínimo, handoff e telemetria. **Blast Radius** Impacto máximo esperado em caso de comprometimento de uma identidade ou componente.