Instruções: o que a IA lê, e por que às vezes não chega
Você escreve instrução em cinco lugares diferentes, e cada um faz um trabalho que os outros não fazem. Quando o agente responde errado, quase sempre o texto está certo — só está no lugar errado, ou nem chegou até ele. Este tutorial mostra onde cada instrução age, o limite que existe e como descobrir, em cada resposta, o que a IA leu antes de decidir.
Os cinco lugares, e o que cada um decide
| Onde você escreve | O que ele decide |
|---|---|
| Instruções do agente | quem ele é, o tom, o que ele nunca faz |
| Instruções da ação | se a IA vai ENCONTRAR aquela consulta |
| Instruções da API | como interpretar o que voltou e como falar do resultado |
| Instruções para a IA de um conteúdo (Conhecimento e Central) | como usar AQUELE documento — viaja colada ao trecho quando ele é recuperado, e o cliente nunca a vê |
| Instruções de IA da organização (Configurações) | as regras de conduta que valem para todos os seus agentes |
A instrução do conteúdo tem um detalhe próprio: ela não entra na busca do conhecimento (não ajuda o documento a ser achado, nem atrapalha) — ela chega junto quando o documento já foi escolhido, orientando o uso ("não cite o nome deste material", "isto só vale para quem já é cliente").
A linha do meio é a que mais surpreende. Vale insistir nela.
Achar a consulta e usar a consulta são coisas diferentes
Quando o seu catálogo cresce, a IA não recebe todas as consultas de uma vez — ela busca a que precisa. E essa busca olha só três campos da ação:
- o nome da ação, que pesa mais;
- a chave;
- as instruções.
As instruções da API não entram nessa busca. Por mais bem escritas que estejam, elas não ajudam a IA a encontrar a consulta certa: elas ensinam a usar o que já foi encontrado.
O erro mais comum, com um exemplo real
Uma empresa com muitas integrações perguntou ao agente: "resumo do faturamento deste mês". A busca voltou oito consultas — e nenhuma delas era a de faturamento. Vieram relatórios de orçamentos, de comissão de vendedores, de notas ao consumidor.
O motivo: dezenas de ações daquele catálogo começavam com a palavra "relatório". Buscar por "relatório" ali é como procurar "arquivo" numa pasta onde tudo se chama arquivo — não distingue nada. A palavra que distinguiria era faturamento, e ela só existia nas instruções, que é o campo de menor peso.
O conserto não foi escrever mais instrução. Foi pôr a palavra certa no campo que pesa: quem responde faturamento precisa ter "faturamento" no nome da ação.
Regra de bolso: pense na palavra que o seu cliente usaria na pergunta. Se ela não estiver no nome da ação, a IA pode não achar a consulta — mesmo que a instrução da API explique tudo.
O limite das instruções da API
Cada API tem um teto de 5.000 caracteres de instrução — o mesmo teto vale para as instruções de cada ação. O limite existe por uma razão: essas instruções vão para a IA em toda mensagem, e uma conta com dez integrações somaria um texto enorme em cada resposta, deixando o atendimento mais lento e mais caro.
O teto é do texto inteiro: nenhuma linha é cortada sozinha, então você pode escrever uma regra longa numa linha só sem medo de perder o fim dela. E o campo Instrução para a IA de cada parâmetro cresce conforme você escreve — a instrução inteira fica à vista, sem rolagem lateral.
Ao escrever, o contador aparece quando você se aproxima do limite e fica vermelho se passar. Passou, o sistema não deixa salvar e diz quanto falta cortar. Ao colar um texto grande no Organizar com IA de uma ação, cabe mais do que o teto final: a IA enxuga e devolve o texto já dentro do limite.
Se você já tem texto acima do limite
Isso é importante: o excedente nunca chegou à IA. Ele ficava guardado, aparecia na tela, e era descartado na hora de montar a resposta — sem erro e sem aviso. E o corte é por caractere, então a última regra costumava chegar pela metade.
Vale abrir cada API e conferir. Duas saídas:
- Suba o que é mais importante. O corte é do fim para o começo, então o que está nas primeiras linhas sempre chega.
- Enxugue. Boa parte do texto costuma ser explicação repetida em várias APIs (formato de valor, formato de data). Uma frase curta ensina igual.
Como ver o que a IA leu antes de responder
Em Inteligência → Agentes → Testar, cada resposta traz o link "Como respondi". Ele abre o caminho daquela resposta em duas partes.
O que ele levou para a conversa — as instruções do agente, as regras gerais, a data de hoje, o perfil do negócio, as instruções de cada API, quantas consultas entraram na mesa e quais ficaram de fora. Cada item tem "Ver o texto que ele leu", com o texto exato que foi para a IA.
O que ele fez — cada consulta chamada, com os parâmetros, o tempo e um trecho do que o sistema respondeu. É aqui que aparece o caso clássico: a consulta que devolveu sucesso com uma mensagem de erro dentro. Para o sistema foi sucesso; para o cliente foi uma resposta sem número nenhum.
No topo, pontos de atenção reúnem o que mais provavelmente explica uma resposta ruim: instrução cortada no limite, consulta que ficou de fora por falta da credencial de quem está falando, busca no conteúdo que não achou nada.
Nada disso fica gravado: é uma conversa de teste, não cria atendimento e some quando você fecha.
Um roteiro para quando a resposta sai errada
- Abra "Como respondi" naquela resposta.
- Veja o que ele fez. Chamou a consulta certa?
Chamou e o dado veio errado → o conserto é na instrução da API (vocabulário, o que não pode ser somado, como apresentar).
Chamou a consulta errada → o conserto é no nome e nas instruções daquela ação e da que deveria ter sido chamada.
Não chamou nada → abra o que ele levou: a consulta estava na mesa? Se ficou de fora por credencial, o caminho é a identificação do visitante. - Veja os pontos de atenção: eles costumam apontar direto para o campo que resolve.
- Ajuste, volte ao Testar e pergunte de novo. Cada linha do painel tem um link para o lugar exato da edição.
O que evitar
- Escrever na API o que deveria estar no nome da ação. A instrução não ajuda a encontrar.
- Repetir a mesma regra em várias APIs. O que vale para o negócio inteiro cabe nas instruções do agente, e é lido em toda conversa.
- Explicar demais. Frase curta e direta funciona melhor do que parágrafo, e ocupa menos do seu limite.
- Concluir pela resposta. O texto que o cliente recebeu não diz o que a IA leu. O "Como respondi" diz.
Veja também
Os tutoriais APIs: conecte a IA aos seus sistemas, Agentes de IA e Fontes de conhecimento completam o assunto: o primeiro cobre o cadastro e as credenciais, o segundo as instruções e as filas de transferência, e o terceiro o conteúdo que responde as dúvidas gerais.