O Decision Assistant é a camada em linguagem natural para trabalhar com os mesmos fluxos de automação (decision chains) que você já gerencia pela API ou pelo painel. Ele serve para perguntar como algo está configurado, criar um fluxo novo a partir de uma descrição, editar com pré-visualização e manter histórico com rollback — sem precisar montar o JSON bloco a bloco na mão.

​
O que você pode fazer

CapacidadeQuando usar
Perguntas (/ask)Entender como as chains estão configuradas, sem alterar nada.
CriaçãoDescrever o fluxo desejado; o assistente propõe a chain completa. Você pode revisar (/create/preview → /create/apply) ou criar em um passo (/create).
EdiçãoPedir mudanças em texto; receber diff e explicação. Idem: preview + apply (/edit/preview → /edit/apply) ou um passo (/edit).
Versões e rollbackListar histórico (GET /versions) e restaurar uma versão anterior (/rollback).

​
Base da API

ItemValor
Prefixo{{BASE_URL}}/api/externalAPIs/public/tolkyReasoning/decisions/assistant
AutenticaçãoAuthorization: Bearer {TOKEN}

Substitua {{BASE_URL}} pela URL do ambiente (ex.: produção ou http://localhost:8080 em desenvolvimento).

​
Fluxos típicos

  1. Só consultar — POST .../ask com hostId, pergunta em question e, se quiser focar em um avatar, avatarId.
  2. Criar com revisão — POST .../create/preview → copiar previewId da resposta → POST .../create/apply com esse previewId.
  3. Criar direto — POST .../create (mesmo corpo do preview; persiste na hora).
  4. Editar com revisão — POST .../edit/preview com decisionChainId e instruction → POST .../edit/apply com previewId.
  5. Histórico / voltar atrás — GET .../versions?decisionChainId=... → escolher versionId → POST .../rollback.

Para CRUD “clássico” das chains (listar, salvar, excluir), use os endpoints em Listar Fluxos e Salvar Fluxo.

​
Exemplos cURL

Defina variáveis uma vez (ajuste IDs e token):

export BASE_URL="{{BASE_URL}}"
export ASSISTANT="${BASE_URL}/api/externalAPIs/public/tolkyReasoning/decisions/assistant"
export TOKEN="seu-token-bearer"
export HOST_ID="uuid-do-host"
export AVATAR_ID="uuid-do-avatar"
export DECISION_CHAIN_ID="uuid-da-chain"
export PREVIEW_ID="uuid-retornado-no-preview"
export VERSION_ID="uuid-da-versao-no-historico"
export USER_ID="uuid-do-usuario-opcional"

No PowerShell, use curl.exe ou rode os comandos no Git Bash para manter a mesma sintaxe.

​
Perguntar (/ask)

Com escopo de avatar (chains daquele avatar + chains globais do host):

curl -sS -X POST "${ASSISTANT}/ask" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"avatarId\": \"${AVATAR_ID}\",
    \"question\": \"Quais blocos disparam criação de ticket?\"
  }"

Sem avatarId — considera todas as chains do host:

curl -sS -X POST "${ASSISTANT}/ask" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"hostId\": \"${HOST_ID}\", \"question\": \"Resuma as regras do fluxo principal.\"}"

​
Criar — só pré-visualização (/create/preview)

curl -sS -X POST "${ASSISTANT}/create/preview" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"avatarId\": \"${AVATAR_ID}\",
    \"prompt\": \"Fluxo simples: saudação e encaminhamento para humano quando o cliente pedir atendente.\",
    \"decisionName\": \"Saudação e handoff\"
  }"

decisionName é opcional; o modelo pode sugerir um nome se você omitir. avatarId também é opcional (omitir = chain global para todos os avatares do host).

Opcionalmente envie agents: array com a lista de agents que o assistente pode usar. Se omitir, o backend carrega os agents disponíveis para o host automaticamente.

​
Criar — aplicar preview (/create/apply)

Use o previewId retornado por /create/preview. Alternativa: em vez de previewId, envie proposedChain (decisionName, chainJson, instructions opcional) quando já tiver o JSON validado por outro fluxo.

curl -sS -X POST "${ASSISTANT}/create/apply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"avatarId\": \"${AVATAR_ID}\",
    \"previewId\": \"${PREVIEW_ID}\",
    \"userId\": \"${USER_ID}\",
    \"active\": true
  }"

​
Criar — um passo (/create)

Mesmo corpo conceitual do preview; cria e persiste em uma chamada:

curl -sS -X POST "${ASSISTANT}/create" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"prompt\": \"Fluxo mínimo com instruções gerais e um bloco de encerramento.\"
  }"

​
Editar — pré-visualização (/edit/preview)

curl -sS -X POST "${ASSISTANT}/edit/preview" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"avatarId\": \"${AVATAR_ID}\",
    \"decisionChainId\": \"${DECISION_CHAIN_ID}\",
    \"instruction\": \"Deixe a description do primeiro bloco operacional mais específica.\"
  }"

​
Editar — aplicar preview (/edit/apply)

previewId vem do /edit/preview. Se já tiver um chain_json validado, você pode aplicar com proposedChainJson no corpo em vez de previewId (um dos dois é obrigatório).

curl -sS -X POST "${ASSISTANT}/edit/apply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"decisionChainId\": \"${DECISION_CHAIN_ID}\",
    \"previewId\": \"${PREVIEW_ID}\",
    \"userId\": \"${USER_ID}\"
  }"

​
Editar — um passo (/edit)

curl -sS -X POST "${ASSISTANT}/edit" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"decisionChainId\": \"${DECISION_CHAIN_ID}\",
    \"instruction\": \"Ajuste apenas textos do bloco generalInstructions para tom mais formal.\"
  }"

​
Listar versões (GET /versions)

curl -sS -G "${ASSISTANT}/versions" \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "decisionChainId=${DECISION_CHAIN_ID}" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

​
Rollback (/rollback)

curl -sS -X POST "${ASSISTANT}/rollback" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostId\": \"${HOST_ID}\",
    \"decisionChainId\": \"${DECISION_CHAIN_ID}\",
    \"versionId\": \"${VERSION_ID}\",
    \"userId\": \"${USER_ID}\"
  }"

​
Respostas e erros comuns

  • O backend pode envolver o payload de sucesso no padrão da API (ex.: data); valide o corpo real na integração.
  • 401 / 403: token ausente ou inválido.
  • 404: chain, preview ou versão inexistente, ou preview expirado.
  • 408: timeout do assistente (60s).

​
Ver também

Deletar ChunkListar Fluxos