Você pode testar todas as rotas do Advisor V4 na documentação interativa.

O omniAdvisorV4 é o advisor de próxima geração do Tolky. Diferente do Decision Advisor, que só enxerga decision chains, o V4 analisa as quatro camadas que configuram o comportamento de um avatar — e aponta a entidade exata que precisa ser corrigida, propõe a correção e re-verifica sem precisar rodar o advisor inteiro de novo.

​
As quatro camadas

CamadaO que configura
envelopeIdentidade, tom, proibições, capabilities declaradas (avatars.prompt_envelop)
decision chainsQuando e como acionar automações (decision_chains, options, agents, versions)
chunksO que o avatar sabe pelo RAG (chunks do dataset vinculado)
smart tagsCaptura de intenções via tags semânticas

Quando um problema acontece, a causa raramente está em uma camada isolada. “O bot respondeu fora do tom” pode ser envelope ambíguo, chunk em inglês, chain que ignorou response_style, ou qualquer combinação.

​
Dores que o V4 resolve

#DorComo resolve
1Issue aponta problema mas usuário não sabe onde está (envelope? qual chunk? chain?)Cada issue registra as entidades exatas do banco via advisor_issue_entities (table + recordId + path)
2Não dá para conduzir a IA até onde corrigirproposeFixForIssueV4 devolve changeSet[] com {table, recordId, path, proposedValue} — alvo preciso
3Para verificar fix, precisa rodar o advisor inteiro de novoverifyIssueV4 compara via LLM o snippet persistido com o conteúdo atual das entidades vinculadas
4Chunks envolvidos em uma issue não aparecem no frontadvisor_issue_entities registra table_name='chunks' + chunk_id para cada chunk relevante
5Problemas relacionais (duas camadas certas mas incompatíveis) não têm representaçãoEscopo cross + role contradicts_with expressam relações N:N entre camadas

​
Escopos

'envelope' | 'chunks' | 'decision' | 'smart_tag' | 'cross'

cross é reservado para issues que envolvem mais de uma camada simultaneamente (ex.: envelope promete algo que nenhuma chain implementa).

No body de /v4/run, omitir scopes (ou enviar []) executa apenas decision. Para todos os escopos omni, envie literal JSON null.

​
Ciclo de vida de uma issue

[detect]  ──→  advisor_issues_v2  (status=open, verification_status=unverified)
                      │
                      ↓ front exibe issue com links para as entidades
                      │
                      ↓ usuário (ou copilot) edita envelope / chunk / chain
                      │
[verify]  ──→  /v4/verifyIssue   → verification_status ∈ {confirmed_fixed | still_present | partial | inconclusive}
                      │
[propose] ──→  /v4/proposeFix     → changeSet[] (read-only, nada é mutado)
                      │
[resolve] ──→  /v4/resolveIssue   → status='resolved', resolved_at=now()
                                    (só executa se verify confirmar fix)

Cada issue em advisor_issues_v2 carrega:

  1. Qual investigador a gerou (investigator_name) — proveniência do diagnóstico.
  2. Quais entidades do banco estão envolvidas (via advisor_issue_entities) — front navega direto, copilot tem alvo de correção.
  3. Qual feature do produto se relaciona (entidade com role='feature_hint' e table_name='tolky_features').
  4. O raciocínio que levou à issue (hypotheses JSONB) — auditável, citável na proposta.
  5. Sessões de diálogo ST (advisor_issue_st_sessions) — rastreia quais conversas tocaram a issue.

​
Arquitetura — cluster de Actions

O V4 é um cluster de Actions executado pelo motor de Sequential Thinking com plano prebuilt (custo determinístico, sem replanejamento):

resolvers → scanners → tracers → enrichers → synthesizers
                                     ↕
                                  terminals
                             (skills por-issue)
                                     ↕
                                 validators
                          (manutenção do ciclo de vida)
CategoriaPapel
resolversCarregam universo de dados do avatar e contexto da issue. Sem LLM pesado.
scannersRanqueadores de candidatos: produzem sítios de interesse para os tracers (LLM leve).
tracersInvestigadores LLM com schema fechado. Cada tracer recebe janela estreita e devolve insights[] com entidades.
enrichersAnexam referências precisas: path exato, citações de chunks, agentes referenciados, features.
terminalsSkills por-issue: verifyIssueV4, proposeFixForIssueV4, resolveIssueIfFixedV4.
synthesizersCompilam insights → issues, deduplicam contra o aberto, persistem em transação.
validatorsManutenção do ciclo de vida sem issueId: dismissa órfãs, enfileira reverify, reconcilia inconsistências.

​
Resiliência — tier por action

  • essential (default): falha após retries → ABORT → pipeline interrompida. Engloba setup, scanners, entityPathResolver, synthesizer chain, terminals e validators.
  • advisory (15 tracers + 3 enrichers opcionais): falha após retries → SKIP → step marcado como SKIPPED, pipeline continua.

Falhas LLM em tracers são absorvidas antes de virarem FAILED no motor:

  • Cap pre-flight de prompt (60 000 chars): prompts maiores pulam a chamada e retornam { insights: [], skipped: true, reason: 'prompt_too_large: ...' }.
  • Try/catch após IACall: exceção remanescente vira { insights: [], skipped: true, reason: 'llm_failed: <msg>' }.

compileAdvisorReportV4 enumera tracers pulados no summary final — usuário enxerga a degradação explicitamente.

​
Endpoints

  • Run — executa o pipeline completo para um avatar (overview do diagnóstico)
  • Verify Issue — re-verifica uma issue específica sem rodar o advisor inteiro
  • Propose Fix — gera changeSet de correção para uma issue (read-only)
  • Resolve Issue — verifica e marca como resolvida se já estiver corrigida

​
Coexistência com V1

O V4 não substitui o V1: decisionAdvisorV2, chunkAdvisor e smartTagAdvisor continuam escrevendo em advisor_issues V1 sem alteração. Reports V4 são identificados por advisor_reports.version='v4' e gravam em advisor_issues_v2.

Insight por DemandaRun (Advisor V4)