Endpoint de produção. Executa o motor com ações reais. O hostId vem do header X-Host-Id (KrakenD). Em ambiente local, envie hostId no body.

​
Endpoint

POST /runWithAgents

​
Ações disponíveis

  • ragSearch — busca semântica na base de conhecimento do host
  • spotLightSearch — busca textual em conversas, mensagens e contatos
  • executeFormFlowCrud — operações no FormFlow, incluindo persistência de dados estruturados
  • captureConversationDataToForm — extrai dados da conversa e salva em formulário existente
  • getNews — busca notícias e informações na web
  • respondToUser — entrega a resposta final ao chamador (deve ser o último step)

A ação captureInterDataWithInstructions está descontinuada e não faz parte do catálogo v4.

​
Parâmetros

instructions
string
required

O que o motor deve fazer, em linguagem natural.

intentId
string (UUID)

ID de uma execução anterior para retomada. Quando presente, instructions é opcional e o motor continua de onde parou.

hostId
string (UUID)

UUID do host. Obrigatório apenas em ambiente local — em produção é ignorado e vem do header X-Host-Id.

hostSlug
string

Slug do host (alternativa ao hostId em ambiente local). O motor resolve hostSlug → hostId via cache Redis antes de prosseguir.

conversational
object

Configuração de persistência conversacional. Quando presente, o motor grava mensagens na conversa-alvo ao longo do ciclo de vida da execução (após criar o intent, ao gerar o plano, ao concluir cada step e na resposta final).

O campo conversational substitui incrementConversationId. Ao usar conversational, o motor controla toda a persistência conversacional internamente ao longo do ciclo de vida. O campo incrementConversationId continua aceito para retrocompatibilidade e é mapeado automaticamente para conversational com os defaults equivalentes ao comportamento anterior.

options
object

​
Exemplo

curl -X POST "{{BASE_URL}}/runWithAgents" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Busque informações sobre planos de saúde na base de conhecimento e responda de forma clara."
  }'

​
Ambiente local (com hostId no body)

curl -X POST "http://localhost:3000/api/externalAPIs/public/sequentialThinking/runWithAgents" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Busque informações sobre planos de saúde.",
    "hostId": "uuid-do-host-aqui"
  }'

​
Retomar execução anterior

curl -X POST "{{BASE_URL}}/runWithAgents" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "intentId": "uuid-retornado-na-primeira-execucao"
  }'

​
Resposta

{
  "data": {
    "result": {
      "success": true,
      "intentId": "uuid-da-execucao",
      "steps": [
        {
          "stepNumber": 1,
          "action": "ragSearch",
          "status": "completed",
          "result": { "chunks": [], "query": "planos de saúde" },
          "params": { "query": "planos de saúde" },
          "durationMs": 2500
        },
        {
          "stepNumber": 2,
          "action": "respondToUser",
          "status": "completed",
          "result": { "message": "Com base na base de conhecimento..." },
          "params": { "message": "Com base na base de conhecimento..." },
          "durationMs": 1200
        }
      ],
      "finalAnswer": { "message": "Com base na base de conhecimento..." },
      "feasibilityAnalysis": { "feasible": true, "issues": [], "warnings": [], "recommendations": [] },
      "metrics": {
        "totalDurationMs": 4500,
        "totalLlmCalls": 3,
        "totalTokensUsed": { "prompt": 2000, "completion": 600 },
        "totalCostInDollars": 0.0089,
        "stepDurations": { "1": 2500, "2": 1200 }
      },
      "auditLog": [],
      "auditInsight": null,
      "error": null
    },
    "events": []
  }
}

​
Campos da Resposta

data
object

​
Verificação de sucesso

Sempre verifique result.success para saber se a execução foi bem-sucedida:

if (data.result.success) {
  const lastStep = data.result.steps?.at(-1);
  const finalMessage = lastStep?.action === 'respondToUser'
    ? lastStep.result?.message
    : JSON.stringify(lastStep?.result);
  // exibir finalMessage ao usuário
} else {
  console.error(data.result.error);
}

​
Erros

CódigoDescrição
400instructions ausente em nova execução — “O campo “instructions” é obrigatório para novas execuções.”
400hostId não encontrado — “hostId não encontrado. Em ambiente local, passe “hostId” no body.”
401Token inválido ou ausente
500Erro interno do servidor
Executar com SandboxIniciar Autenticação PDPJ