Agentes e versões

Crie o rascunho, teste com o provedor real, publique uma versão imutável e controle quando e como o agente atende.

Ciclo de vida

  1. POST /ai/agents cria o agente e o primeiro rascunho. Ele não atende até ser ativado.
  2. PUT /ai/agents/{id} altera o rascunho, sempre com a revisão lida. Sem rascunho, o PUT cria um a partir do corpo enviado.
  3. POST /ai/agents/{id}/preview testa uma versão sem efeitos.
  4. POST /ai/agents/{id}/publish diagnostica e publica o rascunho. A versão fica imutável e o agente passa a apontar para ela. Publicar incrementa operation_revision mas não ativa o agente. Num agente em operação, publicar refaz o vínculo quando os canais mudam e incrementa operation_revision de novo (veja channel_sync).
  5. POST /ai/agents/{id}/operation ativa 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 em expected_revision no PUT e no publish, e em expected_draft_revision no restore.
  • agent.operation_revision: da operação. Vai em expected_revision em operation e archive, e em expected_agent_revision ao 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:

CampoTipo e limitesUso
lifecycledraft | published | active | paused | archivedEtapa do ciclo de vida, abaixo.
servingbooleantrue quando o agente é, agora, quem responde em pelo menos um canal da versão publicada.
serving_viadirect | router | nulldirect: 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_idUUID | nullPrimeiro canal da versão publicada; null sem versão publicada.
channelslista 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

CampoTipo e limitesUso
customer_idUUIDCliente dono do agente.
namestring 1–80Nome do agente.
descriptionstring até 2.000Opcional.
configobjetoConfiguraçã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

CampoTipo e limitesUso
version_idUUIDRascunho ou versão publicada do agente.
operation_keyUUIDRepetir a chave com os mesmos dados devolve a mesma execução; com outros dados, 409 idempotency_conflict.
messages1–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.

  1. Execute o preview e guarde o ID, a resposta e o contexto até a última pergunta. Leia as citações por execution_id.
  2. 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.
  3. Guarde pending_version_id ?? active_version_id devolvido na escrita. Aguarde a fonte ativa, sem erro, com status:ready, sem versão pendente e com active_version_id igual ao ID esperado. Um ready da versão anterior não basta.
  4. Para fonte nova, vincule explicitamente em config.knowledge_source_ids, habilite knowledge.search e salve o rascunho via PUT. O servidor valida ownership. Não precisa publicar para testar.
  5. 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

CampoTipo e limitesUso
expected_revisionstringoperation_revision atual.
modeautomatic | assistedassisted: resposta e ações aguardam aprovação.
pausedbooleanfalse 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).

StatusCódigoQuando
404not_foundAgente ou versão inexistente neste Cliente.
404channel_not_foundCanal 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.
409revision_conflictRevisão do rascunho ou da operação desatualizada.
409duplicate_responderAo ativar, nenhum canal da versão está livre: todos com outro agente ou roteador.
409credential_unavailableCredencial inativa (inclusive as de provedores descontinuados), não validada ou de outro provedor.
409agent_archivedEditar, publicar ou ativar um agente arquivado.
409agent_unavailableAtivar sem versão publicada.
409published_version_immutablePublicar uma versão já publicada.
409idempotency_conflictoperation_key repetida com dados diferentes.
409stage_scope_invalid · knowledge_scope_invalid · skill_scope_invalid · file_scope_invalid · followup_scope_invalidID de etapa, fonte ativa, skill ativa, arquivo ativo (pronto ou convertendo) ou fluxo publicado inválido na publicação.
422incomplete_configurationPublicar ou testar sem instruções, modelo, credencial ou canal.
422diagnostic_blockedPublicar com uma verificação do diagnóstico bloqueando. error.blockers lista cada pendência (id, title, status, detail).
422invalidCorpo fora do schema ou ID malformado.
422provider_not_enabledRascunho com provedor que não seja OpenAI ou Anthropic, no agente ou no operador.
422publish_required · incompatible_send_windowsFollow-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_prompt com ao menos 10 caracteres e model preenchido.
  • credential_id ativa, validada e do mesmo provider. Com operador próprio, a credencial dele também.
  • Ao menos um canal em channel_account_ids (ou channel_account_id), e todos os da lista do Cliente: Número do WhatsApp ou conta do Instagram.
  • allowed_stage_ids, knowledge_source_ids, skill_ids e file_ids existentes e ativos no Cliente (arquivo pronto ou ainda convertendo); fluxos de followup.flow_ids publicados, com janela de envio compatível.
  • Ferramentas que só consultam outros contatos (contacts.search, radar.read, crm.search) exigem data_access.other_contacts: true.
  • Chave validada pelo provedor, com o model no 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_live e nenhum número em test_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 warning e 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": ""
  }
}
CampoTipo e limitesUso
system_promptstring até 20.000Instruções. Mínimo de 10 caracteres para publicar.
provideranthropic, openaiProvedor 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.
modelstring até 200ID do modelo, como listado na credencial.
credential_id · channel_account_idUUID ou nullnull só no rascunho. channel_account_id é o primeiro canal.
channel_account_idslista de UUID, até 10, sem repetirCanais 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_idslista sem repetiçãoFerramentas 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_zonefuso IANAPadrão America/Sao_Paulo.
business_hours{start HH:MM, end HH:MM, weekdays 0–6} ou nullstart antes de end; dias sem repetição (0 = domingo).
outside_hoursrespond | wait | handoffFora de business_hours: responde, adia até a próxima abertura ou passa para a equipe.
max_steps1–25Passos de ferramenta por turno. Padrão 10.
token_budget1.000–500.000Tokens 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_usdmaior que 0 e até 100, ou nullTeto estimado por execução, em dólares.
history_message_window · history_token_window0–200 · 0–50.000Histó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_keywordsaté 30 de até 80Frases que transferem para a equipe.
handoff_enabled · cases_enabledbooleanLiberam a ferramenta handoff e as de casos.
split_messages · split_max_charsboolean · 80–4.000Divide respostas longas.
crm_scopescontacts, opportunities, demandsVazio = nenhum acesso ao CRM.
allowed_stage_idsaté 100 UUIDsÚnicas etapas para onde o agente pode mover.
knowledge_source_ids · skill_idsaté 100 UUIDs cadaFontes e skills autorizadas.
file_idsaté 40 UUIDs, opcionalArquivos que o agente pode mandar; com conversations.attach_files em tool_ids. Veja Arquivos do agente.
platform_skillsnone | allCompõe as skills da plataforma. Veja Skills.
memory_enabledbooleanLê e propõe memória.
data_access.other_contactsbooleanAutoriza 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.
safetyver abaixoCamada 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

CampoTipo e limitesUso
disclose_aibooleanInforma que é uma IA.
disclosure_textstring até 300Texto do aviso.
prohibited_claimsaté 50 de até 300Afirmações que o agente não pode fazer.
additional_rulesaté 30 de até 500Regras extras.
escalation_instructionsstring até 4.000Quando 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_sensitivitystandard | strictNo 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_evaluatorbooleanAvaliaçã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_idO que fazGrupo e riscoExige
contacts.readConsultar o contato atualAtender e responder · Só olhacrm_scopes com contacts
contacts.updateAtualizar o contato atualAtender e responder · Faz mudançascrm_scopes com contacts
conversations.readConsultar a conversa atualAtender e responder · Só olha—
conversations.noteAdicionar nota internaAtender e responder · Faz mudanças—
crm.opportunities.readConsultar oportunidades do contatoVender e mover o funil · Só olhacrm_scopes com opportunities
crm.opportunities.writeAtualizar oportunidades do contatoVender e mover o funil · Faz mudançascrm_scopes com opportunities; mudança de etapa limitada a allowed_stage_ids
crm.demands.readConsultar demandas do contatoVender e mover o funil · Só olhacrm_scopes com demands
crm.demands.writeAtualizar demandas do contatoVender e mover o funil · Faz mudançascrm_scopes com demands; mudança de etapa limitada a allowed_stage_ids
crm.stages.readConsultar etapas permitidasVender e mover o funil · Só olhalista só as etapas de allowed_stage_ids
crm.stages.writeMover etapa do contatoVender e mover o funil · Faz mudançasetapa de destino em allowed_stage_ids
agenda.availabilityConsultar disponibilidadeNão perder o cliente · Só olha—
agenda.proposePropor agendamento (o contato confirma)Não perder o cliente · Faz mudançasconfirmação do contato
agenda.appointments.readConsultar compromissos do contatoNão perder o cliente · Só olha—
agenda.appointments.rescheduleReagendar compromisso do contatoNão perder o cliente · Faz mudanças—
agenda.appointments.cancelCancelar compromisso do contatoNão perder o cliente · Faz mudanças—
knowledge.searchConsultar base de conhecimentoAprender e evoluir · Só olhabusca só em knowledge_source_ids
memory.readConsultar memóriaAprender e evoluir · Só olhamemory_enabled
memory.proposePropor memória para revisãoAprender e evoluir · Faz mudançasmemory_enabled; aprovação humana
skills.readLer habilidadesAprender e evoluir · Só olhalê só skill_ids
followups.enrollInscrever em acompanhamentoNão perder o cliente · Faz mudançasfollowup.enabled e fluxo em followup.flow_ids
followups.pausePausar acompanhamentoNão perder o cliente · Faz mudançasfollowup.enabled
followups.cancelCancelar acompanhamento ou retorno agendadoNão perder o cliente · Faz mudançasfollowup.enabled para inscrições; retornos avulsos não exigem
cases.openAbrir casoPassar para uma pessoa · Faz mudançascases_enabled; abrir com transferência exige handoff_enabled
cases.updateDevolver informação a um casoPassar para uma pessoa · Faz mudançascases_enabled
handoffTransferir para atendentePassar para uma pessoa · Só uma pessoa desfazhandoff_enabled
alerts.createCriar alertaPassar para uma pessoa · Faz mudanças—
followups.scheduleAgendar retorno prometido ao contatoNão perder o cliente · Faz mudanças—
followups.listConsultar retornos e acompanhamentos do contatoNão perder o cliente · Só olha—
contacts.searchBuscar outros contatosAtender e responder · Só olhacrm_scopes com contacts; data_access.other_contacts obrigatório para publicar
contacts.getConsultar um contato pelo IDAtender e responder · Só olhacrm_scopes com contacts; outros contatos só com data_access.other_contacts
contacts.propose_updateSugerir mudança no cadastro (pessoa confirma)Atender e responder · Faz mudançascrm_scopes com contacts; aprovação humana
conversations.listListar conversasAtender e responder · Só olhaoutros contatos só com data_access.other_contacts
conversations.getConsultar uma conversa (a atual ou outra pelo ID)Atender e responder · Só olhaoutros contatos só com data_access.other_contacts
conversations.historyLer histórico de uma conversaAtender e responder · Só olhaoutros contatos só com data_access.other_contacts
conversations.assignAtribuir a conversa atual a uma pessoaPassar para uma pessoa · Faz mudanças—
team.members.readConsultar equipeOrganizar a operação · Só olha—
inbox.queue.readConsultar fila de atendimentoOrganizar a operação · Só olha—
tags.readConsultar marcadores em usoOrganizar a operação · Só olha—
tags.manageAdicionar/remover marcadores do contatoOrganizar a operação · Faz mudanças—
saved_replies.readConsultar respostas rápidasAtender e responder · Só olha—
saved_replies.renderPreencher resposta rápidaAtender e responder · Só olha—
automations.readConsultar réguas de automaçãoOrganizar a operação · Só olha—
automations.runs.readConsultar execuções de réguasOrganizar a operação · Só olhaoutros contatos só com data_access.other_contacts
radar.readConsultar Radar (itens em risco)Não perder o cliente · Só olhadata_access.other_contacts obrigatório para publicar
radar.propose_reactivationPropor retomada de contato (pessoa aprova)Não perder o cliente · Faz mudançasaprovação humana
catalog.products.searchBuscar produtos do catálogo importadoVender e mover o funil · Só olha—
privacy.consent.readConsultar consentimento do contatoAtender e responder · Só olha—
knowledge.sources.readConsultar fontes e prontidãoAprender e evoluir · Só olha—
proposals.readConsultar propostas de melhoriaAprender e evoluir · Só olha—
cases.readConsultar casosPassar para uma pessoa · Só olhacases_enabled; outros contatos só com data_access.other_contacts
crm.searchBuscar oportunidades/demandas do ClienteVender e mover o funil · Só olhadata_access.other_contacts obrigatório para publicar
agenda.schedule.readConsultar agenda por dia/profissionalNão perder o cliente · Só olha—
agenda.appointments.confirmRegistrar presença confirmada pelo contatoNão perder o cliente · Faz mudanças—
cases.noteAnotar no caso aberto da conversaPassar para uma pessoa · Faz mudançascases_enabled
cases.closeEncerrar o caso aberto da conversaPassar para uma pessoa · Faz mudançascases_enabled
conversations.reply_optionsEnviar opções para o contato tocarAtender e responder · Faz mudançassó o agente (o operador é recusado); janela de 24h aberta; list só no WhatsApp
conversations.attach_filesEnviar fotos, vídeos e PDFs da empresaAtender 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