agent_platform_oci/specs/SPEC-002-Agent-Runtime.md

SPEC-002 — Agent Runtime

Escopo

O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.

Componentes

Componente	Responsabilidade
Workflow Builder	Compila o grafo LangGraph.
State Manager	Mantém o estado de execução.
Session Manager	Resolve sessão e conversation_key.
Memory Manager	Carrega e persiste histórico.
Checkpoint Manager	Persiste estado LangGraph.
Input Guardrail Node	Executa guardrails de entrada.
Router Node	Decide rota/intent.
Supervisor Node	Decide handoff ou próximo agente quando habilitado.
Agent Node	Executa agente de domínio.
MCP Client/Router	Executa tools por contrato.
RAG Service	Recupera contexto documental.
Output Supervisor	Revisa resposta antes de saída.
Output Guardrail Node	Executa guardrails de saída.
Judge Node	Avalia resposta.
Persistence Node	Persiste mensagens, memória e checkpoint.

State Model

class AgentState(TypedDict, total=False):
    user_text: str
    sanitized_input: str
    response_text: str
    tenant_id: str
    agent_id: str
    channel: str
    session_id: str
    conversation_key: str
    message_id: str
    route: str
    intent: str
    context: dict
    business_context: dict
    tool_arguments: dict
    mcp_tools: list[str]
    mcp_results: list[dict]
    rag_context: str
    rag_metadata: dict
    guardrails: list[dict]
    judges: list[dict]
    metadata: dict
    errors: list[dict]

Workflow

flowchart TD
    A[start] --> B[input_guardrails]
    B --> C[routing_decision]
    C --> D[agent_execution]
    D --> E[output_supervisor]
    E --> F[output_guardrails]
    F --> G[judge]
    G --> H[persist]
    H --> I[end]
    C --> J[handoff]
    J --> C

Nós

Nó	Entrada	Saída
input_guardrails	user_text, context	sanitized_input, guardrails
routing_decision	sanitized_input, business_context	route, intent, mcp_tools
agent_execution	state completo	response_text, mcp_results, rag_metadata
output_supervisor	response_text	response_text revisado
output_guardrails	response_text	response_text, guardrails
judge	response_text, evidências	judges
persist	state completo	checkpoint, memória, mensagens

Router

routing:
  mode: router
  fallback_agent: billing_agent
  enable_llm_router: false
  intents:
    billing_invoice_explanation:
      route: billing_agent
      keywords:
        - fatura
        - cobrança
        - boleto
      mcp_tools:
        - consultar_fatura
        - consultar_pagamentos

Supervisor

supervisor:
  enabled: true
  profile: supervisor
  max_turns: 5
  handoff_enabled: true
  fallback_route: support_agent

Memory

Provider	Uso
memory	Execução local e testes.
sqlite	Desenvolvimento local persistente.
mongodb	Checkpoint e histórico em ambiente distribuído.
autonomous	Produção com Oracle Autonomous Database.

Checkpoints

Checkpoint contém:

{
  "conversation_key": "default:telecom_contas:session-001",
  "checkpoint_id": "ckpt-001",
  "state": {},
  "pending_writes": [],
  "created_at": "2026-06-19T12:00:00Z"
}

Formato entregue ao LangGraph:

pending_writes: list[tuple[str, str, object]]

Business Context

business_context:
  customer_key: "11999999999"
  contract_key: "3000131180"
  interaction_key: "301953872"
  account_key: null
  resource_key: null
  session_key: "session-001"
  metadata:
    source_channel: web

Ordem de Prioridade dos Dados

1. tool_arguments
2. business_context
3. context
4. session.metadata
5. state
6. extração complementar do texto

MCP Integration

flowchart LR
    AgentNode --> ToolList[mcp_tools]
    ToolList --> Mapping[mcp_parameter_mapping.yaml]
    Mapping --> MCP[MCP Gateway/Router]
    MCP --> Result[mcp_results]

RAG Integration

rag:
  enabled: true
  namespace_strategy: agent_id
  top_k: 5
  profile_generation: rag_generation

Eventos

Evento	Descrição
runtime.started	Execução iniciada.
runtime.session.loaded	Sessão carregada.
runtime.memory.loaded	Memória carregada.
runtime.checkpoint.loaded	Checkpoint carregado.
runtime.route.selected	Rota selecionada.
runtime.agent.started	Agente iniciado.
runtime.agent.completed	Agente concluído.
runtime.persist.completed	Persistência concluída.
runtime.failed	Falha controlada.

Erros

Código	Condição	Tratamento
RUNTIME_INVALID_REQUEST	GatewayRequest inválido	422
RUNTIME_ROUTE_NOT_FOUND	Nenhuma rota elegível	fallback ou resposta controlada
RUNTIME_CHECKPOINT_ERROR	Falha em checkpoint	retry ou stateless conforme config
RUNTIME_MEMORY_ERROR	Falha em memória	retry ou resposta controlada
RUNTIME_AGENT_ERROR	Falha no agente	NOC + fallback
RUNTIME_TIMEOUT	Timeout geral	resposta controlada

Requisitos Não Funcionais

Categoria	Requisito
Disponibilidade	Componentes deployáveis expõem /health e /ready.
Escalabilidade	Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos.
Segurança	Segredos são fornecidos por secret store ou Kubernetes Secrets.
Observabilidade	Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id.
Auditabilidade	Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis.
Portabilidade	Execução suportada em local, Docker Compose e Kubernetes/OKE.
Configuração	Comportamento variável é controlado por .env e YAML versionado.

Critérios de Aceite

• Runtime recebe GatewayRequest validado.
• State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
• Input guardrails executam antes do roteamento.
• Router ou Supervisor seleciona rota.
• Agent Node executa sem acessar payload bruto de canal.
• MCP é acessado por contrato.
• RAG é acessado por serviço reutilizável.
• Output guardrails executam antes da resposta final.
• Judges geram JudgeResult.
• Memória e checkpoint são persistidos conforme provider.
• Erros geram NOC e resposta controlada.

Glossário

Termo	Definição
Agent Platform	Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais.
Agent Framework	Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários.
Agent Runtime	Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida.
Agent Gateway	Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes.
Channel Gateway	Aplicação ou módulo de normalização de payloads de canais para GatewayRequest.
AI Gateway	Aplicação de governança, roteamento e abstração de chamadas LLM/embedding.
MCP Gateway	Aplicação de governança e roteamento de tools MCP.
Evaluator	Camada de avaliação online/offline, regressão e certificação.
Business Context	Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key.