Mensagens do Sistema e Ferramentas
- Como adicionar mensagens do sistema que instruem seu agente LLM
- Como configurar ferramentas de chamada de função que o agente pode usar
- Como configurar pré-ações que executam antes de o agente processar uma mensagem
Quando você cria um agente baseado em LLM, três das cinco abas de configuração controlam o que o agente sabe, o que ele pode fazer e o que acontece antes de ele responder. Esta página cobre as abas Messages, Actions e Tools.
Aba Messages -- Mensagens do Sistema
A aba Messages contém a seção de Mensagens do Sistema. Mensagens do sistema são as instruções que você dá ao modelo de linguagem antes que qualquer conversa com o contato comece. Elas definem a personalidade, o conhecimento, os limites e o comportamento do agente.
Como as mensagens do sistema funcionam
As mensagens do sistema são avaliadas e enviadas ao LLM a cada requisição, antes do histórico da conversa. O modelo lê essas instruções e as segue ao gerar respostas. Você pode adicionar várias mensagens do sistema, e elas são processadas em ordem. Como são reavaliadas a cada mensagem, os valores dinâmicos nelas (veja abaixo) sempre refletem o turno atual da conversa.
Adicionando mensagens do sistema
- Abra seu agente LLM e vá para a aba Messages.
- Você verá uma área de lista para mensagens do sistema.
- Clique no botão "Adicionar Item" para adicionar uma nova mensagem do sistema.
- Digite sua instrução no campo de texto que aparece.
- Repita para adicionar quantas mensagens do sistema forem necessárias.
Dicas para escrever mensagens do sistema eficazes
- Identidade: Diga ao agente quem ele é. Exemplo: "Você é o agente virtual do Bella Salon, um estúdio de cabelo e beleza no centro de Lisboa."
- Conhecimento: Forneça fatos importantes. Exemplo: "Nossos serviços incluem cortes de cabelo (a partir de 25 euros), coloração e penteados. Funcionamos de terça a sábado, das 9h às 19h."
- Tom: Defina o estilo de comunicação. Exemplo: "Seja amigável, profissional e conciso. Use o primeiro nome do contato quando possível."
- Limites: Defina o que o agente não deve fazer. Exemplo: "Nunca discuta preços de concorrentes. Não faça afirmações médicas ou jurídicas. Se não tiver certeza, ofereça conectar o contato com um atendente humano."
- Encaminhamento: Explique quando transferir. Exemplo: "Se o contato pedir para falar com uma pessoa, ou se você não conseguir resolver a questão em 3 trocas, transfira a conversa para um agente humano."
Usando variáveis dinâmicas em mensagens do sistema
As mensagens do sistema são expressões CEL, então você pode inserir informações dinâmicas em tempo de execução. Isso permite personalizar o comportamento do agente com base no contato, na mensagem recebida ou na conversa.
Escreva uma expressão CEL nativa usando as variáveis disponíveis. Para um prompt fixo, use o controle de texto literal para criar uma string CEL entre aspas e com os caracteres escapados. Veja as duas opções de escrita no editor de expressões CEL.
Variáveis disponíveis:
| Variável | Descrição |
|---|---|
contact | Informações do contato (nome, tags, atributos personalizados) |
contactMessage | A mensagem recebida (tipo, conteúdo de texto, mídia, timestamp) |
conversation | A sessão de chat (canal, status, última mensagem) |
company | O registro da sua empresa |
Exemplos:
- Personalizando saudações:
'The contact name is ' + contact.name - Incluindo tags do contato:
'Contact tags: ' + contact.tags.join(', ') - Comportamento condicional baseado no tipo de mensagem:
contactMessage.type == 'text' ? contactMessage.body.text : '(media message)'
Use o painel Explorer para navegar por todas as variáveis disponíveis e suas propriedades. Clique em uma variável para ver seus subcampos e inseri-los na sua expressão.
Aba Tools -- Chamada de função
A aba Tools permite dar ao seu agente a capacidade de chamar funções externas durante uma conversa. Isso é conhecido como "chamada de função" ou "uso de ferramentas": o agente pode buscar dados, fazer cálculos, verificar disponibilidade ou criar agendamentos.
As configurações da aba Tools só aparecem quando o agente realmente pode usar ferramentas. Se você ativar Ativar saídas estruturadas (na aba Avançado), ou se o modelo selecionado não suportar chamada de função, os campos Tool choice, Tools e MCP Servers ficam ocultos e a aba aparece vazia.
Escolha de ferramenta
No topo da aba Tools, você encontrará o dropdown Tool choice com quatro opções:
- auto (padrão): O modelo decide por conta própria quando chamar uma ferramenta com base no contexto da conversa.
- required: O modelo deve chamar uma ferramenta antes de responder.
- none: O modelo nunca chama ferramentas.
- function: O modelo é forçado a chamar uma ferramenta específica. Selecionar isso revela um campo Function, onde você escolhe a ferramenta pelo nome.
Adicionando ferramentas
- Vá para a aba Tools no seu agente LLM.
- Na lista de Tools, clique no botão "Adicionar Item".
- Configure a ferramenta fornecendo seu nome, descrição e esquema de parâmetros. A descrição é crítica porque o LLM a lê para decidir quando e como usar a ferramenta. Ao lado deles há três opções, todas desativadas por padrão:
- Oculto: a ferramenta fica de fora da lista de ferramentas enviada ao modelo, então o agente nunca a chama diretamente. Ela continua podendo ser chamada pelo nome a partir das ações de outra ferramenta.
- Seguro em paralelo: a ferramenta pode ser executada ao mesmo tempo que outras chamadas somente-leitura no mesmo turno. Deixe desativado para ferramentas que alteram dados ou dependem da ordem das chamadas — e note que uma ferramenta com ações sempre é executada de forma sequencial, independentemente dessa opção.
- Encerra o turno (
endsTurn): depois que esta ferramenta roda, se o contato já recebeu uma resposta durante a execução, a execução para ali e o modelo não ganha outro turno. Uma ação que falhou não impede isso — o que decide é se uma resposta chegou ao contato. Veja Encerrando o turno depois de uma ferramenta.
- Na seção Ações da ferramenta, adicione etapas quando precisar consultar dados, chamar uma API ou alterar um registro. A ferramenta também pode ter zero ações e retornar um resultado CEL puro por
function.output.main, incluindo uma função de biblioteca do tenant com versão fixada. Os parâmetros estão disponíveis diretamente pelo nome nessa expressão. - Na seção Output, configure o que a ferramenta retorna ao modelo. Principal é o único campo aqui: uma expressão CEL cujo valor é devolvido ao modelo depois que as ações são executadas. Se deixar vazio, a ferramenta não devolve nada de útil ao agente, então preencha com aquilo que o modelo precisa ver.
- Repita para cada ferramenta que deseja que o agente acesse.
{
"type": "function",
"function": {
"name": "normalize_name",
"description": "Return a normalized name without calling an action",
"parameters": [{"name": "value", "type": "string", "isRequired": true}],
"actions": [],
"output": {"main": {"expr": "text.nameKey(value)", "onFailure": "throw"}}
}
}
Por padrão, o runner devolve cada resultado de ferramenta ao modelo como parte do laço normal do agente, então um novo turno do modelo acontece sozinho — você decide, por meio de Principal, o que o modelo vai ver. A única forma de pular esse turno é Encerra o turno, abaixo.
Encerrando o turno depois de uma ferramenta
Algumas ferramentas são a resposta: um menu de opções enviado com Compor Resposta da Conversa (type: "options"), um documento gerado, uma confirmação de agendamento. Se o modelo ganha outro turno depois de uma ferramenta assim, o que ele escrever chega depois do menu — no WhatsApp, como texto abaixo dos botões. Ative Encerra o turno (endsTurn) na ferramenta para evitar isso.
Quando o modelo chama uma ferramenta com Encerra o turno ativado, três coisas impedem que essa chamada encerre o turno, e o modelo então ganha o próximo turno normalmente:
- os argumentos não eram JSON válido, então a ferramenta não rodou;
- Principal falhou ao ser avaliado — o modelo recebe o erro como resultado da ferramenta;
- a chamada repetiu uma com os mesmos argumentos que já tinha devolvido o mesmo resultado duas vezes nesta execução, então o runner respondeu com esse resultado em vez de rodar a ferramenta de novo.
Uma ação que falha não está nessa lista. O runtime registra a falha naquela etapa — status failed, com o erro no log do agente — e segue para a próxima ação e para Principal, então a chamada ainda conta como executada; uma ação cuja condição não pode ser avaliada é pulada e também não impede. O que decide é se uma resposta de fato chegou ao contato — um menu cujo envio falhou ainda encerra a execução se uma mensagem anterior desta execução chegou ao contato — então o runner verifica se o contato recebeu alguma coisa durante esta execução, pelas ações desta ferramenta ou antes:
- Sim: a execução termina logo depois desse lote de chamadas de ferramenta, do mesmo jeito que quando uma ferramenta enviou a resposta e o último turno do modelo veio vazio (
tool_reply). O modelo não ganha outro turno, e o log do agente registra "Run ended by an endsTurn tool after its actions". - Não — o envio falhou, por exemplo, ou a única mensagem foi para outra pessoa: a opção é ignorada nesta chamada, um aviso é registrado ("endsTurn tool finished without a user-visible reply; the run continues") e a execução segue normalmente, então o modelo ainda pode responder.
Mais alguns detalhes:
- Funciona nas ferramentas definidas nesta aba. Ferramentas de servidores MCP e as ferramentas embutidas não conseguem encerrar o turno.
- Se o modelo chamou outras ferramentas no mesmo turno, elas ainda rodam e são salvas no histórico, mas o modelo não chega a ler os resultados delas antes de a execução terminar.
- Uma pausa
wait_for_userpedida no mesmo turno tem precedência: a execução termina aguardando o contato. - O modelo vê o menu na próxima execução: os menus de opções que o agente enviou são reproduzidos no histórico dele como o contato os viu (título, descrição e rótulos numerados), então um toque que chega como o valor de uma opção pode ser lido contra o menu que a ofereceu.
Quais envios contam como resposta do agente
Encerra o turno, e a regra de que uma execução cujo último turno do modelo veio vazio ainda conta como respondida quando uma ferramenta já enviou a resposta (tool_reply), dependem de o contato já ter sido respondido. Só contam mensagens entregues a esta conversa:
- As mensagens que Compor Resposta da Conversa entrega aqui contam, uma por mensagem, e também as que Enviar Mensagem ao Contato entrega ao próprio contato da execução.
- Uma mensagem enviada a outro contato — uma ferramenta que avisa alguém da equipe, por exemplo — não conta. Se foi só isso que a execução enviou e o último turno do modelo veio vazio, a execução termina como erro (
no_output) em vez de ser registrada como resposta, porque o contato não recebeu nada. Deixe o modelo escrever a resposta, ou envie-a para esta conversa pela ferramenta. - Uma ação que não informa quais mensagens enviou — executar um workflow manual, ou chamar uma função de recurso — conta como uma resposta, porque o runtime não consegue saber para onde a mensagem foi.
- Mensagens internas de status nunca contam.
Exemplos de ferramentas
| Ferramenta | Propósito |
|---|---|
| Verificar disponibilidade do calendário | Permite que o agente consulte horários de consulta disponíveis |
| Criar agendamento | Permite que o agente agende uma consulta para o contato |
| Buscar registro do contato | Recupera detalhes do contato do seu banco de dados |
| Enviar notificação | Envia um alerta para um membro da equipe |
Servidores MCP
Abaixo da lista de Tools, a lista MCP Servers permite conectar servidores MCP (Model Context Protocol) externos cujas ferramentas ficam disponíveis para o agente em tempo de execução, ao lado das ferramentas que você define localmente. Para cada servidor você fornece:
- Server URL: O endereço HTTP(S) público do servidor.
- Server label e Description (opcionais): Ajudam você e o modelo a identificar o servidor.
- Exigir aprovação: Controla a aprovação na execução MCP nativa suportada do OpenAI Responses. O caminho pela ponte MCP local não aplica esse controle; ele não é uma barreira universal de aprovação para todos os caminhos de execução de modelos/servidores.
- Allowed tools (opcional): Restringe quais ferramentas do servidor o agente pode usar.
- Headers (opcional): Cabeçalhos HTTP enviados ao servidor, normalmente para autenticação.
As ferramentas do servidor são descobertas automaticamente e oferecidas ao modelo junto com suas ferramentas locais.
Comece com uma ou duas ferramentas essenciais e teste completamente antes de adicionar mais. Cada ferramenta aumenta a capacidade do agente, mas também adiciona complexidade. O modelo precisa de descrições claras das ferramentas para usá-las corretamente.
Para ferramentas que podem ser encadeadas em uma única solicitação do usuário, evite adicionar uma Compose conversation response apenas de status como primeira ação da ferramenta. Essa ação roda toda vez que a ferramenta é chamada, então um fluxo buscar -> abrir -> resumir pode enviar várias mensagens de "estou trabalhando" antes da resposta útil. Prefira retornar os dados da ferramenta e deixar a resposta final do agente resumir uma única vez. Se uma ferramenta demorada precisar de aviso de progresso, envie no máximo um aviso curto para toda a solicitação.
Aba Actions -- Pré-ações
A aba Actions permite configurar Pré-ações -- etapas que executam automaticamente antes de o LLM processar cada mensagem recebida. Pré-ações podem transformar dados, chamar APIs, definir variáveis ou executar outra lógica para preparar o contexto para a IA.
Se você precisar de um guia campo a campo dos tipos de ação disponíveis, veja a Referência de Ações.
Configurando pré-ações
- Vá para a aba Actions no seu agente LLM.
- Você verá a seção de Pré-ações.
- Clique em "Add step" para adicionar uma nova etapa de pré-ação.
- Configure a etapa com a lógica desejada.
- Adicione etapas adicionais conforme necessário. As etapas executam em sequência.
Depurando pré-ações
A aba Actions inclui um botão Iniciar Debug (cuja dica de ferramenta diz "Depurar tudo"). Clicar nele executa todas as etapas de pré-ação em modo de depuração para que você possa ver o que cada etapa faz, quais dados produz e se algum erro ocorre.
Use pré-ações para enriquecer o contexto da conversa antes de a IA responder. Por exemplo, uma pré-ação pode buscar o histórico de pedidos recentes do contato para que o agente possa referenciá-lo em sua resposta sem precisar de uma chamada de ferramenta durante a conversa.