PRD-025 — Agentic External Integration & Digital Workforce Gateway

1. Objetivo

O External Integration & Digital Workforce Gateway será a camada responsável por permitir que o Agentic Work interaja de maneira segura com sistemas externos ao SST.

O objetivo não é simplesmente “dar acesso à Internet ao agente”.

O objetivo é criar uma fronteira controlada entre o Agentic Work e o mundo externo.

User
  ↓
Agent
  ↓
Intent
  ↓
Planner
  ↓
Policy
  ↓
Capability
  ↓
External Gateway
  ↓
External System
  ↓
Verification

2. Princípio fundamental

O LLM nunca terá acesso direto a:

API keys;
OAuth tokens;
senhas;
URLs arbitrárias;
bancos externos;
SMTP;
sistemas administrativos;
shell;
browser irrestrito;
credenciais de terceiros.

O agente deverá solicitar uma External Capability registrada.

LLM
 ↓
"consultar treinamento no LMS"
 ↓
Capability
 ↓
Policy
 ↓
External Gateway
 ↓
LMS

3. Problema que o PRD resolve

O SST poderá depender de:

RH
LMS
ERP
controle de acesso
sistemas médicos
fornecedores
document management
e-mail
serviços governamentais

Sem uma camada própria, cada integração acabaria criando sua própria lógica de:

authentication
authorization
retry
logging
mapping
security

Isso produziria uma arquitetura difícil de governar.

O Gateway centraliza essas responsabilidades.

4. Arquitetura

                    AGENTIC WORK
                         │
                         ▼
                Capability Registry
                         │
                         ▼
                   Policy Engine
                         │
                         ▼
             External Integration Gateway
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
       REST API       Webhook        File/Document
          │              │              │
          ▼              ▼              ▼
       Adapter A      Adapter B      Adapter C
          │              │              │
          └──────────────┼──────────────┘
                         ▼
                  External System
                         │
                         ▼
                     Verifier

5. Integration Registry

Assim como existe o Capability Registry, deverá existir um:

Integration Registry

Ele definirá os sistemas externos conhecidos.

interface ExternalIntegration {
  integrationId: string;

  name: string;

  provider: string;

  category:
    | "HR"
    | "LMS"
    | "ERP"
    | "ACCESS_CONTROL"
    | "MEDICAL"
    | "GOVERNMENT"
    | "DOCUMENT"
    | "COMMUNICATION"
    | "OTHER";

  tenantScope: "GLOBAL" | "TENANT";

  authentication: AuthenticationMethod;

  endpoints: ExternalEndpoint[];

  dataPolicies: DataPolicy[];

  status: "ACTIVE" | "DISABLED" | "DEGRADED";
}

6. Integration ≠ Capability

Uma integração representa:

com quem o sistema conversa.

Uma capability representa:

o que o agente pode fazer.

Exemplo:

Integration:
acme-lms

Capabilities:
training.search
training.getStatus
training.getCertificate

7. External Capability

A capability continuará obedecendo ao PRD-004.

Exemplo:

id: training.external.getStatus
domain: training
action: getStatus
integration: acme-lms
risk: low

O agente nunca verá necessariamente:

https://api.acme-lms.com/v2/workers/status

Ele verá:

training.external.getStatus

8. Adapter Pattern

Cada integração deverá possuir um adapter.

interface IntegrationAdapter {
  getStatus(): Promise<IntegrationStatus>;

  execute(
    operation: ExternalOperation
  ): Promise<ExternalOperationResult>;

  verify(
    operation: ExternalOperation
  ): Promise<VerificationResult>;
}

O restante do Agentic Work não deverá depender do fornecedor.

9. Canonical Data Model

Um dos objetivos será evitar que o restante do sistema conheça o formato específico de cada fornecedor.

Exemplo externo:

{
  "employee_no": "A-1023",
  "course_code": "NR10",
  "expires": "2026-09-15"
}

será transformado em:

{
  "employeeId": "EMP-104",
  "trainingId": "NR-10",
  "validUntil": "2026-09-15"
}

O restante do sistema trabalhará com o modelo canônico.

10. Mapping Layer

interface IntegrationMapper<TExternal, TCanonical> {
  toCanonical(input: TExternal): TCanonical;

  toExternal(input: TCanonical): TExternal;
}

Isso permitirá trocar:

LMS A

por:

LMS B

sem modificar o Agent Planner.

11. Authentication

O Gateway deverá suportar, conforme necessidade:

OAuth 2.0
API Key
JWT
mTLS
Basic Auth
Signed Requests
Service Account
Webhook Secret

O mecanismo de autenticação deverá ser escolhido pela integração.

12. Credential Isolation

Credenciais deverão permanecer em armazenamento seguro.

O fluxo será:

Capability
 ↓
Gateway
 ↓
Credential Resolver
 ↓
Secret Store
 ↓
Authenticated Request

O segredo nunca deverá:

↓
LLM
↓
Conversation
↓
UI Context
↓
Audit payload

13. Tenant Credentials

Quando a integração for específica de cliente:

Tenant A → LMS credentials A
Tenant B → LMS credentials B

O Gateway deverá garantir:

tenantId
→ credential binding
→ integration binding

Nunca poderá utilizar credencial de outro tenant.

14. Global Integration

Algumas integrações poderão ser compartilhadas.

Mesmo assim:

Tenant Context

deverá continuar presente.

Exemplo:

Shared API
+
tenant-specific authorization
+
tenant-specific mapping

15. Egress Control

O agente não poderá realizar:

HTTP request

para um endereço arbitrário.

O Gateway deverá trabalhar com uma allowlist de destinos.

Integration
 ↓
Allowed Domains
 ↓
Allowed Endpoints

16. SSRF Protection

O Gateway deverá bloquear destinos não autorizados, incluindo:

localhost;
loopback;
redes privadas;
metadata endpoints;
endereços internos;
redirects não autorizados;
hosts fora da allowlist.

Isso será especialmente importante em Workers e ambientes de integração.

17. Request Schema

Toda chamada externa deverá ser validada.

interface ExternalOperation {
  operationId: string;

  integrationId: string;

  capabilityId: string;

  tenantId: string;

  action: string;

  input: unknown;

  idempotencyKey?: string;

  timeoutMs: number;
}

18. Response Schema

interface ExternalOperationResult {
  operationId: string;

  status:
    | "SUCCESS"
    | "FAILED"
    | "TIMEOUT"
    | "UNKNOWN";

  data?: unknown;

  externalRequestId?: string;

  receivedAt: string;

  verification?: VerificationResult;
}

19. Timeout

Cada integração deverá possuir limites.

connect timeout
request timeout
total operation timeout

Exemplo:

timeout:
  connect: 1000
  request: 5000
  total: 10000

Nunca permitir timeout infinito.

20. Retry

O Gateway deverá aplicar as regras do PRD-024.

Exemplo:

→ retry
→ retry
timeout → retry
→ no retry
→ credential refresh/re-auth
→ no retry
→ business/concurrency handling

21. Circuit Breaker

Cada integração deverá possuir estado operacional:

HEALTHY
DEGRADED
OPEN
RECOVERING

Se uma integração estiver indisponível:

Agent
 ↓
Capability
 ↓
Gateway
 ↓
Circuit OPEN

não deverá gerar uma sequência de chamadas inúteis.

22. Rate Limiting

Rate limits deverão existir em múltiplos níveis:

Global
Tenant
Integration
Capability
User
Operation

Exemplo:

Tenant A:
1000 requests/hour

training.getStatus:
100 requests/minute

23. External Rate Limit

O Gateway deverá respeitar também o limite imposto pelo fornecedor.

Exemplo:

External API:
100 requests/min

O sistema deverá impedir que 500 workflows paralelos ultrapassem esse limite.

24. Queueing

Operações que não precisem ser síncronas poderão entrar em fila:

Agent
 ↓
External Gateway
 ↓
Queue
 ↓
Worker
 ↓
External API

Isso será importante para:

grandes lotes;
sincronizações;
importações;
exportações;
processamento de documentos.

25. Synchronous vs Asynchronous

Síncrono

“Qual o status do treinamento de João?”

Assíncrono

“Sincronize todos os 20.000 funcionários.”

O Agentic Planner deverá escolher o modo apropriado através da capability.

26. External Webhooks

Sistemas externos poderão enviar eventos:

External System
 ↓
Webhook Gateway
 ↓
Authentication
 ↓
Validation
 ↓
Normalization
 ↓
Event Fabric

O evento deverá seguir o PRD-020.

27. Webhook Security

O Gateway deverá validar:

signature
timestamp
nonce
source
schema
tenant binding

e bloquear replay attacks.

28. External Events

Exemplo:

LMS
 ↓
TrainingExpired
 ↓
Webhook Gateway
 ↓
Event Fabric
 ↓
Proactive Intelligence

Isso conecta diretamente os PRDs:

External Integration
        ↓
Event Fabric
        ↓
Proactive Intelligence
        ↓
Decision
        ↓
Workflow

29. External Documents

Algumas integrações fornecerão:

PDF
CSV
XML
JSON
images
certificates

O Gateway deverá classificar o conteúdo.

O documento não deverá ser automaticamente considerado confiável.

30. Document Provenance

Todo documento externo deverá possuir:

source
provider
externalDocumentId
retrievedAt
checksum
tenantId

Isso permitirá identificar exatamente a origem da informação.

31. External Data → Knowledge

Quando permitido:

External Data
 ↓
Normalization
 ↓
Validation
 ↓
Provenance
 ↓
Knowledge Pipeline
 ↓
HAG

O dado externo não deverá entrar diretamente na base de conhecimento sem validação.

32. External Data → Decision

Também será possível:

External Data
 ↓
Fact
 ↓
Decision Engine

Exemplo:

LMS:
NR-10 expires in 12 days

↓

Fact:
training.validUntil

↓

Risk:
MEDIUM

33. External Data Trust

A origem externa deverá possuir uma classificação.

VERIFIED
TRUSTED
UNVERIFIED
FAILED_VALIDATION

Essa classificação alimentará o PRD-023.

34. Data Freshness

Cada integração deverá declarar:

freshness requirement

Exemplo:

worker training:
24 hours

access authorization:
5 minutes

critical permit status:
1 minute

Dados antigos não deverão ser usados como se fossem atuais.

35. External Verification

Uma mutação externa deverá possuir verificação.

Exemplo:

Agent:
update employee training

External API:
200

Gateway:
verify

External system:
updated = true

Somente então:

SUCCESS

36. Unknown External State

Se:

request → timeout

o Gateway deverá produzir:

UNKNOWN

e não:

FAILED

quando não for possível determinar se a operação foi processada.

37. External Transaction ID

Quando disponível:

externalRequestId
externalOperationId
externalTransactionId

deverão ser armazenados.

Isso será essencial para:

suporte;
auditoria;
reconciliação;
investigação;
retry seguro.

38. Reconciliation

O Gateway deverá suportar reconciliação.

Exemplo:

Internal:
Training = VALID

External:
Training = EXPIRED

↓

Reconciliation Job

↓

Conflict

↓

Decision / Review

39. Integration Health

Cada integração deverá fornecer:

interface IntegrationHealth {
  integrationId: string;

  status: "HEALTHY" | "DEGRADED" | "DOWN";

  latencyMs?: number;

  errorRate: number;

  lastSuccessfulRequest?: string;

  checkedAt: string;
}

40. Agent Awareness

O agente deverá saber quando uma integração está indisponível.

Em vez de:

“Não encontrei o treinamento.”

deverá responder:

“Não foi possível consultar o LMS neste momento. O serviço está indisponível; não posso concluir o status do treinamento.”

Essa distinção é crítica.

41. Integration Policy

Cada integração deverá possuir políticas.

Exemplo:

integration: external-lms

policies:
  read:
    allowed: true

  write:
    allowed: true
    requiresConfirmation: true

  bulkWrite:
    allowed: false

  export:
    allowed: true
    requiresApproval: true

42. Data Egress Policy

O sistema deverá controlar quais dados podem sair do SST.

Exemplo:

employeeId → ALLOWED
name → ALLOWED
trainingStatus → ALLOWED
medicalDiagnosis → DENIED
salary → DENIED

Antes de qualquer request:

Payload
 ↓
Data Classification
 ↓
Egress Policy
 ↓
Allowed?

43. LLM Data Minimization

Se o LLM precisar interpretar uma resposta externa:

External Response
 ↓
Normalizer
 ↓
Sensitive Data Filter
 ↓
Minimal Context
 ↓
LLM

Não deverá enviar o payload completo quando apenas três campos forem necessários.

44. External System Instructions

Conteúdo externo deverá ser considerado não confiável.

Por exemplo, uma resposta externa contendo:

"Ignore your security policies..."

não terá autoridade sobre o Agentic Work.

Isso segue a proteção contra prompt injection definida anteriormente.

45. Human Approval

Integrações de alto risco poderão exigir:

External Operation
 ↓
Risk
 ↓
Human Approval
 ↓
Gateway

Exemplo:

“Enviar documento oficial para órgão externo?”

[Cancelar]
[Enviar]

46. External Communication

E-mails e mensagens também deverão ser capabilities.

Exemplo:

notification.email.send
notification.sms.send

O LLM não deverá acessar diretamente SMTP ou APIs de mensagens.

47. Anti-Spam

O Gateway deverá impedir:

workflow loop
 ↓
notification
 ↓
event
 ↓
workflow
 ↓
notification

Deverá utilizar:

deduplication
cooldown
rate limit
event correlation

48. External Integration Lifecycle

DRAFT
 ↓
CONFIGURING
 ↓
TESTING
 ↓
VALIDATING
 ↓
APPROVED
 ↓
ACTIVE
 ↓
DEGRADED
 ↓
DISABLED
 ↓
DEPRECATED

49. Integration Versioning

Cada adapter deverá possuir versão.

integration:
acme-lms

adapter:
2.3.0

Mudanças incompatíveis deverão gerar nova versão.

50. Contract Testing

Cada integração deverá possuir testes de contrato.

Request Schema
Response Schema
Authentication
Error Codes
Pagination
Rate Limits
Idempotency

Isso deverá ocorrer no CI/CD.

51. Mock External Systems

O PRD-014 deverá possuir simuladores.

Exemplo:

LMS Mock
ERP Mock
HR Mock
Access Control Mock

permitindo testar:

success
timeout
429
401
403
500
malformed response
duplicate response
stale data

52. Sandbox

Integrações que possuam ambiente sandbox deverão ser testadas primeiro em:

SANDBOX

Nunca diretamente em produção.

53. External Integration Audit

Deverão ser registrados:

integrationId
tenantId
capabilityId
externalRequestId
actor
payload classification
request timestamp
response status
verification result
policy decision

Dados sensíveis deverão ser minimizados.

54. Cost Management

O Gateway deverá medir:

requests
data transferred
provider cost
execution duration
retry count

permitindo calcular:

Cost per integration
Cost per tenant
Cost per workflow
Cost per capability

55. Tenant Quotas

Exemplo:

tenant:
  integrations:
    requestsPerMinute: 500
    dailyRequests: 100000
    concurrentOperations: 20

Os limites deverão ser aplicados antes da chamada externa.

56. Digital Workforce

O conceito de Digital Workforce surge aqui.

Uma capability poderá representar um “trabalhador digital” especializado:

Training Agent
HR Agent
Compliance Agent
Document Agent
Integration Agent
Notification Agent

Mas esses não serão agentes independentes com privilégios irrestritos.

Serão especializações sobre a mesma infraestrutura:

Shared Agent Runtime
+
Shared Policy
+
Shared Capability Registry
+
Shared Audit

57. Specialist Agent

Exemplo:

Training Specialist

poderá possuir:

training.search
training.checkValidity
training.requestRenewal

mas não:

employee.delete
salary.update
admin.changePolicy

O princípio será:

Especialização reduz o conjunto de capacidades; nunca amplia privilégios.

58. Agent-to-Agent Communication

Futuramente poderá existir:

Compliance Agent
       ↓
Training Agent
       ↓
Document Agent

Mas a comunicação deverá ocorrer através de contratos estruturados.

interface AgentTask {
  taskId: string;

  sourceAgent: string;

  targetAgent: string;

  capabilityId: string;

  input: unknown;

  tenantId: string;

  correlationId: string;
}

59. Agent Identity

Cada agente especializado deverá possuir identidade própria:

agentId
agentVersion
capabilitySet
policyScope

Mas:

Agent identity não substitui user authorization.

Uma solicitação iniciada pelo usuário deverá manter a cadeia:

User
 ↓
Agent
 ↓
Specialist
 ↓
Capability

60. No Privilege Escalation

O agente especializado nunca poderá obter privilégios maiores que os do contexto original.

User permissions
       ↓
upper bound
       ↓
Agent permissions
       ↓
Capability

61. Example — Training Expiration

LMS
 ↓
TrainingExpired Event
 ↓
Event Fabric
 ↓
Proactive Intelligence
 ↓
Decision Engine
 ↓
Affected Work Permits
 ↓
Policy
 ↓
Workflow

O workflow poderá solicitar:

Training Specialist

que utilizará:

training.external.getStatus
training.external.getCertificate

e retornará os resultados ao workflow.

62. End-to-End Example

Usuário:

“Verifique se todos os trabalhadores das permissões abertas estão com os treinamentos em dia.”

Fluxo:

Intent
 ↓
Planner
 ↓
Capability Discovery
 ↓
Policy
 ↓
Work Permit Query
 ↓
Worker Resolution
 ↓
Training Capability
 ↓
External Gateway
 ↓
LMS
 ↓
Normalization
 ↓
Verification
 ↓
Decision Engine
 ↓
Result

Resposta:

“Encontrei 237 trabalhadores. 221 estão regulares, 11 possuem treinamento vencendo em até 15 dias e 5 possuem treinamento expirado.”

63. Proactive Example

O mesmo processo poderá ser iniciado automaticamente:

TrainingExpiresSoon
 ↓
Event Fabric
 ↓
Proactive Intelligence
 ↓
Decision
 ↓
37 affected Work Permits
 ↓
Risk HIGH
 ↓
Workflow
 ↓
Notification

Assim os PRDs anteriores passam a formar um ciclo completo.

64. Arquitetura Consolidada

Neste ponto, a arquitetura passa a ser:

                         USER
                           │
                           ▼
                    Conversation
                           │
                           ▼
                         Intent
                           │
                           ▼
                        Planner
                           │
                           ▼
                       Decision
                           │
                           ▼
                         Policy
                           │
                           ▼
                       Capability
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
       Internal Runtime          External Gateway
              │                         │
              ▼                         ▼
        Business APIs             External Systems
              │                         │
              └────────────┬────────────┘
                           ▼
                      Verification
                           │
                           ▼
                        Workflow
                           │
                           ▼
                         Events
                           │
                           ▼
                      Proactive
                           │
                           ▼
                     Decision Center
                           │
                           ▼
                      Human / Agent

65. Critérios de Aceitação

Evidência parcial de implementação — 2026-09-04

O registry de integrações é versionado por tenant e exige evidência de contrato para ativação. O gateway autoriza somente capability/binding/policy registrados, impõe host allowlist, validação de payload, limites de timeout, rate, concorrência e quota diária, e registra estado de saúde/circuit breaker. Dispatches são cifrados e entregues por Queue; webhooks validam assinatura, timestamp e nonce, persistem recibo idempotente e normalizam eventos tenant-bound. A trilha de agência registra principal, delegação, capability, política e referência de credencial sem expor o segredo.

Em 2026-09-05, a saída de rede do Gateway passou a usar redirect: "error": uma resposta de redirecionamento falha fechada em vez de poder alcançar um destino fora da allowlist. O comportamento é coberto pelo teste de execução do LMS sandbox. Worker 893aa68c-3836-41dc-ae4d-97fe8df9c52f publicado com health público saudável.

Em 2026-09-05, os contratos de registry, gateway, webhook e executor externo passaram com 35 testes em 5 arquivos. O canário LMS remoto comprovou autorização, execução síncrona e assíncrona, confirmação externa, health HEALTHY, recibo do provedor, custo rastreado, freshness FRESH, reconciliação MATCH, gate stale UNKNOWN, dispatch cifrado, contexto isolado, negação de escopo/revogação/quota e ausência de segredo; o cleanup confirmou remainingRows:0. A auditoria externa independente permanece aberta para prova dedicada.

Em 2026-09-06, a regressão atual de payload, notificações, registry, gateway e webhooks passou com 44 testes. O typecheck do Agent passou novamente, e o health público do Worker confirmou runtime e bindings. O estado permanece PARTIAL pela ausência de resolvers OAuth/mTLS/JWT reais, bulk, PUSH/SMS e reconciliação multi-domínio ampla.

66. Resultado do PRD-025

O Agentic Work deixa de ser apenas um agente que opera o banco/API do SST.

Ele passa a ser uma camada operacional empresarial, capaz de conectar:

SST
+
RH
+
LMS
+
ERP
+
documentos
+
serviços externos
+
eventos

sem perder o controle centralizado de:

Identity
Authorization
Policy
Capabilities
Audit
Verification
Tenant Isolation
Cost
Security

E isso prepara a arquitetura para o próximo salto.

PRD-026 — Agentic Multi-Agent Orchestration & Specialist Agents

O próximo PRD deverá formalizar a evolução de um único Agent Runtime para uma arquitetura de múltiplos agentes especializados, sem cair no erro comum de criar vários “agentes autônomos” com privilégios independentes.

A arquitetura deverá ser:

                         Agent Supervisor
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼
       Compliance Agent   Training Agent    Document Agent
              │                 │                 │
              └─────────────────┼─────────────────┘
                                ▼
                       Shared Capability Layer
                                │
                       Shared Policy Engine
                                │
                         Shared Audit Fabric

O ponto central do PRD-026 será:

Multi-agent não significa múltiplas autoridades. Significa múltiplas especializações sob uma única arquitetura de segurança, políticas, capacidades, auditoria e identidade.

Ele deverá definir delegação de tarefas, agent contracts, supervisor, specialist discovery, handoff, contexto compartilhado, isolamento de contexto, limites de autoridade, prevenção de loops entre agentes, consenso quando necessário, paralelização, failure handling, agent-to-agent audit, custo, observabilidade e avaliação de sistemas multi-agent.

1. Objetivo​

2. Princípio fundamental

3. Problema que o PRD resolve

4. Arquitetura

5. Integration Registry

6. Integration ≠ Capability

7. External Capability

8. Adapter Pattern

9. Canonical Data Model

10. Mapping Layer

11. Authentication

12. Credential Isolation

13. Tenant Credentials

14. Global Integration

15. Egress Control

16. SSRF Protection

17. Request Schema

18. Response Schema

19. Timeout

20. Retry

21. Circuit Breaker

22. Rate Limiting

23. External Rate Limit

24. Queueing

25. Synchronous vs Asynchronous

Síncrono​

Assíncrono​

26. External Webhooks

27. Webhook Security

28. External Events

29. External Documents

30. Document Provenance

31. External Data → Knowledge

32. External Data → Decision

33. External Data Trust

34. Data Freshness

35. External Verification

36. Unknown External State

37. External Transaction ID

38. Reconciliation

39. Integration Health

40. Agent Awareness

41. Integration Policy

42. Data Egress Policy

43. LLM Data Minimization

44. External System Instructions

45. Human Approval

46. External Communication

47. Anti-Spam

48. External Integration Lifecycle

49. Integration Versioning

50. Contract Testing

51. Mock External Systems

52. Sandbox

53. External Integration Audit

54. Cost Management

55. Tenant Quotas

56. Digital Workforce

57. Specialist Agent

58. Agent-to-Agent Communication

59. Agent Identity

60. No Privilege Escalation

61. Example — Training Expiration

62. End-to-End Example

63. Proactive Example

64. Arquitetura Consolidada

65. Critérios de Aceitação

Evidência parcial de implementação — 2026-09-04​

66. Resultado do PRD-025

PRD-026 — Agentic Multi-Agent Orchestration & Specialist Agents

1. Objetivo

Síncrono

Assíncrono

Evidência parcial de implementação — 2026-09-04