Conhecimento e memória

Antes de indexar

Indexação e busca usam embeddings com a sua chave. Vincule a finalidade embedding a OpenAI text-embedding-3-small em Provedores. Sem isso, as fontes ficam em status: "queued" com last_error: "awaiting_embedding_key" (ou embedding_key_rejected, se a OpenAI recusar a chave), sem consumir tentativas. Vincular a finalidade ou validar a credencial devolve essas fontes à fila automaticamente; fontes prontas não são reindexadas. Para o agente usar uma fonte, inclua o ID em knowledge_source_ids da versão e habilite a ferramenta knowledge.search.

A versão publicada do agente congela quais fontes ele usa, não o conteúdo delas. Editar, substituir, reindexar ou inativar uma fonte vale nas próximas respostas de todos os agentes em operação que a incluem; o mesmo vale para a memória. O painel mostra esses agentes antes e depois de salvar.

Fontes

GET /ai/knowledge

Escopo agents:read

Query customer_id. Todas as fontes, das mais novas às mais antigas. Fontes importadas trazem import_kind (services, products ou conversation).

POST /ai/knowledge

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "name": "Perguntas frequentes",
  "kind": "faq",
  "text": "## Pergunta: Qual o prazo de entrega?\n## Resposta: Entregamos em até 7 dias úteis nas capitais.\n## Pergunta: Vocês parcelam?\n## Resposta: Sim, em até 6 vezes sem juros no cartão."
}

Responde 201 com a fonte em status: "queued". A indexação segue em segundo plano: queued → indexing → ready ou failed com last_error; PDF escaneado para em review até a aprovação no painel (o rascunho lido não é exposto na API). A versão anterior continua valendo até a nova ficar pronta. Na leitura por IA, last_error pode trazer vision_unavailable (sem chave que leia imagens: vincule a finalidade vision ou o padrão do Cliente a um provedor com visão), ocr_unavailable (o provedor não respondeu; reindexe), ocr_refused ou empty_document (nenhum texto legível nas páginas lidas). A leitura usa a chave do Cliente e entra no consumo de IA dele.

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Perguntas frequentes",
  "kind": "faq",
  "active": true,
  "revision": "1",
  "status": "queued",
  "last_error": null,
  "active_version_id": null,
  "pending_version_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
  "transcribed_by_ai": false,
  "created_at": "2026-09-25T13:00:00.000Z",
  "updated_at": "2026-09-25T13:00:00.000Z"
}

GET /ai/knowledge/{id}

Escopo agents:read

Query customer_id. Retorna source, text, file_name, versions e usages (versões de agente que usam a fonte).

PATCH /ai/knowledge/{id}

Escopo agents:write

Corpo {customer_id, expected_revision} e ao menos um de name (1–120), active ou text (1–500.000). Trocar o texto cria nova versão; fontes importadas recusam text com import_required.

DELETE /ai/knowledge/{id}

Escopo agents:write

Corpo {customer_id, expected_revision}. Responde 204. Fonte usada por versão publicada retorna 409 in_use.

POST /ai/knowledge/{id}/reindex

Escopo agents:write

Corpo {customer_id, expected_revision}. Reprocessa a versão atual. Em importações de serviços da Agenda, lê os serviços de novo.

GET /ai/knowledge/{id}/chunks

Escopo agents:read

Query customer_id. Trechos da versão ativa (id, source_id, version_id, ordinal, content, hash). Lista vazia enquanto não há versão pronta.

Busca e diagnóstico

POST /ai/knowledge/search

Escopo agents:read

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "source_ids": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "query": "prazo de entrega",
  "top_k": 5,
  "threshold": 0.3
}

Retorna os trechos com source_name e similarity; em fonte lida por IA, source_name termina com " (transcrito por IA)". Consome embeddings da sua chave. No atendimento, o agente busca só nas fontes da versão.

POST /ai/knowledge/search/diagnostics

Escopo agents:read

Mesmo corpo. Retorna hits e diagnostics: reason (ok, below_threshold, not_indexed, inactive, no_candidates), explanation, threshold, o melhor trecho abaixo do limite em best e o estado de cada fonte.

GET /ai/knowledge/citations

Escopo agents:read

Query customer_id e execution_id ou conversation_id. Trechos que embasaram respostas do agente (chunk_id, source_id, source_name, snippet, score, query). São dados internos da equipe; nunca vão para o contato.

POST /ai/knowledge/coverage

Escopo agents:read

Corpo {customer_id, knowledge_source_ids, skill_ids, allowed_stage_ids, tool_ids} (listas opcionais, até 100). Diagnóstico do editor: prontidão de fontes e skills, embedding_ready, etapas do funil que o agente pode mover (funnel) e issues.

Catálogo incremental

GET /ai/knowledge/{id}/catalog

Escopo agents:read

Query customer_id. Itens atuais do catálogo (items) e últimos eventos aplicados (last_events).

POST /ai/knowledge/{id}/catalog

Escopo agents:write

Aplica inclusões, alterações e remoções item a item, sem reenviar o catálogo inteiro. Itens inalterados reutilizam os embeddings; só os alterados são indexados de novo. Vale para fontes criadas por importação de products; outras retornam 422 catalog_sync_unsupported.

No total, até 1.000 itens por evento, cada id uma única vez. Com updated_at, um evento mais antigo que o último aplicado ao item é ignorado.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "event_key": "loja-2026-09-25T14:00:00Z-000123",
  "upserts": [
    {
      "id": "SKU-123",
      "name": "Cadeira ergonômica",
      "description": "Encosto com regulagem lombar.",
      "price": "899.90",
      "sku": "CAD-ERG-01",
      "permalink": "https://loja.exemplo.com.br/cadeira-ergonomica",
      "updated_at": "2026-09-25T13:58:00-03:00"
    }
  ],
  "removals": [
    {
      "id": "SKU-099"
    }
  ]
}

Retorna contadores (changed, removed, unchanged, stale, missing, items), reindex_queued, emptied, reactivated e replayed.

Importação revisada

POST /ai/knowledge/import

Escopo agents:write

Cria (201) ou atualiza uma fonte de catálogo ou conversa. Para atualizar, envie source_id e expected_revision juntos.

• kind: "services": importa os serviços ativos da Agenda. Sem serviço ativo: 422 catalog_empty.
• kind: "products": 1 a 1.000 produtos com IDs únicos.
• kind: "conversation": uma conversa encerrada, depois de autorizada e revisada.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "kind": "products",
  "name": "Catálogo da loja",
  "products": [
    {
      "id": "SKU-123",
      "name": "Cadeira ergonômica",
      "price": "899.90",
      "categories": [
        {
          "name": "Escritório"
        }
      ]
    }
  ]
}

Fluxo da conversa:

GET /ai/knowledge/conversations

Escopo agents:read

Query customer_id. Conversas encerradas com allowed, revision da permissão e source_id quando já importada.

PATCH /ai/knowledge/conversations/{id}/permission

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision, allowed}. Registra quem autorizou o uso da conversa.

GET /ai/knowledge/conversations/{id}/preview

Escopo agents:read

Query customer_id. Texto anonimizado que será indexado, com permission_revision, preview_hash, message_count e redactions. Mostre esse texto a uma pessoa antes de importar.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "kind": "conversation",
  "name": "Atendimento exemplar: troca",
  "conversation_id": "99999999-9999-4999-8999-999999999999",
  "permission_revision": "1",
  "preview_hash": "9f2c4b1e8d7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e",
  "reviewed": true
}

Mudou a conversa ou a permissão, o hash muda e a importação é recusada com conversation_review_required. Limite: 1.000 mensagens ou 500 mil caracteres.

Upload direto

Documentos de até 20 MiB (.txt, .md, .markdown, .csv, .pdf, inclusive escaneado, que vai para revisão) e pacotes de skill .zip de até 5 MiB vão direto ao armazenamento, sem passar pelo corpo da API.

POST /ai/uploads

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "kind": "knowledge",
  "name": "Tabela de preços",
  "file_name": "tabela-2026.pdf",
  "mime_type": "application/pdf",
  "byte_size": 3145728,
  "sha256": "4f8b42c22dd3729b519ba6f68d2da7cc5b2d606d05daed5ad5128cc03e6c6358"
}

Responde 201 com upload_id, upload_url, headers e expires_at. Guarde o upload_id e envie os bytes com PUT para upload_url usando exatamente headers, sem o token do BotoZap, cookies ou redirecionamentos. A URL é assinada e vale até 15 minutos: não a registre em logs.

POST /ai/uploads/{id}/complete

Escopo agents:write

Corpo {customer_id}. Confere tamanho, hash e tipo e cria a fonte (ou a skill). Retorna a fonte ou a skill. Se a resposta não chegar, repita com o mesmo ID: a importação não é duplicada.

POST /ai/knowledge/upload

Escopo agents:write

Alternativa multipart (customer_id, name, file) para arquivos pequenos. A hospedagem limita o corpo a cerca de 4 MiB; acima disso, use o upload direto. Responde 201 com a fonte.

Memória

A memória tem um documento do Cliente, versionado, e entradas avulsas, globais ou de um contato. Entradas criadas pela API ficam ativas na hora. Entradas propostas pelo agente (memory.propose), pela compactação de conversas ou pelo aprendizado ficam pending até uma aprovação. Desligar a memória interrompe o uso nas execuções seguintes.

GET /ai/memory

Escopo agents:read

Query customer_id. {enabled, revision, content, version_id}.

PUT /ai/memory

Escopo agents:write

Corpo {customer_id, expected_revision, content} (content até 50.000). Publica nova versão do documento.

PATCH /ai/memory

Escopo agents:write

Corpo {customer_id, expected_revision, enabled}. Liga ou desliga a memória do Cliente.

GET /ai/memory/versions

Escopo agents:read

Query customer_id. Versões do documento com content e created_at.

GET /ai/memory/entries

Escopo agents:read

Query customer_id, status (active, pending, archived) e contact_id opcionais. Cada entrada traz title, body, contact_id, source (manual ou proposal), provenance, status e revision.

POST /ai/memory/entries

Escopo agents:write

Corpo {customer_id, title (1–200), body (1–20.000), contact_id?, operation_key?}. Responde 201. Envie operation_key (UUID gerado por você) para repetir com segurança: a mesma chave com os mesmos dados devolve a mesma entrada com 200, sem criar outra; com dados diferentes, 409 idempotency_conflict. Sem a chave, cada chamada cria uma entrada nova.

PATCH /ai/memory/entries/{id}

Escopo agents:write

Corpo {customer_id, expected_revision, title, body}.

DELETE /ai/memory/entries/{id}

Escopo agents:write

Corpo {customer_id, expected_revision}. Arquiva a entrada e retorna-a com status: "archived". Arquivar é o padrão: o texto sai do contexto dos agentes e pode voltar com POST /ai/memory/entries/{id}/reactivate. Para apagar de vez, use /purge.

POST /ai/memory/entries/{id}/approve

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision}. Aprova uma entrada pendente.

POST /ai/memory/entries/{id}/reactivate

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision}. Devolve uma entrada arquivada ao contexto do agente.

POST /ai/memory/entries/{id}/purge

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision}. Exclui a entrada definitivamente, em qualquer status, numa única transação: apaga título, texto e histórico de eventos, e troca as cópias do texto guardadas nas execuções (rastro de ferramentas e checkpoint) e na proposta de aprendizado de origem por "Memória excluída". Não pode ser desfeita. Exige chave criada por um Administrador. Responde 200 só com a auditoria, sem texto: quem excluiu (actor_user_id ou actor_api_key_id), quando e o alcance (scope: customer ou contact).

{
  "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
  "entry_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
  "scope": "customer",
  "actor_user_id": null,
  "actor_api_key_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "purged_at": "2026-09-26T21:00:00.000Z",
  "replayed": false
}

Repetir a mesma exclusão (por exemplo, depois de perder a resposta) devolve o mesmo registro com replayed: true. Depois dela, a entrada some de GET /ai/memory/entries e GET /ai/memory/entries/{id}/events devolve uma lista vazia. Excluir o contato apaga também as entradas vinculadas a ele.

Reprocessamento automático não desfaz a exclusão. A auditoria guarda, sem texto, as origens automáticas da entrada: a chave de operação de quem a criou (memory.propose, compactação de conversa ou aprendizado) e a proposta de aprendizado vinculada. Se a mesma origem tentar criar a entrada de novo (um job repetido, uma execução retomada), nada é recriado: a operação termina como no-op e a tentativa é contada na auditoria. Entradas criadas por pessoas ou pela API (POST /ai/memory/entries) não são bloqueadas, nem mesmo com o mesmo texto.

GET /ai/memory/entries/{id}/events

Escopo agents:read

Query customer_id. Histórico: action (archived, reactivated, approved, status_changed), status anterior e novo, revisão e autor (usuário ou chave).

GET /ai/memory/checkpoints

Escopo agents:read

Query customer_id, agent_id e conversation_id opcionais. Resumos da compactação de conversas longas, com evidências, IDs das memórias pendentes geradas e estado, sem o texto bruto de origem.

Visão geral do Agente de IA · Próxima: Skills