Agentes (Arquitetura Unificada)

Clinical Corvus usa agentes especializados dentro de um control plane próprio. O objetivo é produzir saídas revisáveis e manter políticas, budgets, estado, evidência e formato de resposta sob responsabilidade do Corvus.

Visão Geral da Arquitetura

O Corvus coordena o fluxo clínico. BAML fornece funções estruturadas, e Langroid participa de caminhos seletivos de agente ou tarefa quando preserva os mesmos contratos:

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (UI)                            │
│  AgentQueryInterface │ CorvusAgentPanel │ SmartClipboard        │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP/SSE
┌─────────────────────────────▼───────────────────────────────────┐
│                     API Layer (FastAPI)                         │
│  /api/agents/tasks/* │ /api/agents/chat │ /api/clipboard/*    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                  Agent Orchestration Layer                      │
│  TaskOrchestrator │ BudgetManager │ ProblemProfile              │
│  ClinicalQueryProfile │ EscalationPolicy │ StateOwnershipPolicy  │
└─────────────────────────────┬───────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌─────────────────┐   ┌─────────────────┐
│  CDA          │   │  Compass        │   │  CRA            │
│  (Raciocínio  │◄─►│  Controller     │◄─►│  (Pesquisa      │
│   Clínico)    │   │  Plan/Verify/   │   │   Clínica)      │
│               │   │  Pivot/Stop     │   │                 │
└───────┬───────┘   └─────────────────┘   └────────┬────────┘
        │                                           │
        ▼                                           ▼
┌───────────────┐                         ┌─────────────────────┐
│  BAML Layer   │                         │  Search Policy      │
│  (Prompts &   │                         │  Service            │
│   Schemas)    │                         │  Tier 1: RAG+PubMed │
│               │                         │  Tier 2: SearXNG    │
│               │                         │  Tier 3: Paid APIs  │
└───────────────┘                         └─────────────────────┘
        │                                           │
        ▼                                           ▼
┌───────────────┐                         ┌─────────────────────┐
│  Patient      │                         │  Hybrid RAG         │
│  Context      │                         │  BM25 + Vector +    │
│  Manager      │                         │  HyDE + Reranking   │
└───────────────┘                         └─────────────────────┘

Componentes Principais

Clinical Discussion Agent (CDA)

O agente principal de interação com o clínico. Responsabilidades:

• Raciocínio clínico: síntese do caso, discussão de diagnóstico diferencial
• Gestão da conversa: mantém contexto através de turns
• Decisão de escalação: decide quando chamar o CRA ou pedir clarificação
• Fast path: caminho leve para perguntas de beira de leito já formadas
• Structured answer: produz respostas estruturadas com evidências e incerteza

O CDA usa clinical_query_profile.py para classificar cada request em dimensões reutilizáveis (task_type, decision_horizon, instability_domains, context_sufficiency, answer_shape), garantindo alinhamento entre componentes.

Clinical Research Agent (CRA)

Agente especializado em recuperação de evidências. Acionado quando o CDA identifica necessidade de pesquisa:

• Pesquisa federada: consulta simultânea em PubMed, Europe PMC, OpenAlex, Lens
• Busca híbrida local: BM25 + vector search no corpus local via Hybrid RAG Service
• Tiered search policy: Tier 1 (gratuito), Tier 2 (auto-hospedado), Tier 3 (APIs pagas com opt-in)
• Query shaping: queries adaptadas por provedor (dialetos diferentes para PubMed vs OpenAlex)
• Bounded retrieval: caminhos de recuperação controlados para evitar expansão excessiva
• Evidence ledger: registro de evidências admitidas, rejeitadas, fracas, contraditórias
• Query rewrite: uma tentativa de reescrita com diagnóstico de falha antes de fallback

Compass Controller

Orquestra o loop de raciocínio do CDA seguindo o padrão Plan/Verify/Pivot/Stop:

• Planejar: o que é necessário para responder? (diretriz, ferramenta, conhecimento)
• Verificar: o rascunho atende padrões de segurança e evidência?
• Pivotar: se evidência insuficiente, delegar ao CRA ou pedir clarificação
• Parar: encerrar quando há suporte suficiente ou budget esgotado

O Compass usa BudgetManager para controlar custos de tokens e EscalationPolicy para governar quando escalar.

Task Orchestrator

Gerencia o ciclo de vida de tarefas multi-agente:

• Submit/Pattern: POST para submissão, GET para polling de status
• Async execution: tarefas rodam em background com Redis store
• Dynamic step injection: passos adicionais podem ser injetados durante execução
• Response shaping: formata a resposta final com todos os metadados necessários
• State ownership: verifica autoridade antes de mutar estado do episódio
• HITL support: ferramenta de pausa para revisão humana no fluxo

Outros Componentes

• ProblemProfile: classifica o problema clínico (budget, worker, estratégia)
• BudgetManager: controla limites de tokens por tarefa
• EscalationPolicy: governa quando escalar, parar ou pedir clarificação
• SubagentResponder: delega tarefas a subagentes especializados
• CriticAgent: revisa respostas antes de apresentar ao clínico
• DeliberationManager: gerencia deliberação entre múltiplas opções
• TopicShiftDetector: detecta mudança de tópico na conversa via embeddings
• AdaptationService: ajusta políticas baseado em feedback do usuário
• AgentMemoryService: gerencia memória de longo prazo (LTM) e contexto
• WorkingMemoryManager: memória de trabalho por turno

Camada BAML

BAML (Browse-Agnostic Macro Language) define prompts de alta fidelidade e outputs estruturados:

• agents.baml: IntentAnalysis, AnalyzeMCQAnswer, CritiqueResponse
• research_assistant.baml: GenerateEvidenceAppraisal, FormulatePICOQuery
• translator.baml: tradução de outputs para PT/EN

Fluxo: editar .baml → baml-cli generate → backend consome cliente Python tipado.

BYOK Injection

O sistema injeta credenciais de API do tenant no runtime BAML via services/baml_env_overrides.py, permitindo que cada tenant use suas próprias chaves (OpenAI, Anthropic, etc.).

Contrato de Resposta

Todas as respostas dos agentes seguem o contrato AgentResponse (normalizado via agentResponseResolvers.ts no frontend):

• primary_answer: resposta principal
• research_telemetry: modo de execução, evidence ledger, missing information
• evidence: todas as evidências com IDs, admitted/rejected counts
• safety: flags de segurança, review recommended
• state: answer_state (ready/partial/insufficient_evidence/blocked/review), provenance
• citations: referências com título, URL, data, journal

Estados de Resposta

O sistema expõe estados de resposta explícitos:

Estado	Significado
ready	Resposta com evidência adequada
partial	Resposta parcial com incerteza declarada
insufficient_evidence	Evidência insuficiente para responder
blocked	Request bloqueado (fora do escopo de beta)
review	Requer revisão clínica antes de usar

Governança e Segurança

• PHI Egress Gate: filtra conteúdo que pode sair do backend
• StateOwnershipPolicy: verifica autoridade antes de mutar estado
• EvaluationModeGuard: separa modo de avaliação de produção
• HITL Pause Tool: pausa explícita para revisão humana no fluxo
• Audit logging: todas as ações são logadas com hash de identificadores