Agente de IA pela API

Base https://botozap.com.br/api/v1 e Authorization: Bearer $BOTOZAP_API_KEY. O módulo usa exclusivamente chaves dos seus provedores de IA (BYOK). O provedor cobra o consumo; o BotoZap registra tokens e estimativas em Uso e orçamento, sem créditos ou recargas de IA.

Conceitos

• Agente: identidade que atende um canal. Tem no máximo um rascunho e várias versões publicadas.
• Versão: o config completo (instruções, modelo, credencial, canal, ferramentas, limites). O rascunho é editável. A versão publicada é imutável; mudar exige um novo rascunho.
• Operação: estado de atendimento do agente. paused liga ou desliga; mode escolhe automatic (envia sozinho) ou assisted (a resposta e as ações aguardam aprovação humana). Publicar não ativa o agente.
• Roteador: classifica a intenção da mensagem e escolhe entre agentes publicados do mesmo canal. Um canal tem um único responsável automático: um agente ativo ou um roteador ativo.
• Elegibilidade: decide quais contatos podem ser atendidos pela IA em cada canal. Todo canal começa fechado, respondendo só a números de teste.
• Credencial e finalidade: a chave do provedor fica no Vault. O atendimento e o operador usam a credencial da versão; o roteador usa a do classificador; as demais finalidades têm vínculo próprio.
• Execução: cada turno do agente, com resposta, ferramentas chamadas, consumo e trilha de proteção. Casos e alertas levam a equipe de volta à conversa original.

Checklist de go-live

1. Chave: crie uma chave live com agents:read e agents:write. Aprovar execuções, liberar acesso e decidir casos ou propostas exige que a chave tenha sido criada por um Administrador (papelowner ou admin).
2. Credencial: POST /ai/credentials valida a chave no provedor. Siga só com validation_status: "valid". Veja Credenciais e provedores.
3. Conhecimento (opcional): vincule a finalidade embedding a OpenAI text-embedding-3-small em PUT /ai/providers, crie as fontes e aguarde status: "ready". Veja Conhecimento e memória.
4. Rascunho: POST /ai/agents com o config. Veja Agentes e versões.
5. Teste: POST /ai/agents/{id}/preview. Usa o provedor real e a sua chave; as ações são simuladas e nada é enviado.
6. Publicação: POST /ai/agents/{id}/publish com a revisão do rascunho.
7. Liberar acesso: sem este passo o agente ativo só responde aos números de teste do canal, e a lista começa vazia. Cadastre testadores, valide e depois abra o canal por autorização de origem ou para todos em Acesso e elegibilidade.
8. Ativação: POST /ai/agents/{id}/operation com paused: false. Releia o agente antes: publicar incrementa operation_revision.
9. Operação: aprove execuções no modo assistido, trate casos e alertas e defina um orçamento. Veja Acompanhamento e Uso e orçamento.

Convenções

Conta, Cliente e chave

A Conta vem da chave autenticada; não envie account_id. Informe customer_id na query das leituras e no corpo das escritas, inclusive em DELETE. Todo ID citado precisa pertencer ao mesmo Cliente. A exceção é POST /conversations/{id}/agent-control, que identifica a conversa pelo caminho.

Todas as rotas exigem chave live: uma chave sandbox recebe 403 sandbox_forbidden. Leituras usam agents:read e alterações agents:write. Nas operações que registram autoria, o banco também exige que o criador da chave ainda seja Administrador (papel owner ou admin); a auditoria registra a chave separada do usuário.

Corpos

Corpos e respostas usam snake_case. Os schemas são estritos: um campo desconhecido gera 422 invalid. Sucesso vem em {"data": ...}; erro em {"error": {"code", "message"}}.

Revisões

Reenvie a revisão exatamente como leu. Strings não devem virar ponto flutuante. Revisão desatualizada retorna 409 revision_conflict: releia e decida de novo.

Idempotência

operation_key (UUID) identifica testes, inscrições, retornos, respostas de caso e avisos de teste; request_key faz o mesmo no teste do roteador e nas propostas comerciais. Sem resposta, repita com a mesma chave para obter o mesmo resultado. Não reutilize a chave para outro conteúdo. Um envio com resultado unknown nunca é repetido automaticamente: confira e concilie.

Paginação

• Página (page; per_page padrão 20, máximo 100): {data: [...], meta: {page, per_page, total_pages, total_count}} e os headers X-Total, X-Total-Pages, X-Per-Page e X-Page. Usada em agentes, execuções, casos e suas subcoleções, alertas, envios de avisos, propostas de aprendizado, propostas comerciais e inferências.
• Cursor (cursor; limit 1–100, padrão 30): {data: {data: [...], next_cursor}}. Usada na fila de follow-ups e nos retornos avulsos. Repita com cursor=next_cursor até vir null.
• Limite simples, sem página seguinte: autorizações de contato e inscrições (limit até 200, padrão 100), promessas do turno (até 100, padrão 50) e jobs de propostas comerciais (50 mais recentes).
• As demais listas devolvem o array completo em data.

Erros comuns

Um 503 não é lista vazia nem prova de que nada aconteceu. Em escritas, releia o recurso antes de repetir.

Páginas do guia

O módulo tem 153 operações. Cada página traz corpo, resposta, erros e exemplos.

• Credenciais e provedores: Chaves BYOK, finalidades, alternativas, modelos e catálogo do provedor.
• Agentes e versões: Rascunho, teste, publicação, operação e o schema completo de config e tool_ids.
• Acesso e elegibilidade: Quem pode ser atendido: números de teste, autorizações por origem e canal aberto.
• Conhecimento e memória: Fontes, busca, catálogo incremental, importações, uploads diretos e memória.
• Skills: Instruções versionadas, pacote ZIP, catálogo da plataforma e quase acertos.
• Roteadores: Classificação por intenção entre agentes publicados e tomada de canal.
• Follow-ups e retornos: Fluxos em grafo, inscrições, efeitos, retornos avulsos e fila.
• Acompanhamento: Execuções, casos, alertas, avisos, aprendizado, métricas e controle da conversa.
• Propostas comerciais: Próxima ação sugerida para um negócio do CRM, com decisão humana.
• Uso e orçamento: Inferências, consumo, orçamento mensal e tarifas por modelo.
• Referência de endpoints: Todas as operações do módulo, com escopo e página de cada uma.

Para conectar um agente executado fora do BotoZap aos eventos de canal, consulte Endpoint para agentes. As integrações de atendimento estão em Atendimento pela API.