O cadastro de um agente de IA é um formulário único, dividido em três blocos: configurações (nome, modelo, empresas, fuso e agendamento), entrega do resultado (e-mail ou webhook e formato de saída) e a descrição do que o agente deve fazer. Este artigo percorre cada campo, explica o montador de agendamento, mostra as regras de validação do formulário e traz um guia para escrever descrições que a Filipa transforma em instruções confiáveis. Ao final, você terá um agente salvo, pronto para a validação com a Filipa.
Índice
Abrindo o cadastro
Vá em Filipa IA, Agentes, Agentes de IA e toque no botão de adicionar. A lista mostra os agentes existentes com nome, status (Rascunho, Ativo ou Pausado), formato de saída, agendamento, proprietário e última atualização; toque em um deles para editar. O cadastro exige a permissão Agentes de IA com edição.
Bloco Configurações
| Campo | Como preencher |
|---|---|
| Nome | Até 100 caracteres. Use um nome que diga o conteúdo e a frequência, como “Cotações vencendo, semanal”. Nomes repetidos são recusados. |
| Modelo | Um dos modelos do provedor de agentes configurado pelo master. O modelo padrão do provedor vem sugerido. Escolha um modelo homologado: gpt-5.6-luna ou superior, claude-sonnet-5 ou superior. A lista pode trazer modelos inferiores, que não foram validados. |
| Empresas | Opcional. Seleção múltipla entre as empresas às quais você tem acesso. Vazio, o agente trabalha na empresa atual; com uma seleção, a instrução validada cobre essas empresas. |
| Fuso horário | O fuso usado para interpretar o agendamento e os períodos relativos (“ontem”, “última semana”). Vem preenchido com o fuso padrão; pesquise pelo nome para trocar. É obrigatório quando há agendamento. |
| Agendamento | Quando o agente roda. Veja a seção seguinte. |
O idioma do agente segue o idioma do seu Vendelo no momento do cadastro: a instrução final e o conteúdo gerado ficam nesse idioma.
O montador de agendamento
Você não precisa escrever expressões de agendamento. O campo oferece cinco opções e monta a expressão por você, mostrando um resumo legível:
| Opção | Campos | Resumo exibido |
|---|---|---|
| Sem agendamento (execução manual) | – | O agente só roda por “Executar agora”. |
| A cada hora | A cada (horas); Minuto | “A cada 2 hora(s), no minuto 15” |
| Diariamente | Hora; Minuto | “Todos os dias às 08:00” |
| Semanalmente | Dias da semana; Hora; Minuto | “Toda segunda-feira, quarta-feira às 08:00” |
| Mensalmente | Dia do mês; Hora; Minuto | “Todo mês no dia 1 às 07:30” |
Escolha horários fora do pico de uso da equipe (início da manhã, por exemplo). Os agentes dividem a capacidade do provedor com as conversas da Filipa.
Bloco Entrega do resultado
| Campo | Como preencher |
|---|---|
| Entrega | E-mail ou Webhook. Determina quais campos aparecem abaixo. |
| Formato de saída | Texto simples, Markdown, JSON para integração, Página HTML, Planilha CSV, Documento PDF, Documento Word, Planilha Excel ou Apresentação PowerPoint. Por e-mail, toda execução gera um arquivo nesse formato. Por webhook, Texto simples e Markdown seguem no próprio corpo, sem arquivo. Ao trocar a entrega para Webhook, o formato passa automaticamente para JSON para integração (você pode trocar depois). |
| Destinatários de e-mail (entrega E-mail) | Digite um e-mail e pressione Enter para cada um; aceita separação por vírgula, ponto e vírgula ou espaço. Pelo menos um é obrigatório. E-mails inválidos são recusados na hora. |
| Destino do webhook (entrega Webhook) | Genérico (endpoint próprio), Slack, Microsoft Teams, Discord ou Google Chat. Define o formato do corpo enviado. |
| Webhook (URL https) | A URL que receberá o POST. Só https é aceito. O ícone de ajuda ao lado abre o guia de validação da assinatura. |
| Segredo do webhook | Gerado pelo Vendelo ao salvar o agente com a URL. Aparece somente leitura, com botão de copiar. Guarde-o no servidor que recebe o webhook. |
E-mail e webhook recebem um link de download, válido pelo prazo de retenção das Configurações de IA (sete dias por padrão), não o arquivo em si. Quando a execução é interrompida por um limite, a entrega leva o arquivo partial-result.txt com o que ficou pronto; e um provedor por assinatura que gere vários arquivos entrega um .zip. Com destino Slack, Teams, Discord ou Google Chat e formato JSON, o JSON produzido pelo agente é enviado como está; nos demais formatos, esses destinos recebem uma mensagem de texto com o link. O artigo de entrega detalha cada caso.
A descrição do que o agente deve fazer
O campo “Descreva o que o agente deve fazer” aceita até 8.000 caracteres e é o coração do agente. Escreva como se estivesse explicando a tarefa a uma pessoa nova na equipe, que fará o trabalho sozinha, sem poder perguntar nada. Depois de salvar, a validação com a Filipa vai reescrever essa descrição como uma instrução completa, citando os dados do Vendelo que ela confirmou existirem.
Boas práticas de descrição
- Objetivo em uma frase: “Relatório semanal das cotações abertas que vencem nos próximos 7 dias.”
- Período relativo à execução: “próximos 7 dias contados da data da execução”, “mês anterior ao da execução”. Nunca datas fixas: o agente roda repetidas vezes.
- Colunas e agrupamentos: “uma linha por cotação com número, cliente, vendedor, valor e data de validade; totalizar por vendedor”.
- Ordenação: “ordenar por data de validade crescente”.
- O que fazer sem dados: “se não houver cotações no período, gerar o arquivo com a mensagem ‘Nenhuma cotação vence no período'”.
- Formato e idioma: coerentes com o formato de saída escolhido; para JSON, descreva os campos esperados.
- Não peça envio: não escreva “envie por e-mail para…”. A entrega é feita pelo Vendelo com os destinatários do cadastro; a validação remove pedidos de envio.
Descrição fraca: “manda as cotações da semana pros supervisores”. Falta período exato, colunas, ordenação, comportamento sem dados, e pede envio. A validação vai devolver várias pendências.
Salvando e o que acontece depois
Enquanto faltar algum campo obrigatório, o rodapé mostra o botão Pendências, que lista o que ainda precisa ser preenchido. O botão Salvar só aparece quando o formulário está válido (nome, modelo, entrega com destinatário ou URL https válida, descrição e, se houver agendamento, fuso horário). Ao salvar, o agente fica com status Rascunho, o segredo do webhook é gerado (se houver URL) e aparece o botão Validar com a Filipa. A ativação só é oferecida depois de salvar; o próximo artigo cobre validação e ativação.
Resumo dos campos
| Campo | Obrigatoriedade | Descrição |
|---|---|---|
| Nome | Obrigatório | Até 100 caracteres, único. |
| Modelo | Obrigatório | Modelo do provedor de agentes. |
| Empresas | Opcional | Vazio: a empresa atual; com seleção, a instrução cobre essas empresas. |
| Fuso horário | Obrigatório com agendamento | Fuso do agendamento e dos períodos. |
| Agendamento | Opcional | Sem agendamento significa execução manual. |
| Entrega | Obrigatório | E-mail ou Webhook. |
| Formato de saída | Obrigatório | Um dos nove formatos. |
| Destinatários de e-mail | Obrigatório com entrega E-mail | Um ou mais e-mails válidos. |
| Destino e URL do webhook | Obrigatório com entrega Webhook | URL https válida. |
| Segredo do webhook | Gerado | Somente leitura; copiar para o servidor de destino. |
| Descrição | Obrigatório | Até 8.000 caracteres. |
Perguntas frequentes
Posso mudar o formato depois de validar?
Sim, mas valide de novo: a instrução reescrita cita o formato, e os requisitos de geração mudam (uma planilha precisa de colunas; uma apresentação, de slides).
O agente pode consultar mais de uma empresa e gerar um arquivo só?
Sim. Selecione as empresas e descreva se quer uma seção por empresa ou um consolidado.
Por que a URL do webhook foi recusada?
Só URLs https são aceitas. Confira também se não há espaços ou caracteres inválidos.
Perdi o segredo do webhook. Como gerar outro?
O segredo fica visível no cadastro enquanto o canal de webhook existir, e trocar só a URL mantém o mesmo segredo. Para gerar outro: apague a URL, mude a Entrega para E-mail, informe um destinatário e salve; depois volte para Webhook, cole a URL e salve. Um novo segredo é criado.
Posso copiar um agente existente?
Nesta versão não há duplicar. Abra o agente, copie a descrição e crie um novo com os ajustes.
Preciso escrever em inglês para o modelo entender?
Não. Escreva no seu idioma. A Filipa cuida da comunicação técnica com o modelo.
Próxima leitura
Validar com a Filipa, ativar, pausar e executar: entenda a validação, resolva pendências e coloque o agente para rodar.
