> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Agentes de IA: crie agentes e mantenha a base de conhecimento

> Liste, crie, edite, duplique e exclua agentes de IA e mantenha a base de conhecimento deles (artigos, documentos, links e FAQ) pela API do PanÐá Zap.

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](https://ajuda.pandazap.com/api/overview.md#url-base) da API: `https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/...`.

> [!WARNING]
>
> **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](https://ajuda.pandazap.com/api/authentication.md#segurança-do-token)).

***

## Rotas

| Ação | Método e caminho |
| - | - |
| [Listar agentes](#listar-agentes) | `GET /aiAgent/list` |
| [Listar recursos do motor de agentes](#listar-recursos-do-motor-de-agentes) | `GET /aiAgent/features` |
| [Consultar agente](#consultar-agente) | `GET /aiAgent/show/{aiAgentId}` |
| [Criar agente](#criar-agente) | `POST /aiAgent/create` |
| [Editar agente](#editar-agente) | `POST /aiAgent/update/{aiAgentId}` |
| [Duplicar agente](#duplicar-agente) | `POST /aiAgent/duplicate/{aiAgentId}` |
| [Ver onde o agente é usado](#ver-onde-o-agente-é-usado) | `GET /aiAgent/usage/{aiAgentId}` |
| [Excluir agente](#excluir-agente) | `POST /aiAgent/delete/{aiAgentId}` |
| [Listar artigos](#listar-artigos) | `GET /aiAgent/knowledge/list/{aiAgentId}` |
| [Criar artigo](#criar-artigo) | `POST /aiAgent/knowledge/create/{aiAgentId}` |
| [Editar artigo](#editar-artigo) | `POST /aiAgent/knowledge/update/{aiAgentId}/{knowledgeId}` |
| [Excluir artigo](#excluir-artigo) | `POST /aiAgent/knowledge/delete/{aiAgentId}/{knowledgeId}` |
| [Listar fontes](#listar-fontes) | `GET /aiAgent/source/list/{aiAgentId}` |
| [Importar documento](#importar-documento) | `POST /aiAgent/source/document/{aiAgentId}` |
| [Importar link](#importar-link) | `POST /aiAgent/source/url/{aiAgentId}` |
| [Importar FAQ](#importar-faq) | `POST /aiAgent/source/faq/{aiAgentId}` |
| [Sincronizar fonte](#sincronizar-fonte) | `POST /aiAgent/source/resync/{aiAgentId}/{sourceId}` |
| [Excluir fonte](#excluir-fonte) | `POST /aiAgent/source/delete/{aiAgentId}/{sourceId}` |

Ids do caminho:

| Parâmetro | De onde vem |
| - | - |
| `aiAgentId` | O `id` devolvido por [Listar agentes](#listar-agentes). |
| `knowledgeId` | O `id` do artigo, devolvido por [Listar artigos](#listar-artigos). |
| `sourceId` | O `id` da fonte, devolvido por [Listar fontes](#listar-fontes). |

## Erros comuns a todas as rotas

| Código | Quando acontece |
| - | - |
| `402` `ERR_FEATURE_NOT_IN_PLAN` | O plano da empresa não tem Agentes de IA. |
| `402` `ERR_TENANT_PAYMENT_BLOCKED` | Empresa bloqueada por pagamento. |
| `403` `ERR_API_CONFIG_INACTIVE` | Chave da API desativada. Vale também para o token de uma chave desativada usado com o `ApiID` de outra. |
| `403` `ERR_SESSION_NOT_AUTH_TOKEN` | O token é de outra sessão da API. |
| `404` `ERR_API_CONFIG_NOT_FOUND` | O `ApiID` da URL não existe nesta empresa. |
| `404` `ERR_AI_AGENT_NOT_FOUND` | Nas rotas com `aiAgentId`: agente inexistente, de outra empresa ou fora do formato. Nas rotas com `knowledgeId` ou `sourceId`, vale também para o artigo ou a fonte. |
| `500` `ERR_AI_AGENT_API` | Falha inesperada no servidor. |

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

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/list
```

Lista os agentes de IA da empresa em versão resumida. Dentro de `data` vem uma lista de `{ id, name, isActive, description, kbOnly }`.

| Campo | Significado |
| - | - |
| `kbOnly` | `true` = agente **só base de conhecimento**: não atende e serve de base para outros agentes. |

A configuração completa de cada agente vem em [Consultar agente](#consultar-agente).

***

## Listar recursos do motor de agentes

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/features
```

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

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/show/{aiAgentId}
```

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`.

| Campo | Significado |
| - | - |
| `hasApiKey` | `true` = há chave do provedor salva. A chave do provedor **nunca é devolvida**. |
| `usePlatformAi` | `true` = o agente usa a IA da plataforma. |
| `externalTools` | O segredo de cada ferramenta externa vem vazio, acompanhado de `hasSecret`. |
| `qualifyPassEnabled` | Só vem quando o motor tem o recurso `qualifyPass` (veja [Listar recursos do motor de agentes](#listar-recursos-do-motor-de-agentes)). |

As `key` dos itens (destinos, ferramentas e cards) são as que você reenvia em [Editar agente](#editar-agente). Um agente montado na tela sai aqui no mesmo formato descrito em [Criar agente](#criar-agente).

***

## Criar agente

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/create
```

```json theme={null}
{
  "name": "Agente de triagem",
  "description": "Recebe o cliente e encaminha para o setor certo",
  "isActive": true,
  "apiKey": "SUA_CHAVE_DO_PROVEDOR",
  "model": "gpt-4o-mini",
  "systemPrompt": "Você é o atendente virtual da empresa. Responda com cordialidade e em poucas frases.",
  "temperature": 0.7,
  "maxHistoryMessages": 20,
  "kbEnabled": true,
  "kbTopK": 4,
  "semanticEnabled": false,
  "autoSummaryEnabled": true,
  "timezone": "America/Sao_Paulo"
}
```

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.

| Campo | Regra |
| - | - |
| `name` | Obrigatório, até 255 caracteres. |
| `description` | Até 2.000 caracteres. |
| `isActive` | Booleano. |
| `apiKey` | Chave do provedor (OpenAI ou o compatível do `baseUrl`). |
| `usePlatformAi` | `true` = IA da plataforma, cobrada nos créditos de IA da empresa. |
| `baseUrl` | Endereço próprio compatível com OpenAI (ex.: Ollama ou LM Studio na rede da empresa). Veja as regras em **baseUrl**, abaixo. |
| `model` | Até 255 caracteres. Sem ele, vale `gpt-4o-mini`. |
| `systemPrompt` | Até 100.000 caracteres. |
| `exitKeyword` | Palavra que o cliente digita para sair do agente, até 100 caracteres. |
| `temperature` | De 0 a 2. |
| `maxHistoryMessages` | De 1 a 100. |
| `kbEnabled` | Booleano. |
| `kbTopK` | De 1 a 10. |
| `semanticEnabled` | Busca semântica: vetoriza a base, com custo no provedor do agente ou nos créditos de IA. |
| `routingEnabled` | Booleano. |
| `routingTargets` | Lista de destinos (formato em **Listas**, abaixo). |
| `autoSummaryEnabled` | Booleano. |
| `fallbackQueueId` | Fila de reserva. |
| `transferMessage` | Até 1.000 caracteres. |
| `externalTools` | Lista de ferramentas externas (formato em **Listas**). |
| `actions` | Lista de cards (formato em **Listas**). |
| `actionMessage` | Até 1.000 caracteres. |
| `memoryEnabled` | Booleano. |
| `memoryFields` | Lista (formato em **Listas**). |
| `closeRules` | Objeto (formato em **Objetos**, abaixo). |
| `nativeTools` | Objeto (formato em **Objetos**). |
| `timezone` | Fuso IANA (ex.: `America/Sao_Paulo`). |
| `consultAgents` | Lista (formato em **Listas**). |
| `sharedKbAgents` | Lista (formato em **Listas**). |
| `kbOnly` | Só base de conhecimento: o agente não atende e fica sempre inativo. |
| `replyDelayMin` e `replyDelayMax` | Atraso da resposta, de 0 a 120 segundos. |
| `mcpTools` | Lista (formato em **Listas**). |
| `inactivityConfig` | Objeto (formato em **Objetos**). |
| `qualifyPassEnabled` | Etiquetas e funil decididos depois de cada resposta. Só com o recurso `qualifyPass` (veja [Listar recursos do motor de agentes](#listar-recursos-do-motor-de-agentes)). |

### 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

| Lista | Máximo | Cada item |
| - | - | - |
| `routingTargets` | 10 | `{ key, label, description, type, queueId, userId, chatFlowId ou aiAgentId, transferMessage }`. `label` até 80, `description` até 1.000, `transferMessage` até 1.000. `type`: `queue`, `user`, `chatflow` ou `ai_agent`, com o id do tipo. |
| `externalTools` | 5 | `{ key, label, description, url, secret, timeoutMs, params, secretClear }`. `label` até 60, `description` até 300, `url` até 500, `secret` até 200. `params` (até 6): `[{ name, description, required }]`, com `description` até 200. `secretClear` só no editar: `true` apaga o segredo salvo. |
| `actions` | 10 cards | `{ key, type, label, description, tagId, kanbanId, pipelineId, stageId, responsibleId, opportunityName, opportunityValue, content, notifyQueueId, notifyUserIds, actionMessage }`. `label` até 80, `description` até 200, `opportunityName` até 120, `content` até 1.000, `notifyUserIds` até 20, `actionMessage` até 1.000. `type`: `tag`, `kanban`, `opportunity`, `note`, `notify` ou `block` (o card `block` exige `fallbackQueueId`). |
| `memoryFields` | 10 | `{ name, description }`, com `description` até 200. |
| `consultAgents` | 5 | `{ aiAgentId, description }`, com `description` até 200. |
| `sharedKbAgents` | 3 | `{ aiAgentId }`. |
| `mcpTools` | 3 servidores | `{ serverId, tools }`, com `tools` = lista com os nomes das ferramentas. |

Exemplo de um destino que transfere para uma fila:

```json theme={null}
{
  "routingEnabled": true,
  "routingTargets": [
    {
      "label": "Financeiro",
      "description": "Boletos, pagamentos e segunda via",
      "type": "queue",
      "queueId": 3
    }
  ]
}
```

### Objetos

| Objeto | Formato |
| - | - |
| `closeRules` | `{ reasons: [{ id }], grace: { enabled, seconds, destinationType, queueId, userId, chatFlowId } }`. `destinationType`: `lastUser`, `closedUser`, `queue`, `user` ou `chatflow`. |
| `nativeTools` | `{ booking: { enabled, bookingPageId, eventTypes: [{ id }] }, scheduleMessage: { enabled, maxDaysAhead } }` |
| `inactivityConfig` | `{ enabled, warning: { enabled, minutes, message }, actAfterMinutes, action, queueId, message }`. `action`: `close` ou `transfer`. Minutos de 1 a 1440. |

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`.

| Ids de | Onde buscar |
| - | - |
| Filas | [Listar filas](https://ajuda.pandazap.com/api/listings.md#listar-filas) (`listQueues`) |
| Usuários | [Listar usuários](https://ajuda.pandazap.com/api/users.md#listar-usuários) (`listUsers`) |
| Etiquetas | [Listar tags](https://ajuda.pandazap.com/api/listings.md#listar-tags) (`listTags`) |
| Raias do kanban | [Listar colunas de kanban](https://ajuda.pandazap.com/api/organization.md#listar-colunas-de-kanban) (`listKanban`) |
| Funis | [Listar pipelines](https://ajuda.pandazap.com/api/crm.md#listar-pipelines) (`pipeline/list`) |
| Etapas | [Listar etapas por pipeline](https://ajuda.pandazap.com/api/crm.md#listar-etapas-por-pipeline) (`stage/list`) |
| Fluxos | [Listar fluxos de chatbot](https://ajuda.pandazap.com/api/listings.md#listar-fluxos-de-chatbot) (`listChatFlows`) |
| Motivos | [Listar motivos](https://ajuda.pandazap.com/api/organization.md#listar-motivos) (`listReasons`) |
| Agentes | [Listar agentes](#listar-agentes) |
| Página de agendamento, tipos de evento e servidores MCP | Só no painel (não há rota na API). |

### 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](https://ajuda.pandazap.com/platform/ai-agents.md#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](#consultar-agente) (sem a chave do provedor).

### Erros

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: falta `name`, ou `apiKey` sem `usePlatformAi: true`. |
| `400` `ERR_INVALID_FIELD` | Com `field` ou `fields`: valor fora do tipo, do tamanho ou da faixa, booleano inválido, `apiKey` junto de `usePlatformAi`, item descartado, id fora da empresa ou `baseUrl` recusado. |
| `400` `ERR_AI_AGENT_BLOCK_NEEDS_FALLBACK` | Card `block` sem `fallbackQueueId` válido. |
| `400` `ERR_AI_AGENT_REQUIRED_FIELDS`, `ERR_AI_AGENT_INVALID_TARGETS`, `ERR_AI_AGENT_INVALID_TOOLS`, `ERR_AI_AGENT_INVALID_ACTIONS`, `ERR_AI_AGENT_INVALID_MEMORY_FIELDS`, `ERR_AI_AGENT_INVALID_CLOSE_RULES`, `ERR_AI_AGENT_INVALID_NATIVE_TOOLS`, `ERR_AI_AGENT_INVALID_CONSULT`, `ERR_AI_AGENT_INVALID_SHARED_KB`, `ERR_AI_AGENT_INVALID_MCP`, `ERR_AI_AGENT_INVALID_INACTIVITY` e `ERR_AI_AGENT_INVALID_TIMEZONE` | Recusas do cadastro (o mesmo da tela **Agentes de IA**). |
| `403` `ERR_AI_PLATFORM_DISABLED` | IA da plataforma não liberada para a empresa. |
| `422` `ERR_AI_PLATFORM_MODEL_NOT_ALLOWED` | Modelo fora do catálogo da IA da plataforma. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Editar agente

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/update/{aiAgentId}
```

```json theme={null}
{
  "description": "Recebe o cliente e encaminha para o setor certo",
  "temperature": 0.5
}
```

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](#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](#consultar-agente).

### O que não se limpa

| Campo | Comportamento |
| - | - |
| `name` | `""` ou `null` responde **400** `ERR_INVALID_FIELD`. |
| `apiKey` | `""` ou `null` mantém a chave salva. |
| Booleanos | `null` responde **400** `ERR_INVALID_FIELD`. |

### 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](#consultar-agente).

### Erros

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: falta `apiKey` ao sair da IA da plataforma sem chave ou ao trocar o `baseUrl` sem reenviar a chave. |
| `400` `ERR_INVALID_FIELD` | Com `field` ou `fields`. |
| `400` `ERR_AI_AGENT_BLOCK_NEEDS_FALLBACK` | Card `block` sem `fallbackQueueId` válido. |
| `400` recusas do cadastro | Os mesmos códigos `ERR_AI_AGENT_...` de [Criar agente](#criar-agente). |
| `403` `ERR_AI_PLATFORM_DISABLED` | IA da plataforma não liberada para a empresa. |
| `422` `ERR_AI_PLATFORM_MODEL_NOT_ALLOWED` | Modelo fora do catálogo da IA da plataforma. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Duplicar agente

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/duplicate/{aiAgentId}
```

```json theme={null}
{
  "name": "Agente de triagem 2"
}
```

Duplica um agente de IA com a base de conhecimento: artigos, fontes e arquivos são copiados.

| Campo | Obrigatório | Descrição |
| - | - | - |
| `name` | Não | Nome da cópia. Vazio ou ausente = o mesmo nome do original. |

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](#consultar-agente).

| Código | Quando acontece |
| - | - |
| `400` `ERR_INVALID_FIELD` | Com `field`. |
| `403` `ERR_AI_PLATFORM_DISABLED` | IA da plataforma não liberada para a empresa. |
| `500` `ERR_AI_AGENT_DUPLICATE_FAILED` | A cópia não foi concluída. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Ver onde o agente é usado

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/usage/{aiAgentId}
```

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 }`.

| Campo | O que lista |
| - | - |
| `sharedKbBy` | Agentes que usam a base dele. |
| `transferFrom` | Agentes que transferem para ele. |
| `consultedBy` | Agentes que o consultam. |
| `channels` | Canais ligados a ele. |

Os fluxos (nó **Agente de IA** e **Fora do horário**) não entram nesta lista: confira no painel.

***

## Excluir agente

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/delete/{aiAgentId}
```

O corpo vai vazio: `{}`.

> [!WARNING]
>
> A exclusão **não pode ser desfeita**. Consulte [Ver onde o agente é usado](#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:

| Parte | O que é | Rotas |
| - | - | - |
| Artigos | Textos cadastrados manualmente: conteúdo e título opcional. | [Listar](#listar-artigos), [criar](#criar-artigo), [editar](#editar-artigo) e [excluir](#excluir-artigo) artigos. |
| Fontes | Documentos, links e FAQs importados, que viram trechos. | [Listar fontes](#listar-fontes), [importar documento](#importar-documento), [link](#importar-link) ou [FAQ](#importar-faq), [sincronizar](#sincronizar-fonte) e [excluir](#excluir-fonte). |

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

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/knowledge/list/{aiAgentId}
```

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](#listar-fontes).

Dentro de `data` vem uma lista de `{ id, title, content, isActive, createdAt, updatedAt }`.

***

## Criar artigo

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/knowledge/create/{aiAgentId}
```

```json theme={null}
{
  "content": "Atendemos de segunda a sexta, das 8h às 18h, e aos sábados, das 8h às 12h.",
  "title": "Horário de atendimento",
  "isActive": true
}
```

| Campo | Obrigatório | Descrição |
| - | - | - |
| `content` | Sim | Texto do artigo, até 20.000 caracteres. |
| `title` | Não | Título do artigo. |
| `isActive` | Não | Padrão `true`. Artigo inativo não entra nas respostas. Aceita só `true`, `false`, `"true"` ou `"false"`. |

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`.

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` | Com `fields`: `content`. |
| `400` `ERR_INVALID_FIELD` | Com `field`. |
| `400` `ERR_AI_AGENT_KB_TOO_LARGE` | `content` acima de 20.000 caracteres. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Editar artigo

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/knowledge/update/{aiAgentId}/{knowledgeId}
```

```json theme={null}
{
  "title": "Horário de atendimento",
  "content": "Atendemos de segunda a sexta, das 8h às 18h, e aos sábados, das 8h às 12h.",
  "isActive": true
}
```

Edita um artigo manual da base de conhecimento. Só os campos enviados mudam.

| Campo | Descrição |
| - | - |
| `title` | `""` ou `null` apaga o título. |
| `content` | Até 20.000 caracteres. `""` ou `null` responde **400** `ERR_INVALID_FIELD` com `field` `content`: o artigo não fica sem texto. |
| `isActive` | `true` ou `false`. |

A resposta traz o artigo `{ id, title, content, isActive, createdAt, updatedAt }` dentro de `data`.

| Código | Quando acontece |
| - | - |
| `400` `ERR_INVALID_FIELD` | Com `field`: `content` vazio ou `null`, ou campo fora do tipo. |
| `400` `ERR_AI_AGENT_KB_TOO_LARGE` | `content` acima de 20.000 caracteres. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Excluir artigo

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/knowledge/delete/{aiAgentId}/{knowledgeId}
```

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

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/list/{aiAgentId}
```

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](#sincronizar-fonte) e [Excluir fonte](#excluir-fonte).

| Campo | Significado |
| - | - |
| `type` | `document`, `url` ou `faq`. |
| `status` | `ready` ou `error`. |
| `errorMessage` | Código do erro quando `status` é `error`. |
| `syncEnabled` | `true` = a página é buscada de novo todo dia de madrugada (veja [Importar link](#importar-link)). |
| `chunkCount` | Quantos trechos a fonte gerou. |

***

## Importar documento

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/document/{aiAgentId}
Content-Type: multipart/form-data
```

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`:

```bash theme={null}
curl -X POST "https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/document/{aiAgentId}" \
  -H "Authorization: Bearer {BearerToken}" \
  -F "media=@/caminho/tabela-de-precos.pdf"
```

| Campo | Obrigatório | Descrição |
| - | - | - |
| `media` | Sim | Arquivo, 1 por envio, até 10 MB. Formatos: `.pdf`, `.docx`, `.xlsx`, `.csv` e `.txt` (e `.json`, `.md` e `.markdown` com o recurso `kbJsonMd` de [Listar recursos do motor de agentes](#listar-recursos-do-motor-de-agentes)). O nome do arquivo precisa ter a extensão. |

> [!NOTE]
>
> 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](#base-de-conhecimento). A resposta é **201**, com a fonte criada dentro de `data`, no mesmo formato de [Listar fontes](#listar-fontes).

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` ou `ERR_AI_AGENT_REQUIRED_FIELDS` | Sem arquivo no campo `media`. |
| `400` `ERR_INVALID_FIELD` | Com `field` `media`: arquivo em outro campo, mais de 1 arquivo ou multipart malformado. |
| `400` `ERR_AI_AGENT_SOURCE_TYPE` | Formato não aceito. |
| `400` `ERR_AI_AGENT_SOURCE_PARSE` | Arquivo corrompido, com senha ou ilegível. |
| `400` `ERR_AI_AGENT_SOURCE_NO_TEXT` | Sem texto aproveitável (ex.: PDF escaneado). |
| `400` `ERR_AI_AGENT_SOURCE_LIMIT` | Limite de fontes ou de trechos. |
| `409` `ERR_AI_AGENT_SOURCE_DUPLICATE` | O mesmo conteúdo já foi importado neste agente. |
| `413` `ERR_AI_AGENT_FILE_TOO_LARGE` | Arquivo acima de 10 MB. |
| `429` `ERR_AI_AGENT_SOURCE_BUSY` | Outra importação de documento ou link em andamento. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Importar link

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/url/{aiAgentId}
```

```json theme={null}
{
  "url": "https://www.exemplo.com.br/perguntas-frequentes",
  "syncEnabled": false
}
```

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.

| Campo | Obrigatório | Descrição |
| - | - | - |
| `url` | Sim | `http` ou `https`. Endereço interno é recusado; no máximo 1 redirecionamento, 3 MB e 15 segundos. |
| `syncEnabled` | Não | Padrão `false`. `true` = a página é buscada de novo todo dia de madrugada; com a busca semântica ligada, cada atualização é vetorizada de novo. |

Este envio segue os limites e a regra de uma importação por vez de [Base de conhecimento](#base-de-conhecimento). Também responde **201**, com a fonte dentro de `data`, no formato de [Listar fontes](#listar-fontes).

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` ou `ERR_AI_AGENT_REQUIRED_FIELDS` | Sem `url`. |
| `400` `ERR_INVALID_FIELD` | Com `field`. |
| `400` `ERR_AI_AGENT_SOURCE_FETCH` | A página não abriu: endereço interno, fora do ar, grande demais ou lenta demais. |
| `400` `ERR_AI_AGENT_SOURCE_NO_TEXT` | Página sem texto aproveitável. |
| `400` `ERR_AI_AGENT_SOURCE_LIMIT` | Limite de fontes ou de trechos. |
| `409` `ERR_AI_AGENT_SOURCE_DUPLICATE` | O mesmo conteúdo já foi importado neste agente. |
| `429` `ERR_AI_AGENT_SOURCE_BUSY` | Outra importação de documento ou link em andamento. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Importar FAQ

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/faq/{aiAgentId}
```

```json theme={null}
{
  "items": [
    {
      "question": "Vocês entregam no sábado?",
      "answer": "Sim, das 8h às 12h."
    },
    {
      "question": "Quais são as formas de pagamento?",
      "answer": "Pix, cartão de crédito e boleto."
    }
  ],
  "name": "Entregas e pagamentos"
}
```

Importa perguntas e respostas (FAQ) para a base de conhecimento do agente.

| Campo | Obrigatório | Descrição |
| - | - | - |
| `items` | Sim | Lista de até 400 `{ question, answer }`. |
| `name` | Não | Nome da fonte. Vazio ou ausente = FAQ com a data do dia. |

> [!WARNING]
>
> **O FAQ não deduplica**: repetir o pedido cria outra fonte com as mesmas perguntas. Confira [Listar fontes](#listar-fontes) antes de repetir.

A resposta é **201**, com a fonte dentro de `data`, no formato de [Listar fontes](#listar-fontes).

| Código | Quando acontece |
| - | - |
| `400` `ERR_MISSING_FIELDS` ou `ERR_AI_AGENT_REQUIRED_FIELDS` | Sem `items`. |
| `400` `ERR_INVALID_FIELD` | Com `field`. |
| `400` `ERR_AI_AGENT_SOURCE_LIMIT` | Mais de 400 itens (com `field` `items`) ou limite de fontes do agente. |
| `400` `ERR_AI_AGENT_SOURCE_NO_TEXT` | Nenhum item com pergunta e resposta. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Sincronizar fonte

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/resync/{aiAgentId}/{sourceId}
```

Sincroniza de novo uma fonte da base de conhecimento. O corpo vai vazio (`{}`) e a resposta só sai quando a sincronização termina.

| Tipo da fonte | Resultado |
| - | - |
| Link | Busca a página outra vez e, se ela mudou, troca os trechos. Falha deixa a fonte com `status` `error`. |
| Documento | Com a busca semântica do agente ligada, refaz a vetorização dos trechos; sem ela, só atualiza a data. |
| FAQ | Não sincroniza: importe de novo. |

A resposta traz a fonte dentro de `data`, no formato de [Listar fontes](#listar-fontes).

| Código | Quando acontece |
| - | - |
| `400` `ERR_AI_AGENT_SOURCE_RESYNC_UNSUPPORTED` | Fonte FAQ. |
| `400` `ERR_AI_AGENT_SOURCE_FETCH` | A página não abriu. |
| `400` `ERR_AI_AGENT_SOURCE_NO_TEXT` | Página sem texto aproveitável. |
| `400` `ERR_AI_AGENT_SOURCE_LIMIT` | A página nova passa do limite de trechos. |
| Outros | Veja os [erros comuns](#erros-comuns-a-todas-as-rotas). |

***

## Excluir fonte

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/aiAgent/source/delete/{aiAgentId}/{sourceId}
```

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`.

> [!TIP]
>
> 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](https://ajuda.pandazap.com/platform/ai-agents.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.