Você pode testar esta rota diretamente em nossa documentação interativa.

Cria um sequential_thinking_sessions, injeta stSessionId no contexto e executa o cluster de Actions com plano prebuilt. Devolve o conjunto de issues criadas/atualizadas no run com entidades enriquecidas, hints e rewrites.

​
Endpoint

POST /api/externalAPIs/public/advisor/v4/run

​
Parâmetros

hostId
string (UUID)

ID do host. Obrigatório quando hostSlug (ou alias) não é fornecido.

hostSlug
string

Slug do host. Aliases aceitos: host_slug, slug. Resolvido para hostId server-side.

avatarId
string (UUID)

ID do avatar. Quando informado, valida server-side que pertence ao hostId (404 caso contrário).

scopes
array de string | null

Camadas a analisar. Valores válidos: "envelope", "chunks", "decision", "smart_tag", "cross".

  • Omitido ou [] (ou só strings vazias) → apenas decision.
  • Literal JSON null → todos os escopos omni (decision, envelope, chunks, smart_tag).
model
string

Modelo LLM principal dos tracers.

provider
string

Provider LLM principal dos tracers.

compileModel
string

Modelo LLM usado pelo compileAdvisorReportV4 (synthesizer final).

compileProvider
string

Provider LLM do synthesizer final.

sanitizeModel
string

Modelo LLM usado pelo sanitizeAdvisorIssuesV4.

sanitizeProvider
string

Provider LLM do sanitizer.

completionTimeoutMs
number

Timeout em milissegundos para cada chamada LLM individual. Deve ser positivo.

loopGuardDurationMs
number

Janela de proteção do loop-guard do motor sequentialThinking. Deve ser positivo.

cooldown
boolean
default: "false"

Quando true, pula o run se o cooldown anti-flood estiver ativo para esse host. Só liga com true literal — qualquer outro valor é tratado como false.

​
Exemplo

curl -X POST {{BASE_URL}}/api/externalAPIs/public/advisor/v4/run \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "hostId": "1754b7e6-dbd7-4ca3-a843-7f06fad4e4c0",
    "avatarId": "984c2dee-4f81-4fdf-b299-88baa0be86df"
  }'

​
Resposta

{
  "advisorReportId": "f1a2b3c4-...",
  "issuesCreated": 4,
  "issuesEnriched": 4,
  "issuesKept": 12,
  "issuesResolved": 1,
  "summary": "Encontrados 4 problemas novos. Tracers pulados: envelope_tone (prompt_too_large).",
  "stSessionId": "9c8d7e6f-...",
  "scopesCovered": ["decision", "envelope", "chunks", "smart_tag"],
  "issues": [
    {
      "id": "...",
      "scope": "envelope",
      "snippet": "O avatar promete falar inglês mas...",
      "problemDescription": "Envelope declara fluência em inglês, mas não há chunks nem chains correspondentes.",
      "recommendation": "Remover claim de inglês ou adicionar conteúdo.",
      "verificationStatus": "unverified",
      "entities": [
        {
          "tableName": "avatars",
          "recordId": "984c2dee-...",
          "path": "prompt_envelop.identity.languages",
          "role": "primary",
          "originalText": "...",
          "breadcrumb": ["envelope", "identity", "languages"]
        }
      ],
      "entityNetworks": { },
      "hints": [],
      "rewrites": []
    }
  ],
  "total": 16,
  "costTrackerSummary": {
    "requestControlId": "...",
    "calls": [],
    "totals": { "inputTokens": 12000, "outputTokens": 2400, "totalCostUsd": 0.0184 }
  }
}

​
Campos da Resposta

advisorReportId
string (UUID)

ID do report V4 criado. Use para filtrar issues deste run em queries subsequentes.

issuesCreated
number

Issues novas detectadas neste run.

issuesEnriched
number

Issues enriquecidas pelos enrichers (path exato, citações, features, agentes).

issuesKept
number

Issues abertas pré-existentes mantidas (dedup contra advisor_issues_v2).

issuesResolved
number

Issues que o validateIssuesGlobalAction reconciliou como resolvidas durante este run.

summary
string

Resumo textual do diagnóstico. Inclui notas sobre tracers pulados via soft-fail (prompt_too_large, llm_failed).

stSessionId
string (UUID)

ID da sequential_thinking_sessions criada para este run. Use para replay/auditoria.

scopesCovered
array de string

Escopos efetivamente cobertos no run (pode diferir de scopes informado quando tracers são pulados).

issues
array

Issues criadas/atualizadas neste run, com entities[] (entidade enriquecida com originalText, breadcrumb e snapshot), entityNetworks (mapa por entityId com chain/option/agents), hints[] (dicas de tolky_features) e rewrites[] (sugestões de reescrita persistidas em advisor_issue_rewrites).

total
number

Total de issues abertas para o avatar após o run (criadas + mantidas).

costTrackerSummary
object

Resumo de custo das chamadas LLM da requisição (requestCostTracker.summarize()).

​
Erros

CódigoDescrição
400scopes não é array nem null, completionTimeoutMs/loopGuardDurationMs não positivos, hostId/hostSlug ausentes
401Token inválido ou ausente
404Host não encontrado para hostSlug, ou avatarId não pertence ao hostId
500Erro interno do servidor
Advisor V4 (omniAdvisorV4)Verify Issue (Advisor V4)