Ciclo de vida
POST /ai/agentscria o agente e o primeiro rascunho. Ele não atende até ser ativado.PUT /ai/agents/{id}altera o rascunho, sempre com a revisão lida. Sem rascunho, o PUT cria um a partir do corpo enviado.POST /ai/agents/{id}/previewtesta uma versão sem efeitos.POST /ai/agents/{id}/publishdiagnostica e publica o rascunho. A versão fica imutável e o agente passa a apontar para ela. Publicar incrementaoperation_revisionmas não ativa o agente. Num agente em operação, publicar refaz o vínculo quando os canais mudam e incrementaoperation_revisionde novo (vejachannel_sync).POST /ai/agents/{id}/operationativa ou pausa e escolhe o modo. Antes, libere os canais em Acesso e elegibilidade.
Há duas revisões diferentes, ambas strings decimais:
versions[].revision: do rascunho. Vai emexpected_revisionno PUT e no publish, e emexpected_draft_revisionno restore.agent.operation_revision: da operação. Vai emexpected_revisionem operation e archive, e emexpected_agent_revisionao ativar um membro de roteador.
Estado e atendimento
GET /ai/agents e GET /ai/agents/{id} trazem, em cada agente, o estado real além de paused e archived. Use serving para saber se o agente está respondendo:
| Campo | Tipo e limites | Uso |
|---|---|---|
lifecycle | draft | published | active | paused | archived | Etapa do ciclo de vida, abaixo. |
serving | boolean | true quando o agente é, agora, quem responde em pelo menos um canal da versão publicada. |
serving_via | direct | router | null | direct: vínculo do próprio agente; router: membro do roteador ativo no canal; null quando não atende. Com vários canais, o do primeiro canal em que atende. |
channel_account_id | UUID | null | Primeiro canal da versão publicada; null sem versão publicada. |
channels | lista de {channel_account_id, serving, serving_via} | Um item por canal da versão publicada, na ordem da versão. Mostra o canal que ficou de fora ao ativar (ocupado por outro agente ou roteador). Um canal fora da versão que ainda tem vínculo não entra em channels nem em serving: veja channel_outside no diagnóstico. |
Valores de lifecycle:
draft: Nenhuma versão publicada. Não atende.published: Versão publicada, operação ainda não ativada. Não atende.active: Operação ativada. Atende se serving for true.paused: Tem versão publicada, mas a operação está pausada. Não atende.archived: Histórico preservado. Não atende.
serving só é true com lifecycle: active, credencial ativa e validada do provedor da versão, canal não revogado e fora do sandbox, e posse do canal: o vínculo do agente quando não há roteador ativo, ou a participação no roteador ativo do canal. Um agente active pode ter serving: false, por exemplo com a credencial desativada ou com um roteador ativo do qual não participa. No modo assisted, as respostas aguardam aprovação. serving não considera os contatos liberados: quem recebe resposta ainda depende da elegibilidade do canal.
Rotas
GET /ai/agents
Escopo agents:read
Query customer_id, page, per_page. Lista paginada de agentes, ordenada por nome, cada um no formato de agent abaixo, com lifecycle e serving.
POST /ai/agents
Escopo agents:write
| Campo | Tipo e limites | Uso |
|---|---|---|
customer_id | UUID | Cliente dono do agente. |
name | string 1–80 | Nome do agente. |
description | string até 2.000 | Opcional. |
config | objeto | Configuração da versão. Omitida, usa todos os padrões abaixo. |
Este exemplo é validado em teste contra o schema da rota:
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"name": "Atendimento",
"description": "Atendimento e acompanhamento da equipe",
"config": {
"system_prompt": "Atenda usando os materiais autorizados e encaminhe à equipe quando precisar de uma decisão humana.",
"provider": "openai",
"model": "MODELO_VALIDADO_NA_CREDENCIAL",
"credential_id": "22222222-2222-4222-8222-222222222222",
"channel_account_id": "33333333-3333-4333-8333-333333333333",
"tool_ids": [
"conversations.read",
"conversations.note",
"knowledge.search",
"cases.open",
"handoff"
],
"knowledge_source_ids": [
"77777777-7777-4777-8777-777777777777"
],
"skill_ids": [],
"cases_enabled": true,
"handoff_enabled": true
}
}Responde 201 com {agent_id, version_id, revision}.
GET /ai/agents/{id}
Escopo agents:read
Query customer_id. Retorna o agente e todas as versões, cada uma com o config completo.
{
"agent": {
"id": "44444444-4444-4444-8444-444444444444",
"customer_id": "11111111-1111-4111-8111-111111111111",
"name": "Atendimento",
"description": "Atendimento e acompanhamento da equipe",
"operation_mode": "automatic",
"operation_revision": "4",
"paused": false,
"archived": false,
"published_version_id": "55555555-5555-4555-8555-555555555555",
"updated_at": "2026-09-25T13:00:00.000Z",
"lifecycle": "active",
"serving": true,
"serving_via": "direct",
"channel_account_id": "33333333-3333-4333-8333-333333333333",
"channels": [
{
"channel_account_id": "33333333-3333-4333-8333-333333333333",
"serving": true,
"serving_via": "direct"
}
]
},
"versions": [
{
"id": "55555555-5555-4555-8555-555555555555",
"agent_id": "44444444-4444-4444-8444-444444444444",
"number": 2,
"revision": "3",
"status": "published",
"config": "{ ... }",
"created_at": "2026-09-24T18:00:00.000Z",
"published_at": "2026-09-25T12:58:00.000Z",
"created_by": null
}
]
}PUT /ai/agents/{id}
Escopo agents:write
Mesmo corpo da criação mais expected_revision. Com rascunho existente, a revisão é obrigatória e precisa ser a atual. Sem rascunho, omita-a: um novo rascunho é criado. Retorna {agent_id, version_id, revision}. O config enviado substitui o anterior inteiro; campos omitidos voltam ao padrão.
POST /ai/agents/{id}/preview
Escopo agents:write
| Campo | Tipo e limites | Uso |
|---|---|---|
version_id | UUID | Rascunho ou versão publicada do agente. |
operation_key | UUID | Repetir a chave com os mesmos dados devolve a mesma execução; com outros dados, 409 idempotency_conflict. |
messages | 1–200 itens {role: user|assistant, content ≤20.000} | A última mensagem precisa ser do usuário. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"version_id": "55555555-5555-4555-8555-555555555555",
"operation_key": "66666666-6666-4666-8666-666666666666",
"messages": [
{
"role": "user",
"content": "Qual o prazo de entrega para Manaus?"
}
]
}Retorna uma execução, no mesmo formato de Execuções. Usa o provedor real e consome a sua chave. Só conhecimento, memória e skills são consultados de verdade; as demais ferramentas, inclusive leituras, devolvem uma simulação. Nada é enviado ao contato. Com o operador ligado, operator_execution traz a revisão dele.
Testar, completar a base e comparar respostas
No Studio, cada resposta conserva seus Trechos consultados, com nome, trecho e consulta. São registros da execução, não uma nova busca. Eles indicam consulta e não comprovam que cada trecho foi usado na resposta. Sem citações, o teste mostra um estado neutro. Encaminhamento concluído ou busca explicitamente vazia oferecem “Se faltou informação, adicione uma fonte”; um pedido de atendente também pode ter outros motivos.
- Execute o preview e guarde o ID, a resposta e o contexto até a última pergunta. Leia as citações por
execution_id. - Crie uma fonte ou edite a existente com a revisão atual. O editor abre no próprio Studio, preservando o teste. Fontes importadas e OCR mantêm seus fluxos de atualização e revisão.
- Guarde
pending_version_id ?? active_version_iddevolvido na escrita. Aguarde a fonte ativa, sem erro, comstatus:ready, sem versão pendente e comactive_version_idigual ao ID esperado. Umreadyda versão anterior não basta. - Para fonte nova, vincule explicitamente em
config.knowledge_source_ids, habiliteknowledge.searche salve o rascunho via PUT. O servidor valida ownership. Não precisa publicar para testar. - Clique em Refazer última pergunta. Pela API, envie o contexto até a pergunta, sem a resposta anterior e sem duplicar a pergunta, com uma nova
operation_key. Mantenha a chave desta tentativa se o transporte ficar incerto.
Cada inferência pode gerar custo e só acontece por ação explícita. A resposta anterior e suas fontes ficam para comparação; as mensagens seguintes usam a nova resposta. Alterar conta, cliente, agente, versão ou começar outra conversa invalida o reteste pendente. Atualizar a página preserva a sessão de teste nesta aba; mudar a revisão do agente invalida o reteste guiado. Editar uma fonte compartilhada afeta também os agentes publicados que a usam; confira o aviso antes de salvar.
Exemplo canônico das operações existentes (use os IDs e revisões recebidos nas respostas):
{
"preview": {
"method": "POST",
"path": "/api/v1/ai/agents/44444444-4444-4444-8444-444444444444/preview",
"scope": "agents:write",
"body": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"version_id": "55555555-5555-4555-8555-555555555555",
"operation_key": "66666666-6666-4666-8666-666666666666",
"messages": [
{
"role": "user",
"content": "Qual o prazo de entrega para Manaus?"
}
]
}
},
"citations": {
"method": "GET",
"path": "/api/v1/ai/knowledge/citations",
"scope": "agents:read",
"query": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"execution_id": "88888888-8888-4888-8888-888888888888"
}
},
"create": {
"method": "POST",
"path": "/api/v1/ai/knowledge",
"scope": "agents:write",
"body": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"name": "Prazos de entrega",
"kind": "text",
"text": "Para Manaus, a entrega leva sete dias úteis."
}
},
"edit": {
"method": "PATCH",
"path": "/api/v1/ai/knowledge/77777777-7777-4777-8777-777777777777",
"scope": "agents:write",
"body": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"expected_revision": "1",
"text": "Para Manaus, a entrega leva cinco dias úteis."
}
},
"status": {
"method": "GET",
"path": "/api/v1/ai/knowledge/77777777-7777-4777-8777-777777777777",
"scope": "agents:read",
"query": {
"customer_id": "11111111-1111-4111-8111-111111111111"
}
},
"link": {
"method": "PUT",
"path": "/api/v1/ai/agents/44444444-4444-4444-8444-444444444444",
"scope": "agents:write",
"body": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"expected_revision": "1",
"name": "Atendimento",
"description": "",
"config": {
"system_prompt": "Atenda usando somente os materiais autorizados.",
"provider": "openai",
"model": "MODELO_VALIDADO_NA_CREDENCIAL",
"credential_id": "22222222-2222-4222-8222-222222222222",
"tool_ids": [
"knowledge.search"
],
"knowledge_source_ids": [
"77777777-7777-4777-8777-777777777777"
]
}
}
},
"retest": {
"method": "POST",
"path": "/api/v1/ai/agents/44444444-4444-4444-8444-444444444444/preview",
"scope": "agents:write",
"body": {
"customer_id": "11111111-1111-4111-8111-111111111111",
"version_id": "55555555-5555-4555-8555-555555555555",
"operation_key": "99999999-9999-4999-8999-999999999999",
"messages": [
{
"role": "user",
"content": "Qual o prazo de entrega para Manaus?"
}
]
}
}
}POST /ai/agents/{id}/publish
Escopo agents:write
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"version_id": "55555555-5555-4555-8555-555555555555",
"expected_revision": "3"
}Retorna {version_id, number, channel_sync}. Antes de publicar, o servidor roda no rascunho o mesmo diagnóstico do painel. Se alguma verificação bloquear, a publicação é recusada com 422 diagnostic_blocked e error.blockers, a lista de pendências. Veja os requisitos de publicação.
Agente em operação com vínculo próprio (não só como membro de roteador), cuja versão nova muda os canais em relação à publicada antes, tem o vínculo refeito com os canais dela na mesma chamada. Publicar de novo com os mesmos canais não tenta outra vez o canal que ficou de fora: para isso, pause e ative o agente. channel_sync diz o que aconteceu: {status: "unchanged"} quando não havia o que mudar (agente pausado, só publicado, membro de roteador ou mesmos canais); {status: "synced", skipped} com os canais que ficaram de fora; {status: "failed", code} quando nenhum canal pôde ser ligado. Nesse caso a versão continua publicada, os vínculos de antes ficam e code explica, por exemplo duplicate_responder.
{
"error": {
"code": "diagnostic_blocked",
"message": "O diagnóstico do rascunho tem verificações que impedem a publicação. Resolva as pendências e publique de novo. Pendências: Elegibilidade para atender.",
"blockers": [
{
"id": "eligibility",
"title": "Elegibilidade para atender",
"status": "blocked",
"detail": "Somente números de teste, e nenhum número de teste foi cadastrado em Loja Centro: a IA não responde a ninguém. Cadastre um número de teste ou abra o canal em Acesso da IA."
}
]
}
}POST /ai/agents/{id}/restore
Escopo agents:write
Corpo {customer_id, version_id, expected_draft_revision?}. Copia o config de uma versão para o rascunho. Se já existir rascunho, informe a revisão dele. Não publica nem ativa.
POST /ai/agents/{id}/duplicate
Escopo agents:write
Corpo {customer_id, name}. Cria outro agente com o rascunho (ou a versão publicada) copiado, sem canal e inativo. Retorna {agent_id, version_id, revision}.
POST /ai/agents/{id}/archive
Escopo agents:write
Corpo {customer_id, expected_revision, archived}, com operation_revision. Arquivar pausa o agente, libera os canais e preserva o histórico. Desarquivar não reativa. Retorna {id, revision, archived}.
POST /ai/agents/{id}/operation
Escopo agents:write
| Campo | Tipo e limites | Uso |
|---|---|---|
expected_revision | string | operation_revision atual. |
mode | automatic | assisted | assisted: resposta e ações aguardam aprovação. |
paused | boolean | false ativa; true pausa. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"expected_revision": "2",
"mode": "assisted",
"paused": false
}Retorna {revision, paused, mode, skipped}. Ativar exige versão publicada e credencial ativa e válida, e vincula o agente aos canais da versão publicada. Canal com outro agente vinculado, com roteador ativo ou que não é mais do Cliente fica de fora e volta em skipped, cada um com channel_account_id e reason (agent, router ou missing); os outros são ligados. Sem nenhum canal livre, retorna 409 duplicate_responder (ou 404 channel_not_found quando nenhum canal é mais do Cliente) e nada muda. Ativar também desfaz o vínculo com canal que saiu da versão publicada. Trocar o modo com paused: false num agente em operação refaz o vínculo do mesmo jeito, e pode devolver skipped ou 409. Pausar mantém o vínculo e devolve skipped: []; arquivar o libera.
O campo paused sozinho não diz se o agente atende: um agente recém-criado ou só publicado tem paused: false e ainda não foi ativado. Leia lifecycle e serving em GET /ai/agents.
GET /ai/agents/{id}/capability-usage
Escopo agents:read
Query customer_id e days (1–90, padrão 30). Compara o uso real de cada ferramenta com a versão publicada (ou o rascunho, se nada foi publicado): agent e operator com summary e items (tool, enabled, signal, recommendation, total, failures, unknown, test, last_at). Falha de leitura é 503, nunca zero.
GET /ai/agents/{id}/diagnostic
Escopo agents:read
Query customer_id. Devolve o mesmo diagnóstico do painel, para o rascunho ou, sem rascunho, para a versão publicada (version_id, version_number, version_status). Cada item de checks tem id, title, status (ok, warning, blocked ou unknown), detail, blocking e action: onde a pessoa corrige no painel, um caminho como /ia/provedores ou #grupo-… para um grupo da configuração do agente, ou null. ready é false quando algum item com blocking: true não está ok: é a mesma regra que recusa a publicação com diagnostic_blocked. Um item que não pôde ser lido vem como unknown, nunca como ok.
Os itens de canal (channel, eligibility e self_tester) saem um por canal da versão. Com vários canais, o id leva o canal (channel:<channel_account_id>, eligibility:<channel_account_id>, self_tester:<channel_account_id>) e o title, o nome dele. Com vários canais, o que só afeta um canal (canal inativo, acesso da IA sem testador) vira warning enquanto outro canal está pronto para atender; canal de outro Cliente ou de outro tipo continua bloqueando. channel_outside:<channel_account_id> avisa, com o agente em operação, que ele ainda atende num canal que não está na versão publicada (a publicação não achou canal livre, por exemplo).
generation_proof é o resultado da última prova de geração registrada (never, ok, failed, unknown, running ou stale). Esta leitura não faz prova nem chamada ao provedor e não gera custo.
{
"agent_id": "44444444-4444-4444-8444-444444444444",
"version_id": "55555555-5555-4555-8555-555555555555",
"version_number": 3,
"version_status": "draft",
"ready": true,
"checks": [
{
"id": "configuration",
"title": "Configuração mínima",
"status": "ok",
"detail": "Instruções, modelo, credencial e canal preenchidos.",
"blocking": true,
"action": null
},
{
"id": "knowledge_tool",
"title": "Consulta à base de conhecimento",
"status": "warning",
"detail": "1 fonte de conhecimento está selecionada, mas a ferramenta \"Consultar base de conhecimento\" está desligada: o agente não consulta esse material e responde só com as instruções. Ligue a ferramenta em O que ele pode fazer.",
"blocking": false,
"action": {
"href": "#grupo-capacidades",
"label": "Ligar a consulta à base"
}
},
{
"id": "audio",
"title": "Áudios recebidos",
"status": "warning",
"detail": "Nenhuma chave foi escolhida para Transcrição de áudio, e essa finalidade não usa a chave padrão. Quando um contato mandar áudio, o agente não consegue ouvir e responde pedindo para escrever. Escolha uma chave da OpenAI em Transcrição de áudio, em Provedores e chaves.",
"blocking": false,
"action": {
"href": "/ia/provedores",
"label": "Abrir Provedores e chaves"
}
}
],
"generation_proof": {
"status": "ok",
"at": "2026-10-23T14:02:11.000Z",
"detail": "O provedor aceitou uma geração real com esta chave e este modelo."
}
}Avisos que não bloqueiam e mostram o que o agente não vai fazer como esperado: knowledge_tool (fontes marcadas sem knowledge.search no agente nem no operador), knowledge_sources (fonte marcada aguardando a chave de conhecimento, com falha, em revisão, inativa ou removida), audio (sem vínculo de transcription, que não herda o padrão), vision (o catálogo do provedor diz que o modelo de imagens não aceita imagens), self_tester (o próprio número ou a própria conta na lista de teste), channel (canal com outro agente ou roteador, que fica de fora ao ativar, ou canal ainda sem vínculo com o agente em operação), channel_outside (vínculo num canal fora da versão publicada), operation (operação não ativada, ou ativa no modo assisted) e publication (nunca publicado, ou rascunho diferente da versão publicada).
| Status | Código | Quando |
|---|---|---|
| 404 | not_found | Agente ou versão inexistente neste Cliente. |
| 404 | channel_not_found | Canal que não pertence ao Cliente ou não está ativo. No PUT, vale para cada canal da lista; ao ativar, quando nenhum canal da versão é mais do Cliente. |
| 409 | revision_conflict | Revisão do rascunho ou da operação desatualizada. |
| 409 | duplicate_responder | Ao ativar, nenhum canal da versão está livre: todos com outro agente ou roteador. |
| 409 | credential_unavailable | Credencial inativa (inclusive as de provedores descontinuados), não validada ou de outro provedor. |
| 409 | agent_archived | Editar, publicar ou ativar um agente arquivado. |
| 409 | agent_unavailable | Ativar sem versão publicada. |
| 409 | published_version_immutable | Publicar uma versão já publicada. |
| 409 | idempotency_conflict | operation_key repetida com dados diferentes. |
| 409 | stage_scope_invalid · knowledge_scope_invalid · skill_scope_invalid · file_scope_invalid · followup_scope_invalid | ID de etapa, fonte ativa, skill ativa, arquivo ativo (pronto ou convertendo) ou fluxo publicado inválido na publicação. |
| 422 | incomplete_configuration | Publicar ou testar sem instruções, modelo, credencial ou canal. |
| 422 | diagnostic_blocked | Publicar com uma verificação do diagnóstico bloqueando. error.blockers lista cada pendência (id, title, status, detail). |
| 422 | invalid | Corpo fora do schema ou ID malformado. |
| 422 | provider_not_enabled | Rascunho com provedor que não seja OpenAI ou Anthropic, no agente ou no operador. |
| 422 | publish_required · incompatible_send_windows | Follow-up ligado com fluxo não publicado ou sem horário em comum. |
Requisitos de publicação
A publicação pelo painel e pela API segue a mesma regra: o rascunho é diagnosticado no servidor e qualquer verificação bloqueante recusa a publicação com diagnostic_blocked. Uma verificação que não pôde ser lida também bloqueia; ela nunca conta como aprovada. A prova de geração é opcional e não bloqueia. Bloqueiam:
system_promptcom ao menos 10 caracteres emodelpreenchido.credential_idativa, validada e do mesmoprovider. Com operador próprio, a credencial dele também.- Ao menos um canal em
channel_account_ids(ouchannel_account_id), e todos os da lista do Cliente: Número do WhatsApp ou conta do Instagram. allowed_stage_ids,knowledge_source_ids,skill_idsefile_idsexistentes e ativos no Cliente (arquivo pronto ou ainda convertendo); fluxos defollowup.flow_idspublicados, com janela de envio compatível.- Ferramentas que só consultam outros contatos (
contacts.search,radar.read,crm.search) exigemdata_access.other_contacts: true. - Chave validada pelo provedor, com o
modelno catálogo dela e compatível com atendimento. Com operador próprio, a credencial e o modelo dele também. - Cada canal ativo, do Cliente, WhatsApp ou Instagram, e fora do sandbox.
- Cada canal elegível: conta fora de exclusão e canal que aceita IA. Com o canal em
pre_go_livee nenhum número emtest_phone_numbers, a IA não responderia a ninguém, então a publicação é recusada. Cadastre um número de teste ou mude o modo em Acesso e elegibilidade. - Com vários canais, basta um pronto: nos outros, canal inativo, de sandbox ou sem testador vira
warninge não recusa a publicação. Canal de outro Cliente ou de outro tipo recusa sempre.
Avisos não bloqueiam: outro agente ou roteador ativo no canal, ferramentas sem efeito, regras da empresa ausentes, proteções desligadas e os avisos de atendimento listados em GET /ai/agents/{id}/diagnostic.
Como o agente recebe o contexto
O prompt começa com a identidade e as instruções do negócio, seguidas de um guia de escrita para WhatsApp e Instagram. Depois vêm a memória publicada do Cliente, as entradas autorizadas de memória do Cliente e o índice de skills, as regras adicionais e as regras da plataforma. As skills ativas vêm depois da parte estável; não alteram a proteção da plataforma.
Com knowledge.search habilitada e fontes ativas já indexadas, o agente pesquisa a base antes de responder a mensagens que não sejam triviais. Os melhores trechos entram como dados de referência do negócio, sem autorizar mudanças nas regras. A busca usa embeddings cobrados na sua configuração de IA e registra as citações; a ferramenta continua disponível para pesquisas adicionais. Se essa busca inicial falhar, o atendimento segue sem os trechos.
Mensagens, arquivos, transcrições, resumo da conversa, casos, memória do contato e contexto do turno ficam como dados, separados das instruções de sistema. O contexto do turno inclui data, hora, fuso, canal e nome do contato quando disponível. Esses dados não autorizam preços ou ações nem mudanças nas regras. As condições comerciais precisam vir das instruções publicadas, da memória do Cliente, das skills ou de fontes de negócio autorizadas. Um total também é aceito quando é a soma de preços dessas fontes citados na própria resposta, cada um uma vez, multiplicados por 1 ou por uma quantidade escrita na resposta.
Uma regra da plataforma vale para todo negócio: se o contato relatar suicídio, autolesão, violência ou emergência médica, o agente acolhe, indica CVV (188), SAMU (192) ou polícia (190) e encaminha para a equipe quando o encaminhamento estiver habilitado; isso nunca conta como fora do escopo. Relato de risco à vida abre um alerta crítico life_risk_contact mesmo quando o agente responde. Os demais sinais de urgência abrem urgent_contact só quando o turno não sai automaticamente.
Schema do config
O schema é estrito: chave desconhecida gera 422. Todo campo tem padrão. Estes são os valores aplicados a um config vazio:
{
"system_prompt": "",
"provider": "openai",
"model": "",
"credential_id": null,
"channel_account_id": null,
"tool_ids": [],
"operator": {
"enabled": false,
"provider": null,
"model": null,
"credential_id": null,
"tool_ids": []
},
"trigger": {
"keywords": [],
"match": "any",
"ignore_groups": true,
"ignore_self": true
},
"time_zone": "America/Sao_Paulo",
"business_hours": null,
"outside_hours": "respond",
"max_steps": 10,
"token_budget": 150000,
"estimated_cost_limit_usd": null,
"history_message_window": 20,
"history_token_window": 8000,
"handoff_keywords": [
"falar com humano",
"atendente",
"pessoa real"
],
"handoff_enabled": true,
"cases_enabled": true,
"split_messages": false,
"split_max_chars": 600,
"crm_scopes": [],
"allowed_stage_ids": [],
"knowledge_source_ids": [],
"skill_ids": [],
"platform_skills": "none",
"memory_enabled": true,
"data_access": {
"other_contacts": false
},
"accountability": {
"enabled": false,
"classification": false
},
"media": {
"images_enabled": true,
"documents_enabled": true,
"video_frames_enabled": false
},
"followup": {
"enabled": false,
"flow_ids": [],
"send_window": null,
"return_template": null
},
"safety": {
"disclose_ai": true,
"prohibited_claims": [],
"escalation_instructions": "",
"additional_rules": [],
"disclosure_text": "",
"commercial_limits": {
"min_price_brl": null,
"max_discount_percent": null,
"max_installments": null
},
"guard_sensitivity": "standard",
"semantic_evaluator": false
},
"style": {
"tone": "friendly",
"verbosity": "balanced",
"use_emojis": false,
"instructions": ""
}
}| Campo | Tipo e limites | Uso |
|---|---|---|
system_prompt | string até 20.000 | Instruções. Mínimo de 10 caracteres para publicar. |
provider | anthropic, openai | Provedor do modelo de atendimento. Uma versão antiga com provedor descontinuado (google, openrouter, deepseek, xai) continua legível, mas salvar retorna 422 provider_not_enabled e publicar, 422 incomplete_configuration. |
model | string até 200 | ID do modelo, como listado na credencial. |
credential_id · channel_account_id | UUID ou null | null só no rascunho. channel_account_id é o primeiro canal. |
channel_account_ids | lista de UUID, até 10, sem repetir | Canais em que o mesmo agente atende (WhatsApp e Instagram do Cliente). Com dois ou mais, channel_account_id é o primeiro; com um, a lista não é gravada. channel_account_id que está na lista fora do primeiro lugar retorna 422 invalid; fora da lista, ele manda e a lista vira esse canal. |
tool_ids | lista sem repetição | Ferramentas do agente. Veja o catálogo. |
operator | {enabled, provider, model, credential_id, tool_ids} | Operador revisa o turno com ferramentas próprias. provider, model e credential_id vão juntos ou todos null (herda do agente). |
trigger | {keywords ≤40 de até 80, match: any|all, ignore_groups: true, ignore_self: true} | Sem palavras-chave, responde a toda mensagem elegível. |
time_zone | fuso IANA | Padrão America/Sao_Paulo. |
business_hours | {start HH:MM, end HH:MM, weekdays 0–6} ou null | start antes de end; dias sem repetição (0 = domingo). |
outside_hours | respond | wait | handoff | Fora de business_hours: responde, adia até a próxima abertura ou passa para a equipe. |
max_steps | 1–25 | Passos de ferramenta por turno. Padrão 10. |
token_budget | 1.000–500.000 | Tokens de entrada e saída somados em todas as etapas do turno. Padrão 150.000. Cada etapa com ferramenta reenvia o contexto e conta de novo, inclusive a parte lida do cache do provedor. Ao atingir o limite, o turno termina com finish_reason token_budget, sem resposta: o agente passa para a equipe (se handoff_enabled) ou abre um alerta. |
estimated_cost_limit_usd | maior que 0 e até 100, ou null | Teto estimado por execução, em dólares. |
history_message_window · history_token_window | 0–200 · 0–50.000 | Histórico enviado ao modelo. Pausas de 6 horas ou mais e mensagens que não foram escritas pelo agente (equipe, app, API, automações) chegam sinalizadas. |
handoff_keywords | até 30 de até 80 | Frases que transferem para a equipe. |
handoff_enabled · cases_enabled | boolean | Liberam a ferramenta handoff e as de casos. |
split_messages · split_max_chars | boolean · 80–4.000 | Divide respostas longas. |
crm_scopes | contacts, opportunities, demands | Vazio = nenhum acesso ao CRM. |
allowed_stage_ids | até 100 UUIDs | Únicas etapas para onde o agente pode mover. |
knowledge_source_ids · skill_ids | até 100 UUIDs cada | Fontes e skills autorizadas. |
file_ids | até 40 UUIDs, opcional | Arquivos que o agente pode mandar; com conversations.attach_files em tool_ids. Veja Arquivos do agente. |
platform_skills | none | all | Compõe as skills da plataforma. Veja Skills. |
memory_enabled | boolean | Lê e propõe memória. |
data_access.other_contacts | boolean | Autoriza ler outros contatos e conversas. |
accountability | {enabled, classification} | Fechamento do turno com promessas e sugestão de etapa. Gera uma inferência adicional por turno. |
media | {images_enabled, documents_enabled, video_frames_enabled} | Mídias que o agente lê. Com o tipo desligado, o agente sabe que o arquivo chegou, mas não lê o conteúdo e responde pelas instruções. |
followup | {enabled, flow_ids ≤100, send_window ou null, return_template ou null} | Com enabled, ao menos um fluxo. return_template {template_id, variable_map}: template aprovado que o retorno agendado pelo agente (followups.schedule) envia com a janela de 24 horas fechada, só no WhatsApp; sem ele, o retorno vira alerta. O agente não escolhe outro template. |
safety | ver abaixo | Camada do Cliente acima da política obrigatória da plataforma. |
style | {tone, verbosity, use_emojis, instructions ≤4.000} | tone: professional, friendly, direct. verbosity: concise, balanced, detailed. |
safety
| Campo | Tipo e limites | Uso |
|---|---|---|
disclose_ai | boolean | Informa que é uma IA. |
disclosure_text | string até 300 | Texto do aviso. |
prohibited_claims | até 50 de até 300 | Afirmações que o agente não pode fazer. |
additional_rules | até 30 de até 500 | Regras extras. |
escalation_instructions | string até 4.000 | Quando e como escalar. |
commercial_limits | {min_price_brl, max_discount_percent 0–100, max_installments 1–120} | Tetos conferidos antes do envio; null = sem tabela. |
guard_sensitivity | standard | strict | No turno do agente, falhas transitórias ou resposta inválida repetem a classificação uma vez. standard: se o modelo continuar indisponível, segue pela heurística sem tentativa clara e registra alerta. strict: indisponibilidade e sinais leves retêm. Falta de vínculo, orçamento recusado ou entrada truncada retêm nas duas sensibilidades. Follow-ups preservam a retenção quando o detector fica indisponível. |
semantic_evaluator | boolean | Avaliação adicional antes do envio. |
Catálogo de ferramentas
57 valores aceitos em tool_ids e operator.tool_ids. A lista vem do código. O servidor aplica as exigências a cada chamada; uma ferramenta fora delas é recusada no turno, sem efeito.
| tool_id | O que faz | Grupo e risco | Exige |
|---|---|---|---|
contacts.read | Consultar o contato atual | Atender e responder · Só olha | crm_scopes com contacts |
contacts.update | Atualizar o contato atual | Atender e responder · Faz mudanças | crm_scopes com contacts |
conversations.read | Consultar a conversa atual | Atender e responder · Só olha | — |
conversations.note | Adicionar nota interna | Atender e responder · Faz mudanças | — |
crm.opportunities.read | Consultar oportunidades do contato | Vender e mover o funil · Só olha | crm_scopes com opportunities |
crm.opportunities.write | Atualizar oportunidades do contato | Vender e mover o funil · Faz mudanças | crm_scopes com opportunities; mudança de etapa limitada a allowed_stage_ids |
crm.demands.read | Consultar demandas do contato | Vender e mover o funil · Só olha | crm_scopes com demands |
crm.demands.write | Atualizar demandas do contato | Vender e mover o funil · Faz mudanças | crm_scopes com demands; mudança de etapa limitada a allowed_stage_ids |
crm.stages.read | Consultar etapas permitidas | Vender e mover o funil · Só olha | lista só as etapas de allowed_stage_ids |
crm.stages.write | Mover etapa do contato | Vender e mover o funil · Faz mudanças | etapa de destino em allowed_stage_ids |
agenda.availability | Consultar disponibilidade | Não perder o cliente · Só olha | — |
agenda.propose | Propor agendamento (o contato confirma) | Não perder o cliente · Faz mudanças | confirmação do contato |
agenda.appointments.read | Consultar compromissos do contato | Não perder o cliente · Só olha | — |
agenda.appointments.reschedule | Reagendar compromisso do contato | Não perder o cliente · Faz mudanças | — |
agenda.appointments.cancel | Cancelar compromisso do contato | Não perder o cliente · Faz mudanças | — |
knowledge.search | Consultar base de conhecimento | Aprender e evoluir · Só olha | busca só em knowledge_source_ids |
memory.read | Consultar memória | Aprender e evoluir · Só olha | memory_enabled |
memory.propose | Propor memória para revisão | Aprender e evoluir · Faz mudanças | memory_enabled; aprovação humana |
skills.read | Ler habilidades | Aprender e evoluir · Só olha | lê só skill_ids |
followups.enroll | Inscrever em acompanhamento | Não perder o cliente · Faz mudanças | followup.enabled e fluxo em followup.flow_ids |
followups.pause | Pausar acompanhamento | Não perder o cliente · Faz mudanças | followup.enabled |
followups.cancel | Cancelar acompanhamento ou retorno agendado | Não perder o cliente · Faz mudanças | followup.enabled para inscrições; retornos avulsos não exigem |
cases.open | Abrir caso | Passar para uma pessoa · Faz mudanças | cases_enabled; abrir com transferência exige handoff_enabled |
cases.update | Devolver informação a um caso | Passar para uma pessoa · Faz mudanças | cases_enabled |
handoff | Transferir para atendente | Passar para uma pessoa · Só uma pessoa desfaz | handoff_enabled |
alerts.create | Criar alerta | Passar para uma pessoa · Faz mudanças | — |
followups.schedule | Agendar retorno prometido ao contato | Não perder o cliente · Faz mudanças | — |
followups.list | Consultar retornos e acompanhamentos do contato | Não perder o cliente · Só olha | — |
contacts.search | Buscar outros contatos | Atender e responder · Só olha | crm_scopes com contacts; data_access.other_contacts obrigatório para publicar |
contacts.get | Consultar um contato pelo ID | Atender e responder · Só olha | crm_scopes com contacts; outros contatos só com data_access.other_contacts |
contacts.propose_update | Sugerir mudança no cadastro (pessoa confirma) | Atender e responder · Faz mudanças | crm_scopes com contacts; aprovação humana |
conversations.list | Listar conversas | Atender e responder · Só olha | outros contatos só com data_access.other_contacts |
conversations.get | Consultar uma conversa (a atual ou outra pelo ID) | Atender e responder · Só olha | outros contatos só com data_access.other_contacts |
conversations.history | Ler histórico de uma conversa | Atender e responder · Só olha | outros contatos só com data_access.other_contacts |
conversations.assign | Atribuir a conversa atual a uma pessoa | Passar para uma pessoa · Faz mudanças | — |
team.members.read | Consultar equipe | Organizar a operação · Só olha | — |
inbox.queue.read | Consultar fila de atendimento | Organizar a operação · Só olha | — |
tags.read | Consultar marcadores em uso | Organizar a operação · Só olha | — |
tags.manage | Adicionar/remover marcadores do contato | Organizar a operação · Faz mudanças | — |
saved_replies.read | Consultar respostas rápidas | Atender e responder · Só olha | — |
saved_replies.render | Preencher resposta rápida | Atender e responder · Só olha | — |
automations.read | Consultar réguas de automação | Organizar a operação · Só olha | — |
automations.runs.read | Consultar execuções de réguas | Organizar a operação · Só olha | outros contatos só com data_access.other_contacts |
radar.read | Consultar Radar (itens em risco) | Não perder o cliente · Só olha | data_access.other_contacts obrigatório para publicar |
radar.propose_reactivation | Propor retomada de contato (pessoa aprova) | Não perder o cliente · Faz mudanças | aprovação humana |
catalog.products.search | Buscar produtos do catálogo importado | Vender e mover o funil · Só olha | — |
privacy.consent.read | Consultar consentimento do contato | Atender e responder · Só olha | — |
knowledge.sources.read | Consultar fontes e prontidão | Aprender e evoluir · Só olha | — |
proposals.read | Consultar propostas de melhoria | Aprender e evoluir · Só olha | — |
cases.read | Consultar casos | Passar para uma pessoa · Só olha | cases_enabled; outros contatos só com data_access.other_contacts |
crm.search | Buscar oportunidades/demandas do Cliente | Vender e mover o funil · Só olha | data_access.other_contacts obrigatório para publicar |
agenda.schedule.read | Consultar agenda por dia/profissional | Não perder o cliente · Só olha | — |
agenda.appointments.confirm | Registrar presença confirmada pelo contato | Não perder o cliente · Faz mudanças | — |
cases.note | Anotar no caso aberto da conversa | Passar para uma pessoa · Faz mudanças | cases_enabled |
cases.close | Encerrar o caso aberto da conversa | Passar para uma pessoa · Faz mudanças | cases_enabled |
conversations.reply_options | Enviar opções para o contato tocar | Atender e responder · Faz mudanças | só o agente (o operador é recusado); janela de 24h aberta; list só no WhatsApp |
conversations.attach_files | Enviar fotos, vídeos e PDFs da empresa | Atender e responder · Faz mudanças | — |
agenda.propose só conclui quando o contato responde com CONFIRMAR XXXXXXXX, usando o código devolvido pela Agenda; o agente não confirma por conta própria. handoff tira a IA da conversa até uma pessoa devolver pelo painel ou por POST /conversations/{id}/agent-control. Enquanto ninguém assume, a conversa aparece na caixa Atendimento humano da Inbox.
conversations.reply_options não envia nada sozinha: anexa opções à resposta final do turno. No WhatsApp, o último trecho da resposta sai como mensagem interativa (kind: "buttons", até 3 botões de até 20 caracteres, ou kind: "list" com list_button e até 10 opções), com os mesmos limites de mensagens interativas. No Instagram, só buttons, enviados como respostas rápidas. Só com a janela de 24h aberta. O texto das opções passa pela mesma avaliação antes do envio que a resposta, e o toque do contato volta como a próxima mensagem dele.
Visão geral do Agente de IA · Próxima: Acesso e elegibilidade
