Executar com Agentes Reais

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

O motor escolhe automaticamente quais ações usar a partir da instrução. Você não precisa nomeá-las no pedido — basta descrever o resultado que quer. Use GET /listActions para ver o catálogo vivo do seu host (algumas ações podem estar disponíveis apenas em certas camadas ou hosts).

Conhecimento e busca

• ragSearch — busca semântica na base de conhecimento do host (documentos, FAQs, conteúdo curado).
• webSearchV4 — pesquisa na web em tempo real para enriquecer respostas com fatos atuais. Útil quando a base do host pode não cobrir o tópico.
• recursiveSearch — busca em múltiplas passagens, encadeando consultas para ir mais fundo num assunto.
• spotLightSearch — busca textual em conversas, mensagens e contatos do host.

Conversa e contexto

• extractConversationMetadata — lê a conversa em andamento e extrai metadados estruturados (lead, datas, intenção, etc.).
• analyzeDateMention — interpreta menções a datas em linguagem natural (“amanhã”, “próxima quinta”) e converte em data absoluta.
• investigateWithV3 — analisa o histórico da conversa com IA para responder perguntas sobre ela.
• findLeadByContact — localiza um lead a partir de telefone, e-mail ou outro identificador.
• consultTolkyFeatures — responde sobre capacidades e funcionalidades da plataforma Tolky.

Captura de dados estruturados

• buildCaptureSchema — monta dinamicamente o schema dos campos a capturar a partir da intenção.
• captureStructuredData — extrai dados estruturados de um texto livre conforme um schema definido.
• searchFormCatalogs — pesquisa entre os formulários e catálogos disponíveis no host.
• captureConversationDataToForm — extrai dados da conversa em andamento e salva num formulário existente.
• formFlowCrud — operações CRUD no FormFlow, incluindo persistência de dados estruturados.

Tickets e tarefas

• findTicketByProtocol — localiza um ticket a partir do número de protocolo.
• updateTicket — atualiza campos de um ticket existente.
• followupNotify — agenda ou dispara notificações de follow-up.
• sendEmail — envia e-mail a partir do host.

Dados internos

• queryDatabase — gera e executa consulta SQL sobre os dados do host, com validação de segurança e escopo.
• querySmartTags — consulta dados via templates pré-construídos (smart tags), mais rápidos e baratos que SQL livre.

Apresentação ao usuário

• presentVisualBlocksV2 — entrega blocos visuais (cartões, gráficos, KPIs) para o cliente renderizar junto da resposta.
• exportToSpreadsheet — exporta resultado em planilha (XLSX/CSV) para download.
• interruptForInput — pausa a execução e devolve uma pergunta ao usuário quando o motor precisa de informação faltante para concluir bem (veja Quando o motor pausa para perguntar algo).
• respondToUser — entrega a resposta final ao chamador. Sempre o último step.

​

Parâmetros

​

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:8080/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

​

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);
}

​

Quando o motor pausa para perguntar algo

Em alguns pedidos, o motor identifica que falta informação para concluir bem (ex.: o usuário pediu “atualize meu cadastro” mas não disse qual campo, ou pediu “marca para amanhã” sem dizer o horário). Em vez de chutar ou falhar silenciosamente, o motor pausa a execução e devolve uma pergunta para o usuário responder.

Quando isso acontece, a resposta de runWithAgents chega com success: false e interrupted: true. Não é um erro — é um pedido de complemento.

​

Resposta de execução interrompida

{
  "data": {
    "result": {
      "success": false,
      "interrupted": true,
      "intentId": "uuid-da-execucao",
      "interruptionPayload": {
        "question": "Qual campo do cadastro você quer atualizar?",
        "context": "Para atualizar seu cadastro preciso saber qual campo",
        "options": ["Telefone", "E-mail", "Endereço"]
      },
      "continuationDepth": 0,
      "finalAnswer": {
        "message": "Qual campo do cadastro você quer atualizar?",
        "executionStatus": "interrupted",
        "interruptionPayload": { "question": "...", "context": "...", "options": [] }
      },
      "steps": [
        { "stepNumber": 1, "action": "interruptForInput", "status": "interrupted" }
      ],
      "error": null
    },
    "events": [
      { "type": "execution_interrupted" }
    ]
  }
}

O que fazer com cada campo:

• interruptionPayload.question — mostre essa pergunta ao usuário (é a frase pronta para exibir).
• interruptionPayload.options (opcional) — quando presente, é uma lista curta de opções. Ofereça-as como botões ou chips para resposta rápida.
• interruptionPayload.context — contexto interno do motor sobre por que parou. Útil para logs e telemetria; normalmente não precisa aparecer ao usuário.
• intentId — guarde-o. Você vai usá-lo no próximo POST para retomar.
• continuationDepth — quantas vezes esta execução já pausou. O motor limita a 4 continuações (maxContinuations padrão) para evitar loops; se você atingir esse limite, considere reformular o pedido em vez de continuar.

​

Como continuar

Faça um novo POST /runWithAgents com o mesmo intentId e o continuationInput carregando a resposta do usuário:

curl -X POST "{{BASE_URL}}/runWithAgents" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "intentId": "uuid-da-execucao",
    "continuationInput": {
      "userResponse": "Telefone"
    }
  }'

Campos do continuationInput:

• userResponse (obrigatório) — texto da resposta do usuário, exatamente como ele respondeu.
• additionalInstructions (opcional) — instruções extras suas para guiar a continuação (ex.: “se o usuário disse um campo inválido, peça novamente”).

A continuação reutiliza tudo o que já foi planejado e executado: o motor lê a resposta, replaneja apenas o que falta, e segue. A resposta final pode chegar nessa segunda chamada, ou o motor pode pausar de novo se ainda precisar de mais alguma coisa.

​

Erros