Pular para o conteúdo principal
Os agentes da tela Agentes de IA também podem ser montados e mantidos pela API. É o mesmo cadastro da tela: o que a API cria aparece no painel, e um agente montado no painel sai na API no mesmo formato. Use estas rotas para manter as instruções, os destinos e a base de conhecimento dos agentes a partir de outro sistema. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}. Os endereços seguem a URL base da API: https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/....
Qual chave da API usar: as rotas de Agentes de IA aceitam toda chave ativa da empresa, inclusive a chave presa a um canal. Ou seja: quem tem a chave da API pode listar, criar, editar e excluir agentes. Guarde o token como uma senha (veja Segurança do Token).

Rotas

Ids do caminho:

Erros comuns a todas as rotas

Nas recusas de validação, ERR_INVALID_FIELD vem com field (ou fields) apontando o caminho do campo recusado, por exemplo temperature, externalTools[0].url ou actions[2].tagId.

Listar agentes

Lista os agentes de IA da empresa em versão resumida. Dentro de data vem uma lista de { id, name, isActive, description, kbOnly }. A configuração completa de cada agente vem em Consultar agente.

Listar recursos do motor de agentes

Lista os recursos disponíveis no motor de agentes do seu servidor PanÐá Zap. Dentro de data vem { engineFeatures: [...] }. Exemplos de recursos: actionsV5, routingV5, booking, scheduleMessage, kbJsonMd, agentHandoff, agentConsult, kbOnly, kbShared, replyDelay, mcp, inactivity e qualifyPass. O que depende de um recurso fora da lista é ignorado ou não roda. Exemplos:
  • Destino do tipo ai_agent sem o recurso agentHandoff.
  • qualifyPassEnabled sem o recurso qualifyPass.
  • Documento .json ou .md sem o recurso kbJsonMd.

Consultar agente

Consulta um agente de IA com a configuração completa. Dentro de data vêm id, name, description, isActive, kbOnly, usePlatformAi, hasApiKey, baseUrl, model, systemPrompt, exitKeyword, temperature, maxHistoryMessages, kbEnabled, kbTopK, semanticEnabled, routingEnabled, routingTargets, autoSummaryEnabled, fallbackQueueId, transferMessage, externalTools, actions, actionMessage, memoryEnabled, memoryFields, closeRules, nativeTools, timezone, consultAgents, sharedKbAgents, replyDelayMin, replyDelayMax, mcpTools, inactivityConfig, qualifyPassEnabled, createdAt e updatedAt. As key dos itens (destinos, ferramentas e cards) são as que você reenvia em Editar agente. Um agente montado na tela sai aqui no mesmo formato descrito em Criar agente.

Criar agente

Cria um agente de IA na empresa do token. É o mesmo cadastro da tela Agentes de IA.

Obrigatórios

  • name.
  • A conexão com o modelo, que é uma destas:
    • apiKey: chave do provedor (OpenAI ou o compatível do baseUrl);
    • usePlatformAi: true: IA da plataforma, cobrada nos créditos de IA da empresa. Não mande apiKey junto.
No criar, texto vazio e null valem como campo ausente. Sem apiKey e sem usePlatformAi: true, a rota responde 400 ERR_MISSING_FIELDS. Sem model, vale gpt-4o-mini; com a IA da plataforma, o modelo precisa estar no catálogo dela (senão, 422).

Campos do body

Só estes campos são aceitos; outra chave é ignorada.

Validação

  • Limites são recusados, nunca cortados nem ajustados: texto acima do tamanho, lista acima da quantidade e número fora da faixa (temperature, maxHistoryMessages, kbTopK, replyDelayMin e replyDelayMax) respondem 400 ERR_INVALID_FIELD, com field no caminho (ex.: temperature, externalTools[0].url).
  • Lista com mais de 50 itens é recusada logo de cara, antes de conferir os itens.
  • Booleanos aceitam só true, false, "true" ou "false" (outro valor responde 400 ERR_INVALID_FIELD com field). A regra vale também dentro dos objetos e listas: closeRules.grace.enabled, nativeTools.booking.enabled, nativeTools.scheduleMessage.enabled, inactivityConfig.enabled, inactivityConfig.warning.enabled, externalTools[].params[].required e externalTools[].secretClear.

Listas

Exemplo de um destino que transfere para uma fila:

Objetos

O nome dos motivos e dos tipos de evento vem do cadastro.

Keys dos itens

  • Item sem key ganha uma gerada (api_ + 8 caracteres), devolvida na resposta.
  • key própria: só letras, números, _ e -, até 40 caracteres.
  • Item que a tela descartaria (sem label, description ou nome, tipo inválido, key repetida) responde 400 ERR_INVALID_FIELD com field (ex.: routingTargets[1]).

Ids conferidos na empresa

Os ids (filas, usuários, fluxos, agentes, etiquetas, raias, funis, etapas, motivos, página e tipos de evento da agenda, servidores MCP) são conferidos na empresa do token: inexistente ou de outra empresa responde 400 ERR_INVALID_FIELD, com field no caminho (ex.: actions[2].tagId). O stageId tem de ser do pipelineId do card, e os eventTypes, da bookingPageId.

baseUrl

  • http ou https, sem usuário e senha no endereço (usuario:senha@host responde 400 ERR_INVALID_FIELD com field baseUrl).
  • Endereço de metadados de nuvem é recusado (400 ERR_INVALID_FIELD; conferência de melhor esforço ao salvar).
  • Com a IA da plataforma, o baseUrl é ignorado.

Depois de criar

  • O agente criado só responde depois de ligado a um canal (menu Canais) ou a um nó de fluxo no painel. Veja Ativar e Vincular um Agente.
  • Repetir o pedido cria outro agente.

Resposta

201, com o agente completo dentro de data, no formato de Consultar agente (sem a chave do provedor).

Erros


Editar agente

Edita um agente de IA: só os campos enviados mudam. Os campos aceitos, os formatos das listas e dos objetos, as keys, os booleanos, os tamanhos, as faixas e a conferência dos ids são os mesmos de Criar agente. Valor fora deles é recusado, nunca cortado.

Como limpar um campo

  • null ou "" limpam o campo: texto, número (como fallbackQueueId, replyDelayMin e replyDelayMax) e objeto (como closeRules, nativeTools e inactivityConfig).
  • [] limpa a lista.
  • Lista enviada substitui a lista inteira: para mudar um item, reenvie a lista completa com as key devolvidas por Consultar agente.

O que não se limpa

Conexão com o modelo

  • usePlatformAi: true passa o agente para a IA da plataforma (sem apiKey junto). false num agente da plataforma exige apiKey.
  • Trocar o baseUrl para outro endereço (não vazio) num agente com chave própria exige reenviar a apiKey no mesmo pedido, senão a rota responde 400 ERR_MISSING_FIELDS com fields ["apiKey"]: a chave salva nunca vai para um endereço novo.
  • Com a IA da plataforma, mandar model confere o catálogo (422).
  • O baseUrl só é conferido quando muda.

Outras regras

  • Ids conferidos na empresa: só os novos. Os que já estão salvos no agente passam, mesmo que a fila ou o agente referenciado tenha sido excluído.
  • Ferramenta externa: reenvie a mesma key e a mesma url com secret vazio para manter o segredo salvo, ou mande secretClear: true no item para apagar o segredo salvo.
  • Uma key nova faz anotações e avisos à equipe já feitos nos atendimentos em curso poderem sair de novo.
  • A troca de chave vale também para os atendimentos em que o agente está respondendo, e outros processos do servidor podem usar a versão anterior por até 60 segundos.

Resposta

Dentro de data, o agente completo, no formato de Consultar agente.

Erros


Duplicar agente

Duplica um agente de IA com a base de conhecimento: artigos, fontes e arquivos são copiados. Regras:
  • A cópia não herda o vínculo com canais nem com nós de fluxo.
  • Se a passada de qualificação (qualifyPassEnabled) está desligada no original, continua desligada na cópia.
  • Agente que usa a IA da plataforma: a cópia passa antes pela trava dos créditos de IA da empresa.
  • Repetir o pedido cria outra cópia.
A resposta é 201, com { id, name, isActive, description, kbOnly } dentro de data. A configuração completa vem em Consultar agente.

Ver onde o agente é usado

Mostra onde o agente é usado. Consulte antes de excluí-lo ou de ligar o só base de conhecimento (kbOnly). Dentro de data vem { sharedKbBy, transferFrom, consultedBy, channels }, cada um uma lista de { id, name }. Os fluxos (nó Agente de IA e Fora do horário) não entram nesta lista: confira no painel.

Excluir agente

O corpo vai vazio: {}.
A exclusão não pode ser desfeita. Consulte Ver onde o agente é usado antes.
O que acontece:
  • O agente é desligado dos canais.
  • Os atendimentos abertos e pendentes em que ele está respondendo são soltos.
  • A base de conhecimento dele é apagada (artigos, fontes e arquivos).
  • Não são limpas as referências em outros agentes (destinos, consulta e base compartilhada) nem nos fluxos: ali o atendimento cai na fila de reserva ou o passo fica indisponível.
A resposta traz { deleted: true } dentro de data.

Base de conhecimento

A base de conhecimento de um agente tem duas partes, cada uma com as suas rotas: Regras das importações:
  • Documento e link: limites de 20 fontes por agente, 400 trechos por fonte e 2.000 trechos por agente. Acima deles, a rota responde 400 ERR_AI_AGENT_SOURCE_LIMIT.
  • FAQ: até 400 perguntas por envio, dentro do limite de fontes do agente.
  • Uma importação de documento ou link por vez em cada processo do servidor. Ocupado responde 429 ERR_AI_AGENT_SOURCE_BUSY: tente de novo em alguns segundos.
  • Com a busca semântica do agente ligada (semanticEnabled), os artigos e os trechos de documento e de FAQ são vetorizados, com custo no provedor do agente ou nos créditos de IA.

Listar artigos

Lista os artigos manuais da base de conhecimento do agente. Os trechos importados de documento, link ou FAQ não aparecem aqui: veja Listar fontes. Dentro de data vem uma lista de { id, title, content, isActive, createdAt, updatedAt }.

Criar artigo

Regras:
  • Texto vazio vale como campo ausente: content ausente, vazio ou null responde 400 ERR_MISSING_FIELDS.
  • Com a busca semântica do agente ligada, o artigo é vetorizado em segundo plano.
A resposta é 201, com o artigo { id, title, content, isActive, createdAt, updatedAt } dentro de data.

Editar artigo

Edita um artigo manual da base de conhecimento. Só os campos enviados mudam. A resposta traz o artigo { id, title, content, isActive, createdAt, updatedAt } dentro de data.

Excluir artigo

Exclui um artigo manual da base de conhecimento. Não pode ser desfeito. O corpo vai vazio ({}) e a resposta traz { deleted: true } dentro de data.

Listar fontes

Lista as fontes da base de conhecimento do agente: documentos, links e FAQs importados. Dentro de data vem uma lista de { id, type, name, url, status, errorMessage, syncEnabled, chunkCount, lastSyncAt, createdAt }. O id é o sourceId de Sincronizar fonte e Excluir fonte.

Importar documento

Importa um documento para a base de conhecimento do agente. O envio é um formulário (multipart/form-data), não JSON, com o arquivo no campo media:
A resposta só sai quando o documento termina de ser lido e dividido em trechos. Pode levar minutos em arquivo grande: não corte a conexão antes.
Os limites de fontes e de trechos e a regra de uma importação por vez estão em Base de conhecimento. A resposta é 201, com a fonte criada dentro de data, no mesmo formato de Listar fontes.
Importa o texto de uma página (link) para a base de conhecimento do agente. A resposta só sai quando a página termina de ser lida. Este envio segue os limites e a regra de uma importação por vez de Base de conhecimento. Também responde 201, com a fonte dentro de data, no formato de Listar fontes.

Importar FAQ

Importa perguntas e respostas (FAQ) para a base de conhecimento do agente.
O FAQ não deduplica: repetir o pedido cria outra fonte com as mesmas perguntas. Confira Listar fontes antes de repetir.
A resposta é 201, com a fonte dentro de data, no formato de Listar fontes.

Sincronizar fonte

Sincroniza de novo uma fonte da base de conhecimento. O corpo vai vazio ({}) e a resposta só sai quando a sincronização termina. A resposta traz a fonte dentro de data, no formato de Listar fontes.

Excluir fonte

Exclui uma fonte da base de conhecimento do agente, com os trechos e o arquivo dela. Não pode ser desfeito. O corpo vai vazio ({}) e a resposta traz { deleted: true } dentro de data.
Para montar o agente pela tela (instruções, destinos, ações, ferramentas e base de conhecimento) e ligá-lo a um canal ou fluxo, veja Agentes de IA.