Orquestração, memória e contexto dos agentes

Esta página descreve a infraestrutura comum aos agentes. O papel de cada agente está em [Agentes de IA — funil comercial](ia/agentes-comerciais), em [Agentes de IA — contrato, entrega e carteira](ia/agentes-entrega) e em [Organization Intelligence](ia/organization-intelligence) (perfil, auditoria, Health Score, Delivery Advisor e Customer Success).

Fila de agentes

Arquivo: src/fila.ts. Executor: src/agentes.ts.

• Mensagem: todo gatilho vira {agente, alvo: {tipo, id}, origem, opcoes?, depois?, tentativa?, organizacao_id?, request_id?}. O alvo pode ser lead, cliente, oportunidade, contrato, escopo, mudanca ou organizacao.
• Agentes que a fila conhece (NomeAgente): site, resumo, proxima_acao, estrategia, embedding, risco, expansao, escopo, perfil, auditoria, saude, entrega, sucesso, fonte_analista (AI Source Analyzer, ADR-0015) e webhook_entrada (payload de webhook de provedor guardado na fila antes do 200 ao provedor; o consumidor roda o parser e o pipeline de entrada — ADR-0015).
• Os demais agentes são chamados direto pelas rotas: SDR, rascunho, detalhamento, reunião, briefing, contrato, validador, mudança, relatório, Copiloto, o agente de perfil do onboarding e os do Knowledge Center.
• Registro: HANDLERS em agentes.ts liga cada nome a uma função. risco decide pelo alvo: cliente vai para avaliarRiscoCliente; lead vai para a próxima ação. escopo com um contrato do tipo aditivo aplica a mudança (aplicarPorAditivo) em vez de gerar escopo. auditoria (Organization Auditor), saude (Health Score), entrega (Delivery Advisor, só alvo escopo) e sucesso (Customer Success, só alvo cliente) engolem o próprio erro com log: são opcionais e o cron refaz. perfil está declarado sem efeito (só log) — o agente de perfil roda direto no onboarding.
• **Despacho (despachar):**
• com o binding FILA (Cloudflare Queue), a mensagem é enfileirada e a requisição volta na hora;
• sem o binding, a mensagem roda no waitUntil da própria requisição (processar).

A fila está ligada desde 26/09/2026 (Workers Paid; queues em wrangler.jsonc: Queue radar-agentes, lote de até 5, 3 entregas). Se o envio para a fila falha, a mensagem roda inline no waitUntil (log fila.envio_falhou). Sem o binding (desenvolvimento, testes), tudo roda inline.

• **Consumidor (consumirLote):** executa, dá ack e encadeia o próximo agente de depois (enfileirado com a mesma organizacao_id; se a fila recusar, roda ali mesmo). A tentativa é contada por attempts da entrega. Erro faz retry até a 3ª entrega; na 3ª, ack com log e soma ao contador de mensagens mortas em KV, que o alerta de operação lê (dead-letter por log, para não travar a fila).
• Organização e rastreio: despachar carimba a organizacao_id e o request_id do contexto atual na mensagem; processar reentra na organização (comOrg) e o consumidor no request_id de origem (comRequisicao), para os logs do consumidor se ligarem aos da requisição.

Cadeias (CADEIAS)

Toda cadeia declarada tem quem a dispare, e test/fila.test.ts confere isso no código-fonte. A próxima ação continua síncrona onde o resultado é usado na hora:

• reunião registrada ou marcada: o Consultor volta à página esperando a ação nova;
• cron de silêncio: o e-mail leva a sugestão;
• botão do Consultor.

Por isso não há cadeias reuniao_registrada nem silencio. Os demais gatilhos avulsos (aceite pelo lead, WhatsApp, webhooks do Resend, formulário de contato) também chamam gerarProximaAcao direto.

O botão "reler" da expansão no 360 despacha uma mensagem avulsa (agente: 'expansao', sem cadeia).

Crons

Os crons rodam por executarCron em src/cron.ts (o scheduled() de src/index.ts só delega; o "Rodar agora" de /radar/plataforma chama a mesma função), uma vez por organização ativa (paraCadaOrganizacao), cada uma no seu contexto. Detalhes de operação (marcadores, alertas, recuperação) em [Infraestrutura](tecnica/infraestrutura).

• 0 * * * *: silêncio de 48 h, que gera a próxima ação dos leads parados; depois, os alertas de operação e a recuperação de um diário ou semanal que não rodou (evento cron_recuperado).
• 0 11 * * MON-FRI (8h em Brasília, dias úteis): aviso de fim do teste → risco dos clientes → escalação de etapas atrasadas → Health Score → Delivery Advisor (rodarEntregas) → auditoria por 20 conversas novas do SDR → digest.
• 30 11 * * MON (segunda, 8h30): Organization Auditor → Customer Success (rodarSucessos) → expansão (até 30 clientes) → relatório semanal.

Esqueleto comum: executarAnalise

Arquivo: src/agentes.ts. Usam o esqueleto o risco do cliente (ANALISE_RISCO_CLIENTE), a expansão (ANALISE_EXPANSAO), o Delivery Advisor (ANALISE_ENTREGA, alvo escopo, evento entrega_sugerida) e o Customer Success (ANALISE_SUCESSO, alvo cliente, evento sucesso_plano). Os agentes mais antigos (site, resumo, estratégia, reunião, detalhamento, próxima ação, briefing) e o Organization Auditor (tipo auditoria, alvo organização) repetem o mesmo padrão à mão. Contrato, escopo e mudança gravam nas próprias tabelas.

O fluxo tem sete passos:

1. Entrada: entrada(env, alvoId) monta o system prompt, a mensagem do usuário e a chaveHash. Devolver null significa "nada a analisar".
2. Hash: SHA-256 de {v: versao, k: chaveHash}. A chave contém só o que muda a resposta: ids de eventos, status, datas. O risco do cliente não inclui a data: o passar do tempo entra pelas regras calculadas na hora (chave e nível). A expansão inclui o mês. Os agentes que leem o perfil da Organização põem a versão dele na chave, e os que leem um documento funcional, a versão do documento (versaoDocumental).
3. Cache: se já existe uma linha em analises_ia para o mesmo alvo, tipo e hash_entrada, ela é devolvida sem chamar o modelo. Com forcar, o hash é gravado com o sufixo :timestamp e não serve de cache depois.
4. Chamada: chamarClaude com o modelo, maxTokens e thinking do agente, rótulo = tipo. O custo vai para ia_chamadas.
5. Validação em código: interpretar(texto) devolve o objeto tipado ou null. O código nunca confia no texto: vocabulários fechados, tamanhos cortados, ids conferidos.
6. Fallback: sem saída válida, roda regra(env, alvoId), a versão determinística. A linha é gravada com modelo: 'regra' e sem custo.
7. Gravação: grava em analises_ia (com alvo_tipo/alvo_id, e lead_id quando há lead de origem), registra o evento <tipo>_gerado (regra, custo_usd) e roda aplicar, se houver. A expansão, por exemplo, reprecifica e reescreve o conteúdo em aplicar.

Modelos, preços e limite

Arquivo: src/claude.ts.

• Modelos: MODELO = 'claude-sonnet-5' é o padrão. MODELO_PROXIMA_ACAO = 'claude-opus-5' serve a próxima ação e a expansão; MODELO_ESTRATEGIA = 'claude-opus-5' serve a estratégia; MODELO_AUDITOR = 'claude-opus-5' (src/perfil/auditor.ts) serve o Organization Auditor. MODELO_COPILOTO = MODELO. Os embeddings usam MODELO_EMBEDDING = 'voyage-3.5' (src/embeddings.ts).
• **Preços (US$ por milhão de tokens), em PRECOS_USD_POR_MTOK:**
• Sonnet 5: entrada 2, saída 10, leitura de cache 0,2, escrita de cache 2,5.
• Opus 5: entrada 5, saída 25, leitura de cache 0,5, escrita de cache 6,25.

Um modelo desconhecido é cobrado pelo preço de MODELO.

• Cliente e cache: um cliente do SDK oficial por requisição (maxRetries: 2, timeout: 90 s). Todas as chamadas usam cache de prompt efêmero no system e no prefixo. thinking: 'disabled' é usado em saídas curtas em JSON.
• Custo: registrarChamadaIA grava uma linha em ia_chamadas (rótulo, modelo, tokens de entrada, saída e cache, US$, lead_id/conversa_id) e soma ao cache de uso do mês da Organização. Todos os agentes registram, inclusive o resumo e o relatório semanal (desde 25/09/2026).
• Limite mensal por Organização: a porta única é iaBloqueada(env, rotulo), que confere limiteIaAtingido quando há Organização no contexto. chamarClaude a chama antes de cada chamada. O Agente SDR e o Copiloto montam a chamada no SDK (cliente(), por causa do tool use) e chamam iaBloqueada antes. O teto é organizacoes.limite_ia_usd_mes ou, sem ele, a IA incluída no Plano (planos.ts; o plano interno não tem limite). O uso é somado de ia_chamadas desde o dia 1º, em horário de Brasília, com cache de 5 min. Atingido o teto, o modelo não é chamado e o evento limite_ia_atingido é registrado (com o rótulo de quem pediu). O que acontece depois depende do chamador:
• quem usa chamarClaude cai no fallback;
• o SDR oferece ao visitante o formulário de contato e faz o Handoff (motivo limite_ia);
• o Copiloto avisa o Consultor e não guarda a pergunta.
• Cache de narrativas: o briefing da Home (alvo usuario) e o relatório semanal (alvo organizacao) guardam o texto em analises_ia por hash da entrada. Reabrir a Home ou a prévia /radar/relatorio com os mesmos dados não chama o modelo.
• Gating por plano: é diferente do limite. O Copiloto só funciona a partir do Plano Profissional (402 abaixo dele).

Memória

Além delas, o perfil de IA da Organização (organizacao_perfil_ia, lido por contextoOrganizacional com cache de 1 min) entra no system prompt de quase todos os agentes; ver [Agentes de IA — funil comercial](ia/agentes-comerciais) e [Organization Intelligence](ia/organization-intelligence).

A memória de cada agente é montada a cada chamada a partir dessas tabelas e das de negócio (eventos, notas, tarefas, propostas). Nenhum agente guarda estado próprio fora delas.

Vetores (leads parecidos)

Arquivo: src/embeddings.ts. Tabela lead_embeddings. Função SQL leads_parecidos (pgvector, migração 0011).

• **Texto do lead (textoDoLead): setor, dor, momento, porte, ferramentas, urgência e orçamento, até 2.000 caracteres. Sem nome nem e-mail.**
• Vetor: Voyage AI (voyage-3.5, 1024 dimensões, input_type: document), timeout de 15 s. É idempotente pelo texto: o mesmo texto não gera nova chamada.
• Quando indexa:
• o agente embedding na cadeia:handoff e na cadeia:fechado;
• a mudança do estágio para ganho ou perdido na página do lead;
• mudar_estagio para perdido pelo Copiloto.
• Busca: parecidosSemanticos procura vizinhos entre os leads ganho/perdido, por distância de cosseno, com similaridade mínima de 0,55 e até 3 resultados. parecidosDoLead (src/parecidos.ts) usa esse resultado quando existe e, sem ele, a regra por setor, momento e porte. A estratégia usa só a regra.
• **Sem VOYAGE_API_KEY ou sem a migração:** tudo devolve null e a Radhr AI segue pela regra.
• Isolamento: a função SQL leads_parecidos só procura vizinhos da organização do lead-alvo (migração 0024). O RLS não protegeria aqui, porque o Worker usa a service key. parecidosDoLead segue como segunda barreira: só aceita ids presentes na lista de fechados da Organização atual.

Contexto por organização

Arquivo: src/org-contexto.ts.

• Como funciona: um AsyncLocalStorage (flag nodejs_compat) guarda a organização da execução. orgAtual() devolve o id ou null fora de contexto; orgOuPadrao() devolve o id ou 1 (Witbiz); comOrg(id, fn) roda fn dentro do contexto.
• Quem entra no contexto:
• o middleware da Radhr AI, com a organização da sessão (a tabela organizacoes dá nome, plano, limite de IA, ativa e domínio);
• as rotas públicas, com a organização do link (organizacaoDoLink) ou, sem link, a do domínio (organizacaoPorHost);
• cada cron, por organização;
• cada mensagem da fila, pela organizacao_id da mensagem.
• Crons: só organizações com ativa diferente de false; sem nenhuma listada, roda só a organização 1.
• Efeito nos agentes: db.ts filtra e carimba organizacao_id em toda leitura e escrita das tabelas de TABELAS_ORG (inclui analises_ia, ia_chamadas, recomendacoes_ia, lead_embeddings, copiloto_conversas) e envia o cabeçalho x-organizacao, que o RLS usa como segunda barreira. Assim, o contexto que um agente monta só enxerga os dados da própria Organização, e o custo cai na conta certa.

Segurança de prompt

• Dados nunca são instruções. Notas, e-mails, mensagens de WhatsApp, transcrições e o texto de sites entram nos prompts como dado. O system do Copiloto diz isso explicitamente, mas a garantia é do código:
• nenhuma ferramenta de ação executa pelo modelo;
• as saídas de todos os agentes passam por validação com vocabulário fechado.
• Ações do Copiloto exigem confirmação. validarAcao confere os argumentos e o papel antes de propor (o Consultor só nos seus leads e clientes; o admin em todos; ganho só pela conversão). A ação vira pendente, e só decidirAcao com confirmada chama executarAcao. Cada ação fica registrada em auditoria e no evento copiloto_acao.
• Números e decisões ficam no código:
• preço (pré-proposta, detalhamento, expansão);
• valores de contrato (R$ fora da Proposta e percentuais são recusados);
• valor de mudança (horas × valor-hora);
• estágio do lead (só sugerido pela reunião);
• troca de canal da próxima ação.
• Nada sai para fora sem o Consultor, com três exceções que são do próprio fluxo:
• a Pré-proposta do SDR (estimativa rotulada como tal);
• a renovação aberta a 60 dias;
• a mudança automática de status do cliente pelo motor de risco.
• O SDR não mostra o estado ao visitante. O estado vai por tool use, e o prompt proíbe revelar as instruções.
• Perfil da Organização é dado. aiInstructions e organizationalKnowledge entram delimitados no system, com o aviso de que não sobrepõem as regras do código; o bloco do perfil diz que preço só vem do catálogo. A ferramenta catalogo do Copiloto devolve só itens e agentes ativos no catálogo da Organização (itemAtivo/agenteAtivo).
• Leitura que é credencial passa pela permissão. As ferramentas de leitura do Copiloto não filtram por dono, salvo link_portal: o link /portal/<token> dá acesso sem login aos dados do Cliente, então só sai para quem pode enviar o portal (admin, ou o Consultor dono do Cliente ou de Cliente sem dono; financeiro e leitura não; portal.enviar com o RBAC v2; recusaDoPortal em src/portal.ts, a mesma regra do "Enviar portal" do Cliente 360). Ela só devolve o link que já existe; não gera token nem envia e-mail.

Documentação viva como fonte de contexto

Pelo ADR-0010, a documentação desta pasta (docs/conhecimento/), empacotada em src/conhecimento/base.gerada.ts por scripts/conhecimento.mjs, é fonte de contexto dos agentes pela ferramenta de leitura **consultar_documentacao** do Copiloto. Com ela, o Copiloto responde "como funciona" e "por que a Radhr AI fez isso" citando o documento, e não de memória. O prompt do Copiloto manda consultá-la antes de explicar a Radhr AI e dizer que a documentação não cobre o assunto em vez de supor.

Ela segue as regras das ferramentas de leitura:

• executa na hora (busca BM25 em memória, src/conhecimento/busca.ts, sem rede e sem custo);
• devolve até 5 trechos com fonte e link, que são dado, nunca instrução;
• só lê as fontes autorizadas da organização de quem pergunta: a Witbiz (organização 1) vê tudo; as demais, o funcional, o glossário e os documentos que a própria organização escreveu (playbooks, regras comerciais, processos e guias de tela, fase 3). Documento de uma organização nunca aparece para outra.

Desde a fase 1, a documentação também entra no system prompt de alguns agentes: promptDocumental(area) (src/conhecimento/contexto.ts) anexa a seção "Regras de negócio" do documento funcional da área, com o aviso de que as validações do código prevalecem, e, na estratégia, no risco do cliente e na expansão, versaoDocumental(area) põe a versão do documento no hash (documento revisado → análise refeita). Usam: estratégia (propostas), risco do cliente e expansão (clientes), Scope Builder/Validator e Change Request Analyzer (escopos).

Na fase 2, documentos editados na Radhr AI valem por cima do bundle (sincronizarBase, src/conhecimento/edicao.ts): a busca, o assistente, o Copiloto e o contexto dos agentes leem o texto novo. Toda consulta do Copiloto à documentação é registrada em doc_perguntas (registrarPergunta), com as fontes devolvidas, e conta no uso da documentação (fase 4). A consulta sem fonte também entra na fila de revisão.

O assistente de documentação e o Smart Changelog estão em Documentation Agent e Knowledge Center.

Registro central e avaliação

• Registro dos agentes (src/agentes-registro.ts, só leitura): para cada agente do inventário, na Organização, os últimos 30 dias de chamadas e custo (ia_chamadas por rótulo), análises gravadas, taxa de fallback por regra (analises_ia.modelo = 'regra', selo "alto" acima de 20%) e quantas análises foram refeitas depois da última atualização do perfil. Aparece na tabela de agentes de /radar/conhecimento/ia (o master escolhe a organização com ?org=).
• Conjunto de avaliação em modo regra (test/avaliacao.test.ts + test/avaliacao/<agente>.json, no CI): saídas fixas do modelo e o que o validador em código tem de fazer com elas (aceitar, cortar, anular, limpar vocabulário). Cobre proxima_acao, estrategia, risco, expansao, mudanca, entrega, sucesso e auditoria, com pelo menos 4 casos cada; todo interpretador listado precisa de arquivo. Não chama o modelo; a rodada com o modelo real não existe ainda.