Quando o agente diz que fez, ele fez

Quando o agente de IA executa uma ação que altera dados no seu sistema, duas perguntas importam: quando ele pode dizer que fez, e o que conta como feito. As duas mudaram, e a resposta agora é a mesma nos dois casos — quem decide não é o agente.

Nada muda sem o cliente confirmar

Ação de escrita nunca roda sozinha. Ao chamá-la, o agente mostra um cartão de confirmação logo abaixo da mensagem dele, com os botões Confirmar e Agora não. Enquanto ninguém confirma, nada acontece no seu sistema.

Por isso o agente foi ensinado a falar no futuro enquanto o cartão está pendente — o que vai acontecer quando o cliente confirmar — e nunca no passado. Ele também não descreve o cartão nem manda clicar em botão nenhum: antes, chegava a dizer coisas como “enviei a solicitação, clique em Executar acima”, com três erros numa frase só.

Depois do aceite, e só depois, vem a frase de desfecho: ✅ Pronto! Concluí… com o nome da ação. Se o cliente recusar, o agente responde que cancelou e segue a conversa.

Responder 200 não é a mesma coisa que dar certo

Muito sistema de gestão confirma o recebimento com sucesso e informa a falha dentro do corpo da resposta. Antes, a plataforma olhava só o código da resposta: o cartão virava Feito, o agente dizia que estava resolvido, e nada tinha acontecido.

Agora, quando o código e o corpo se contradizem, o corpo ganha. A chamada é reprovada quando a resposta traz, no primeiro nível:

  • um campo de situação dizendo error, erro, fail, failed ou failure;
  • um campo de sucesso valendo false;
  • um campo de erro preenchido.

Nesse caso o cartão mostra Não deu certo e o cliente lê ❌ Não consegui executar com a mensagem que o seu sistema escreveu — não um texto genérico.

A régua é conservadora de propósito: campo de erro vazio não derruba nada, e a palavra “erro” no meio dos dados também não — só o topo da resposta é lido.

O ponto de atenção ao montar a sua API

Isso vale também para as consultas. Se a sua API devolve um campo de erro preenchido numa resposta normal — por exemplo “nenhum registro encontrado” —, aquilo passa a ser tratado como falha. Nesses casos, deixe o campo de erro ausente ou vazio quando a chamada tiver dado certo.

Onde conferir a verdade

Em Inteligência › Agentes, aba APIs, abra a gaveta Chamadas e use o filtro Com erro. Ali está o que saiu, o que voltou e a mensagem exata do seu sistema.

Para saber de antemão quais ações passam pelo cartão de confirmação, clique no nome da ação na lista: abre uma tela só de leitura, sem risco de mexer em nada, com a faixa dizendo se aquela ação altera dados ou só consulta, os parâmetros, as instruções e quantas chamadas ela teve nos últimos 7 dias.