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 assistente 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.
Para usar uma variável dinâmica em uma mensagem do sistema:
- Escreva uma expressão CEL usando as variáveis disponíveis. O interruptor Usar expressões simples (sCEL) alterna uma mensagem entre CEL simples e CEL bruto.
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.
- Na seção Actions da ferramenta, adicione as etapas que são executadas quando o assistente chama a ferramenta. Uma ferramenta sem ações não faz nada — essas ações de Workflow/etapa realizam o trabalho de fato (consultar dados, chamar uma API, criar um registro e assim por diante). Novas ferramentas começam com uma lista de ações vazia, então adicione ao menos uma ação para que a ferramenta tenha algum efeito.
- Na seção Output, configure o que a ferramenta retorna ao modelo. A saída main é o valor devolvido ao assistente depois que as ações são executadas. Você também pode ativar Execute extra completion para executar uma completion adicional do modelo sobre o resultado e Enable tools in extra completion para permitir novas chamadas de ferramenta durante ela. Ambas ficam desativadas por padrão.
- Repita para cada ferramenta que deseja que o agente acesse.
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.
- Require approval: Se as chamadas de ferramenta a esse servidor precisam de aprovação.
- 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 assistente 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.