Skip to main content

PRD-010 — Agentic Conversation Runtime

1. Objetivo​

O Agentic Conversation Runtime é responsável por transformar a conversa entre usuário e agente em um estado operacional contínuo, capaz de manter contexto, resolver referências, acompanhar ações pendentes, receber confirmações, tratar correções e continuar operações após resultados parciais ou falhas.

A conversa deixa de ser simplesmente:

mensagem → LLM → resposta

e passa a ser:

mensagem → estado conversacional → intenção → contexto → plano → política → execução → resultado → próximo estado

O Runtime deve permitir que o usuário converse com o sistema de forma natural, sem precisar repetir informações que já estejam inequivocamente disponíveis no contexto.

2. Problema

Em um agente tradicional, cada mensagem é tratada isoladamente.

Por exemplo:

Usuário: Abra a permissão 123.

Agente: Permissão 123 aberta.

Usuário: Vá para os componentes.

O segundo comando depende de informações da primeira interação.

O agente precisa saber:

  • qual permissão foi aberta;
  • qual entidade está selecionada;
  • em qual página o usuário está;
  • qual aba está ativa;
  • qual foi a última operação;
  • se existe uma operação pendente;
  • se o usuário está confirmando algo;
  • se o usuário está corrigindo uma interpretação anterior;
  • se “isso”, “esse”, “aquele” ou “ela” se refere ao objeto atual;
  • se a nova mensagem é continuação da operação anterior ou uma nova solicitação.

Portanto, o Runtime precisa manter estado semântico, e não simplesmente histórico textual.

3. Princípio arquitetural

A conversa deve ser modelada como uma máquina de estados operacional.

                    ┌──────────────────────┐
                    │      USER MESSAGE    │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │ Conversation Runtime │
                    └──────────┬───────────┘
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
             ▼                 ▼                 ▼
       Context Update    Intent Resolution   Reference
                                              Resolution
             │                 │                 │
             └─────────────────┼─────────────────┘
                               │
                               ▼
                        ┌─────────────┐
                        │ Intent State│
                        └──────┬──────┘
                               │
                               ▼
                         Planner 006
                               │
                               ▼
                         Policy 008
                               │
                               ▼
                        Execution
                               │
                               ▼
                         Result State
                               │
                               ▼
                      Next Conversation State

O Runtime não substitui os PRDs anteriores.

Ele coordena:

  • PRD-003 — Knowledge Router;
  • PRD-004 — Capability Registry;
  • PRD-005 — Intent Engine;
  • PRD-006 — Planner & Execution Orchestrator;
  • PRD-007 — Tool Runtime & Context Bridge;
  • PRD-008 — Policy Engine;
  • PRD-009 — Knowledge-to-Capability Binding.

4. Escopo

O PRD-010 cobre:

  1. gerenciamento de estado conversacional;
  2. continuidade entre mensagens;
  3. resolução de referências;
  4. follow-up intents;
  5. confirmação de operações;
  6. esclarecimentos;
  7. cancelamento;
  8. correção de interpretação;
  9. retomada após erro;
  10. controle de contexto;
  11. isolamento entre operações;
  12. histórico operacional;
  13. estado pendente;
  14. expiração de estado;
  15. contexto de curto e médio prazo;
  16. integração com execução;
  17. streaming do estado para a UI;
  18. prevenção de contaminação por contexto antigo.

Não cobre:

  • implementação do LLM;
  • implementação do HAG;
  • implementação do Capability Registry;
  • implementação do Policy Engine;
  • implementação da execução das APIs.

Esses componentes já foram definidos anteriormente.

5. Modelo conceitual

Uma Conversation será composta por vários estados e objetos relacionados.

Conversation
│
├── ConversationContext
│
├── ActiveIntent
│
├── PendingClarification
│
├── PendingConfirmation
│
├── ActiveExecution
│
├── LastResult
│
├── ReferenceState
│
├── ContextSnapshot
│
└── MessageHistory

O histórico de mensagens é apenas uma parte da conversa.

O estado operacional possui prioridade sobre o texto histórico.

6. Estados da conversa

O Runtime deverá suportar, no mínimo:

IDLE
UNDERSTANDING
CLARIFICATION_REQUIRED
PLANNING
CONFIRMATION_REQUIRED
EXECUTING
PARTIAL_SUCCESS
SUCCESS
FAILED
CANCELLED
CORRECTING
RESUMING
CLOSED

IDLE​

Nenhuma operação pendente.

O usuário pode iniciar uma nova solicitação.

UNDERSTANDING​

O sistema está interpretando a mensagem.

Pode executar:

  • normalização;
  • resolução de contexto;
  • resolução de referências;
  • classificação de intenção;
  • busca de conhecimento;
  • descoberta de capabilities.

CLARIFICATION_REQUIRED​

O agente não possui informação suficiente para executar com segurança.

Exemplo:

Usuário: Adicione o funcionário.

Existem 12 funcionários possíveis.

O agente deverá perguntar:

Qual funcionário você deseja adicionar?

PLANNING​

A intenção foi compreendida e o Planner está construindo o plano.

CONFIRMATION_REQUIRED​

O plano está pronto, mas exige confirmação.

Exemplo:

Encontrei o componente “Trabalho em Altura”. Deseja adicioná-lo à Permissão 123?

EXECUTING​

O plano está sendo executado.

PARTIAL_SUCCESS​

Uma operação multi-step terminou parcialmente.

Exemplo:

3 componentes:
✓ Trabalho em altura
✓ Trabalho a quente
✗ Espaço confinado

SUCCESS​

Operação concluída.

FAILED​

A operação falhou.

CANCELLED​

O usuário cancelou uma operação pendente.

CORRECTING​

O usuário indicou que a interpretação anterior estava incorreta.

Exemplo:

Não era essa permissão.

RESUMING​

O agente está retomando uma operação interrompida.

7. Conversation State

Modelo conceitual:

interface ConversationState {
  conversationId: string;

  tenantId: string;
  userId: string;
  sessionId: string;

  status: ConversationStatus;

  activeIntent?: IntentState;

  pendingClarification?: ClarificationState;

  pendingConfirmation?: ConfirmationState;

  activeExecution?: ExecutionState;

  lastResult?: ExecutionResult;

  context: ConversationContext;

  references: ReferenceState[];

  version: number;

  createdAt: string;
  updatedAt: string;
}

8. Conversation Context

O contexto conversacional deve ser estruturado.

interface ConversationContext {
  applicationId: string;

  uiContext?: SemanticUIContext;

  activeEntity?: EntityReference;

  activeCapability?: string;

  activeOperation?: string;

  recentEntities: EntityReference[];

  recentCapabilities: string[];

  recentResults: ResultReference[];

  conversationTopic?: string;

  knowledgeVersion?: string;

  manifestVersion?: string;

  timestamp: string;
}

9. Contexto não é histórico

Este é um princípio importante.

O agente não deve depender de reenviar toda a conversa ao LLM para descobrir o contexto atual.

Em vez disso:

Conversation History
        │
        ▼
Conversation State
        │
        ├── Active Entity
        ├── Active Intent
        ├── Pending Action
        ├── UI Context
        ├── Last Result
        └── References

O LLM recebe somente o contexto necessário.

Isso reduz:

  • latência;
  • custo;
  • tokens;
  • ambiguidades;
  • risco de usar informação antiga.

10. Resolução de referências

Uma das funções mais importantes do Runtime é resolver expressões como:

  • isso;
  • isto;
  • esse;
  • essa;
  • aquele;
  • aquela;
  • ele;
  • ela;
  • o anterior;
  • o último;
  • essa permissão;
  • esse funcionário;
  • esse componente.

Exemplo:

Abra a permissão 123.

Depois:

Vá para os componentes.

Depois:

Adicione esse componente.

O agente deve resolver:

"esse componente"
        ↓
lastReferencedEntity
        ↓
component:COMP-81

11. Hierarquia de resolução

A resolução deverá seguir esta prioridade:

1. Referência explícita
2. Entidade selecionada na UI
3. Entidade ativa
4. Resultado da última operação
5. Foco semântico
6. Entidade mencionada na mensagem anterior
7. Entidades recentes
8. Contexto da conversa
9. HAG
10. Inferência LLM

Nunca utilizar uma inferência fraca quando existir uma referência determinística.

12. Ambiguidade

O Runtime deve possuir um Ambiguity Resolver.

Exemplo:

Usuário:
"Abra a permissão 123"

Existe somente uma:

WP-123

→ executar.

Mas se houver:

WP-123 — Empresa A
WP-123 — Empresa B

não deve escolher arbitrariamente.

Deve perguntar:

Encontrei duas permissões 123. Você quer a da Empresa A ou a da Empresa B?

13. Clarification State

interface ClarificationState {
  clarificationId: string;

  intentId: string;

  question: string;

  missingFields: string[];

  candidates?: ReferenceCandidate[];

  expiresAt: string;

  attempts: number;
}

Exemplo:

{
  "missingFields": [
    "employeeId"
  ],
  "question": "Qual funcionário você deseja adicionar?"
}

Quando o usuário responde:

João Silva.

o Runtime não deve criar uma nova intenção independente.

Deve completar a intenção pendente.

14. Pending Intent

Uma intenção incompleta deve permanecer armazenada.

Intent
├── target = workPermit:WP-123
├── action = addComponent
├── componentType = ?
└── employee = ?

Usuário:

João Silva.

Estado:

Intent
├── target = workPermit:WP-123
├── action = addComponent
├── componentType = ?
└── employee = João Silva

O Runtime verifica se ainda falta alguma informação.

15. Confirmation State

Confirmação deve ser tratada como estado explícito.

interface ConfirmationState {
  confirmationId: string;

  planId: string;

  riskLevel: RiskLevel;

  summary: string;

  affectedResources: ResourceReference[];

  expiresAt: string;

  confirmationToken: string;

  requiredLevel: "soft" | "strong" | "human_review";
}

Exemplo:

Agent:
Deseja excluir o registro RISCO-22?

User:
Sim.

O "Sim" somente é válido porque existe um PendingConfirmation.

16. Confirmação contextual

Nunca interpretar:

Sim

como autorização global.

A confirmação deve estar vinculada a:

confirmationId
planId
userId
tenantId
intent
resource
risk
expiration

Portanto:

"Sim"

não significa:

execute qualquer operação pendente.

Significa:

confirme especificamente a operação associada ao PendingConfirmation atual.

17. Expiração

Confirmações e intenções pendentes devem expirar.

Exemplo:

Confirmation TTL = 5 minutos

Após isso:

CONFIRMATION_REQUIRED
        ↓
EXPIRED

O agente deverá solicitar nova confirmação.

18. Cancelamento

O usuário pode dizer:

cancela

esquece

não faça

pare

deixa para lá

O Runtime deverá reconhecer isso mesmo que exista uma confirmação ou execução pendente.

Antes da execução​

Cancelar imediatamente.

Durante execução​

Depende da capability.

Se a operação puder ser interrompida:

EXECUTING
   ↓
CANCELLING
   ↓
CANCELLED

Caso não possa:

A operação já foi iniciada e não pode mais ser interrompida. Vou concluir esta etapa e informar o resultado.

19. Correção de interpretação

Exemplo:

Usuário: Abra a permissão 123.

Agente: Abri a permissão WP-123 da Empresa A.

Usuário: Não, a da Empresa B.

O Runtime deve identificar uma correction intent.

Não deve criar simplesmente:

OPEN_PERMISSION

Deve modificar o contexto ativo:

activeEntity = WP-123 / Empresa B

e registrar a correção.

20. Princípio de correção

Uma correção explícita do usuário tem prioridade sobre qualquer inferência anterior.

User correction
      >
Explicit reference
      >
UI selection
      >
Conversation state
      >
HAG
      >
LLM inference

21. “Desfaça”

O comando:

desfaça

é diferente de:

cancele.

Cancelar​

Impede uma operação ainda não concluída.

Desfazer​

Solicita uma operação compensatória sobre uma operação já executada.

Exemplo:

CREATE component
       ↓
SUCCESS
       ↓
"Desfaça"
       ↓
DELETE component

O Runtime deverá verificar se existe uma capability de compensação registrada.

Nunca deve inventar uma operação inversa.

22. Undo Registry

Capabilities poderão declarar:

interface UndoDefinition {
  capabilityId: string;

  undoCapabilityId: string;

  conditions: string[];

  reversible: boolean;

  expiresAfter?: number;
}

Exemplo:

workPermit.components.add
        ↓
undo
        ↓
workPermit.components.remove

Se não houver capability de undo:

Essa operação não pode ser desfeita automaticamente.

23. Follow-up Intent

Uma das funções mais importantes.

Exemplo:

Usuário: Explique a validade da permissão.

Agente: A validade padrão é de 30 dias...

Usuário: Mude para 60.

O segundo comando não contém:

  • entidade;
  • propriedade;
  • capability.

O Runtime deve recuperar:

conversation.topic = workPermit.validity

e produzir:

UPDATE
target = currentWorkPermit
property = validity
value = 60

24. Follow-up com mudança de assunto

O agente deve saber quando uma mensagem inicia outro tópico.

Exemplo:

Explique a validade da permissão.

Depois:

Quantos funcionários estão cadastrados?

A segunda mensagem não deve herdar automaticamente:

workPermit.validity

O Intent Engine reclassifica o tópico.

25. Topic State

interface TopicState {
  topicId: string;

  semanticId?: string;

  entity?: EntityReference;

  capabilityDomain?: string;

  startedAt: string;

  lastActivityAt: string;
}

O tópico atual funciona como contexto de curto prazo.

26. Conversation Scope vs Operation Scope

É fundamental separar:

Conversation Scope​

Informações gerais da conversa.

Operation Scope​

Informações específicas da operação atual.

Exemplo:

Conversation
└── User discussing Work Permits

Operation A
└── Update WP-123 validity

Operation B
└── Add component COMP-81 to WP-123

Uma nova operação não deve herdar automaticamente todos os dados da anterior.

27. Operation Context

interface OperationContext {
  operationId: string;

  intentId: string;

  targetEntities: EntityReference[];

  capabilityIds: string[];

  uiContextSnapshot?: SemanticUIContext;

  knowledgeVersion?: string;

  manifestVersion?: string;

  createdAt: string;
}

Isso cria uma fronteira clara entre operações.

28. Context Snapshot

Antes de executar uma operação importante, o Runtime deve capturar um snapshot.

Operation
   │
   └── Context Snapshot
         ├── page
         ├── tab
         ├── selection
         ├── focus
         ├── entity
         ├── filters
         ├── form state
         └── contextVersion

Esse snapshot permite verificar posteriormente se o contexto mudou.

29. Stale Context

Exemplo:

  1. Usuário seleciona WP-123.
  2. Agente prepara atualização.
  3. Usuário muda para WP-456.
  4. Agente recebe confirmação.

O agente não deve atualizar WP-456 simplesmente porque ele é a seleção atual.

O plano original estava associado a:

WP-123

Portanto:

plan.target = WP-123

continua sendo a referência.

Se necessário, o Runtime deve avisar:

A permissão selecionada mudou desde que preparei essa operação. A operação estava direcionada à WP-123. Deseja continuar?

30. Conversation Version

O estado deve possuir versionamento otimista.

interface ConversationState {
  version: number;
}

Atualização:

version 12
   ↓
update
   ↓
version 13

Se dois eventos tentarem alterar:

version 12

simultaneamente, um deverá falhar e ser reprocessado.

Isso evita race conditions.

31. Eventos conversacionais

O Runtime deverá trabalhar orientado a eventos.

Exemplos:

MESSAGE_RECEIVED
CONTEXT_UPDATED
INTENT_CREATED
INTENT_UPDATED
REFERENCE_RESOLVED
CLARIFICATION_REQUIRED
CLARIFICATION_RESOLVED
PLAN_CREATED
CONFIRMATION_REQUIRED
CONFIRMATION_RECEIVED
EXECUTION_STARTED
EXECUTION_PROGRESS
EXECUTION_COMPLETED
EXECUTION_FAILED
EXECUTION_CANCELLED
CORRECTION_RECEIVED
UNDO_REQUESTED
TOPIC_CHANGED
CONVERSATION_CLOSED

32. Event Envelope

interface ConversationEvent {
  id: string;

  conversationId: string;

  operationId?: string;

  type: ConversationEventType;

  timestamp: string;

  actor: "user" | "agent" | "system";

  payload: unknown;

  stateVersion: number;
}

33. Event Sourcing parcial

Não é necessário transformar todo o sistema em Event Sourcing.

Entretanto, eventos operacionais importantes devem ser persistidos.

Especialmente:

  • intent;
  • clarification;
  • confirmation;
  • plan;
  • execution;
  • result;
  • correction;
  • cancellation;
  • undo.

Isso cria uma trilha auditável.

34. Persistência

Como o sistema utiliza infraestrutura serverless, o estado conversacional não deve depender da memória do Worker.

Modelo conceitual:

Hot State
   ↓
KV / Durable State

Operational State
   ↓
D1

Execution State
   ↓
Durable execution mechanism

Large artifacts
   ↓
R2

A implementação específica deve permanecer desacoplada.

O Runtime deverá utilizar uma interface:

interface ConversationStore {
  get(conversationId: string): Promise<ConversationState>;

  save(state: ConversationState): Promise<void>;

  appendEvent(event: ConversationEvent): Promise<void>;

  lock(conversationId: string): Promise<void>;

  unlock(conversationId: string): Promise<void>;
}

35. Conversation Lock

Somente uma transição crítica deve modificar o estado de uma conversa por vez.

Exemplo:

User Message A
       │
       ▼
Conversation Lock
       │
       ▼
State Update
       │
       ▼
Unlock

Isso evita que:

"sim"

seja processado simultaneamente com:

"cancela"

36. Context Compression

Não enviar o histórico completo para o modelo.

O Runtime deve construir um:

Conversation Context Package

contendo apenas:

Current topic
Active entity
Current operation
Pending clarification
Pending confirmation
Last relevant result
Relevant previous references
UI semantic context
Relevant knowledge

Exemplo:

{
  "topic": "workPermit.components",
  "entity": "WP-123",
  "activeTab": "components",
  "lastComponent": "COMP-81",
  "pendingOperation": "addComponent"
}

37. Long-Term Conversation Memory

O Runtime não deve automaticamente transformar todo histórico em memória permanente.

Somente informações explicitamente classificadas como persistentes poderão ser armazenadas como memória.

Exemplo:

Conversation memory
≠
User profile memory

A memória conversacional normalmente terá escopo:

conversation
session
operation

e não global.

38. Segurança contra Context Leakage

Um dos requisitos mais importantes.

O agente nunca deverá reutilizar:

  • dados de outro tenant;
  • entidades de outra sessão;
  • resultados de outro usuário;
  • informações de uma operação não autorizada.

Toda referência deve possuir:

tenantId
user scope
resource scope

quando aplicável.

39. Isolamento entre conversas

Conversation A
    ↓
State A

Conversation B
    ↓
State B

Nunca:

Conversation A
      ↓
global agent memory
      ↓
Conversation B

sem uma camada explícita de autorização e escopo.

40. Tratamento de erro

Quando uma operação falhar, o Runtime deve preservar o contexto suficiente para permitir:

tente novamente

ou:

faça de outra maneira.

Exemplo:

Agent:
Não consegui atualizar a validade porque a permissão está aprovada.

User:
Então cancele a permissão.

A nova intenção deve utilizar o contexto da operação anterior, mas passar novamente pelo:

Intent
→ Planner
→ Policy
→ Authorization
→ Execution

Nunca reutilizar autorização antiga.

41. Retry conversacional

O usuário poderá dizer:

tente novamente

O Runtime deverá recuperar a última operação falhada.

Mas deve verificar:

  • se ainda é válida;
  • se o contexto não mudou;
  • se a entidade ainda existe;
  • se as permissões permanecem;
  • se a capability ainda está ativa;
  • se a operação é idempotente.

42. Resultado como contexto

O resultado da operação deve alimentar o próximo turno.

Exemplo:

CREATE
   ↓
COMP-81 created
   ↓
LastResult

Usuário:

Explique esse componente.

Resolver:

"esse componente"
        ↓
LastResult.createdEntity
        ↓
COMP-81

43. Result Reference

interface ResultReference {
  entity?: EntityReference;

  operationId: string;

  capabilityId: string;

  resultType: string;

  timestamp: string;
}

Isso permite referências naturais a resultados recentes.

44. Resposta do agente

O Runtime deverá separar:

Execution Result

de:

Natural Language Response

Exemplo:

{
  "execution": {
    "status": "success",
    "entityId": "COMP-81"
  },
  "response": {
    "type": "success",
    "template": "component.created"
  }
}

O Result Composer transforma isso em:

Componente “Trabalho em Altura” adicionado à Permissão 123.

45. Streaming

Durante operações longas, o usuário deve receber eventos progressivamente.

Preparando operação...
        ↓
Validando permissão...
        ↓
Validando componente...
        ↓
Adicionando componente...
        ↓
Confirmando resultado...
        ↓
Concluído.

Esses eventos devem vir do Execution Orchestrator e passar pelo Conversation Runtime até a UI.

46. Multi-step conversation

O Runtime deverá suportar:

User
 ↓
Intent
 ↓
Clarification
 ↓
User answer
 ↓
Intent completion
 ↓
Plan
 ↓
Confirmation
 ↓
User confirmation
 ↓
Execution
 ↓
Result
 ↓
Follow-up

Isso é essencial para tornar a interação realmente agentic.

47. Exemplo completo

Turno 1​

Abra a permissão 123.

Runtime:

Intent = NAVIGATION
Entity = WP-123
Capability = navigation.openEntity

Executa.

Turno 2​

Agora vá para os componentes.

Runtime:

activeEntity = WP-123
activeTab = components

Executa:

OPEN_TAB(workPermit.components)

Turno 3​

Adicione o componente de trabalho em altura.

Runtime:

Intent = CREATE
Target = WP-123
Component = workingAtHeight
Capability = workPermit.components.add
Risk = medium

Policy:

REQUIRE_CONFIRMATION

Turno 4​

Sim.

Runtime identifica:

PendingConfirmation

e não cria uma nova intenção.

Executa o plano.

Turno 5​

Explique esse componente.

Runtime:

Reference:
"esse componente"
        ↓
LastResult.createdEntity
        ↓
COMP-81

Intent:

EXPLANATION
target = COMP-81

Knowledge Router busca documentação relacionada.

48. Correção

Usuário:

Adicione o componente de trabalho em altura.

Agente:

Deseja adicionar o componente “Trabalho em Altura”?

Usuário:

Não. Quero “Trabalho a Quente”.

O Runtime deverá alterar o pending intent:

component = workingAtHeight

para:

component = hotWork

e invalidar a confirmação anterior.

A confirmação anterior não pode permanecer válida depois que o objeto da operação mudou.

49. Mudança de entidade

Usuário:

Atualize a validade para 60 dias.

Agente prepara WP-123.

Usuário:

Ah, não. É a permissão 456.

O Runtime deverá:

  1. invalidar o plano anterior;
  2. atualizar a entidade;
  3. recalcular autorização;
  4. recalcular política;
  5. recalcular plano;
  6. pedir nova confirmação se necessária.

50. Conversation Garbage Collection

Estados temporários devem possuir TTL.

Exemplo:

Pending clarification: 15 min
Pending confirmation: 5 min
Operation context: 30 min
Recent references: session lifetime
Conversation history: configurable

Valores devem ser configuráveis.

51. Métricas

O Runtime deverá medir:

Conversação​

  • conversation turns;
  • average turns per task;
  • task completion rate;
  • abandoned conversations.

Contexto​

  • reference resolution rate;
  • ambiguous references;
  • context misses;
  • stale context events.

Intent​

  • follow-up resolution;
  • clarification rate;
  • correction rate;
  • intent replacement rate.

Execução​

  • confirmation rate;
  • cancellation rate;
  • retry rate;
  • undo rate;
  • failure recovery rate.

Performance​

  • state lookup latency;
  • state update latency;
  • reference resolution latency;
  • total turn latency.

52. Observabilidade

Cada operação deverá possuir:

conversationId
operationId
intentId
planId
executionId

permitindo rastrear:

User Message
      ↓
Intent
      ↓
Capability
      ↓
Policy
      ↓
Plan
      ↓
Execution
      ↓
API
      ↓
Verification
      ↓
Response

Isso será extremamente importante para debugging.

53. Segurança

O Runtime deverá aplicar:

Tenant isolation​

Toda conversa pertence a um tenant.

User isolation​

O estado é associado ao usuário autenticado.

Session isolation​

Conversas de sessões distintas não devem compartilhar estado operacional implicitamente.

Authorization​

Toda nova execução passa novamente pelo Policy Engine.

Context validation​

Contexto antigo não deve ser utilizado sem verificação.

Sensitive data minimization​

O estado conversacional deve armazenar o mínimo necessário.

54. Não confiar no cliente

A UI poderá enviar:

selectedEntity = WP-123

mas isso não significa que WP-123 pertence ao usuário.

O servidor deve obter:

userId
tenantId
permissions

do mecanismo de autenticação confiável e validar o recurso.

55. API conceitual

O Runtime poderá expor:

POST /agent/conversations
POST /agent/conversations/:id/messages
GET  /agent/conversations/:id
POST /agent/conversations/:id/confirm
POST /agent/conversations/:id/cancel
POST /agent/conversations/:id/undo
POST /agent/conversations/:id/resume
GET  /agent/conversations/:id/events

Os endpoints reais deverão ser definidos posteriormente pela equipe.

56. Conversation Runtime API

Interface interna:

interface ConversationRuntime {
  receiveMessage(
    conversationId: string,
    message: UserMessage
  ): Promise<ConversationTurn>;

  confirm(
    conversationId: string,
    confirmationId: string
  ): Promise<ConversationTurn>;

  cancel(
    conversationId: string
  ): Promise<ConversationTurn>;

  undo(
    conversationId: string
  ): Promise<ConversationTurn>;

  resume(
    conversationId: string
  ): Promise<ConversationTurn>;

  getState(
    conversationId: string
  ): Promise<ConversationState>;
}

57. Regra fundamental de execução

O Conversation Runtime nunca executa diretamente uma API de negócio.

Sempre:

Conversation Runtime
        ↓
Intent Engine
        ↓
Planner
        ↓
Policy Engine
        ↓
Capability
        ↓
Tool Runtime
        ↓
Existing API

Isso preserva a arquitetura definida nos PRDs anteriores.

58. Fast Path

A maioria dos turnos deverá evitar LLM.

Exemplo:

Sim.

Fluxo:

MESSAGE
 ↓
PendingConfirmation lookup
 ↓
Validate confirmation
 ↓
Policy
 ↓
Execute

Nenhum LLM é necessário.

Outro:

Vá para os componentes.

Com contexto claro:

Current Entity
+
UI semantic context
+
Navigation capability

→ execução determinística.

Isso é fundamental para atingir o objetivo de uma experiência extremamente rápida.

59. Quando usar LLM

LLM deverá ser utilizado principalmente quando houver:

  • linguagem ambígua;
  • intenção complexa;
  • múltiplas interpretações;
  • planejamento não determinístico;
  • explicação contextual;
  • síntese de resultados;
  • ausência de correspondência determinística.

Não deve ser utilizado para:

  • "sim";
  • "não";
  • "cancela";
  • "desfaça";
  • resolução direta de entidade;
  • navegação conhecida;
  • lookup por Semantic ID;
  • recuperação de capability;
  • validações estruturais.

60. Primeiro Vertical Slice

O primeiro vertical slice do PRD-010 deverá utilizar Work Permit.

Fluxo mínimo:

Abrir Work Permit
        ↓
Navegar para Components
        ↓
Selecionar Component
        ↓
Adicionar Component
        ↓
Confirmar
        ↓
Executar
        ↓
Resultado
        ↓
"Explique esse componente"
        ↓
Knowledge Retrieval

Depois:

Correction
Cancellation
Retry
Undo
Multi-step

61. Critérios de aceitação

O PRD será considerado implementado quando:

Conversação​

  • conversa possui estado persistente;
  • estado possui versionamento;
  • operações possuem contexto próprio;
  • tópicos podem mudar sem contaminar operações anteriores;
  • contexto conversacional não depende exclusivamente do histórico textual.

Referências​

  • “isso”, “esse”, “aquele” podem ser resolvidos;
  • seleção da UI pode resolver entidades;
  • resultados anteriores podem ser referenciados;
  • ambiguidades não são arbitradas silenciosamente.

Clarificação​

  • intenções incompletas podem permanecer pendentes;
  • respostas posteriores completam a intenção;
  • perguntas possuem estado e TTL.

Confirmação​

  • confirmações são vinculadas a um plano;
  • confirmação possui TTL;
  • mudança de intenção invalida confirmação;
  • confirmação não substitui autorização.

Correção​

  • usuário pode corrigir uma interpretação;
  • plano anterior é invalidado quando necessário;
  • autorização é recalculada.

Cancelamento​

  • operações pendentes podem ser canceladas;
  • execução em andamento respeita capacidade de cancelamento;
  • estado é atualizado corretamente.

Undo​

  • undo somente utiliza capabilities registradas;
  • operações irreversíveis são identificadas;
  • undo possui política própria.

Resiliência​

  • operações podem ser retomadas;
  • falhas podem ser reexecutadas quando seguro;
  • contexto é preservado durante erros;
  • race conditions são evitadas.

Segurança​

  • isolamento por tenant;
  • isolamento por usuário;
  • contexto antigo não pode alterar recurso errado;
  • autorização ocorre novamente na execução;
  • dados sensíveis são minimizados.

Performance​

  • confirmações não utilizam LLM;
  • cancelamentos simples não utilizam LLM;
  • navegação contextual não utiliza LLM quando determinística;
  • lookup do estado é de baixa latência;
  • histórico completo não é enviado desnecessariamente ao modelo.

Evidência de implementação e produção — 2026-09-05​

O runtime modela estado e revisão de conversa, tópicos explícitos, operação com contextVersion, referências determinísticas de UI/resultado/conversa e pendências de clarificação/confirmação com TTL. Confirmação exige o planId exato e não substitui autorização; correção invalida operação pendente, cancelamento não vira undo e transições terminais são fechadas. O Agent SDK Durable Object persiste o snapshot SQLite isolado por tenant e usuário, sem depender de transcrição bruta.

Em 2026-09-04, ConversationRuntime.rehydrate passou a validar e restaurar snapshot operacional somente quando identidade, revisão, timeline e transições são coerentes; qualquer adulteração falha fechada com INVALID_CONVERSATION_SNAPSHOT. A recuperação restaura apenas estado semântico e nunca autoriza, consome confirmação ou retoma execução.

Em 2026-09-04, o limite do Durable Object passou a revalidar todo estado recuperado antes de expô-lo ou aceitar operação: timeline incoerente falha fechada com 409 INVALID_RECOVERED_SESSION_STATE. A prova reproduz estado persistido impossível (RECEIVED para EXECUTING sem transição intermediária), e assegura que não vira resposta 200 nem autorização.

Em 2026-09-05, o conjunto de runtime conversacional, sessão Durable Object, confirmação e execução passou com 21 testes em 5 arquivos, e o typecheck do Agent passou. A validação cobre persistência e reidratação fail-closed, versionamento, referências semânticas, ambiguidade e pendência, TTL de pergunta e confirmação, invalidação por correção, cancelamento, undo restrito a capability, retry seguro, proteção contra corrida e isolamento por tenant/usuário. O Worker já publicado mantém o fluxo em produção; falta apenas um canário específico de reinicialização de infraestrutura, sem reduzir os invariantes cobertos pelos contratos.

Em 2026-09-06, a regressão atual de runtime, sessão Durable Object, roteamento e intenção conversacional passou com 38 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou o runtime e seus bindings. A cobertura continua PARTIAL: ainda faltam o canário específico de recuperação de infraestrutura e uma superfície ampla de mensagens conversacionais.

62. Resultado arquitetural

Ao final do PRD-010, o agente passa a ter uma propriedade fundamental:

continuidade operacional.

Ele não apenas entende uma mensagem.

Ele entende:

o que o usuário acabou de fazer
+
onde o usuário está
+
qual entidade está em foco
+
qual operação está pendente
+
qual foi o resultado anterior
+
o que o usuário está tentando fazer agora

Isso transforma o sistema de um chatbot com ferramentas em um verdadeiro agente operacional contextual.

PRD-011 — Agentic UI Intelligence & Semantic Interaction Layer

O próximo estágio deve fechar uma lacuna importante: até agora definimos como o agente entende e executa ações, mas precisamos definir como ele entende a interface visual e interage semanticamente com ela.

O PRD-011 deverá especificar:

React Application
       │
       ├── Semantic Components
       ├── Semantic IDs
       ├── Forms
       ├── Tables
       ├── Tabs
       ├── Modals
       ├── Actions
       └── Navigation
                │
                ▼
       Semantic Interaction Layer
                │
                ▼
          Agent Tool Runtime
                │
                ▼
             Agent

A ideia central será permitir comandos como:

“Clique naquele botão.”

“Abra a aba de riscos.”

“Preencha isso com os dados que acabei de informar.”

“Mostre os campos obrigatórios.”

“Vá para aquele funcionário.”

“Explique esta seção.”

sem transformar o agente em um robô que depende de coordenadas, seletores CSS frágeis ou inspeção indiscriminada do DOM.

O próximo PRD, portanto, será o contrato entre o Agent Runtime e a aplicação React, definindo o Semantic UI Layer que tornará toda a interface operável pelo agente de forma determinística, segura e extremamente rápida.