Um agente autônomo é um pedido à Filipa que roda sozinho, no horário que você define, e entrega o resultado por e-mail ou webhook sem ninguém precisar abrir o Vendelo. O relatório semanal de cotações vencendo, o resumo diário de pedidos aguardando aprovação, a planilha mensal de metas por vendedor: tudo isso vira um agente. Este artigo explica o que é um agente, o ciclo de vida completo (cadastrar, validar com a Filipa, ativar, executar, entregar), os papéis de cada tela do subgrupo Agentes, os requisitos para usar e as regras de segurança. Ao final, você saberá quando criar um agente e o que esperar dele.
Índice
O que é um agente autônomo
É um cadastro no Vendelo com quatro partes: uma instrução (o que fazer, em linguagem natural), um agendamento (quando rodar, ou execução manual), um formato de saída (texto, planilha, apresentação, PDF, entre outros) e uma entrega (e-mail para destinatários ou webhook para um sistema). Na hora marcada, o serviço de agentes da Vendelo executa a instrução usando a mesma Filipa das conversas: consulta o Vendelo com o usuário dono do agente, produz o resultado no formato pedido e o Vendelo entrega.
A entrega foi pensada para os canais que a equipe já usa. Além do e-mail, um agente pode publicar direto em um canal do Slack, do Microsoft Teams, do Discord ou do Google Chat, com a mensagem no formato nativo de cada aplicativo, ou enviar o resultado a um sistema seu por webhook assinado. Assim, o resumo diário da fila de aprovação pode aparecer às 7h30 no canal dos aprovadores, sem que ninguém abra o Vendelo ou o e-mail.
Quando usar um agente em vez de uma conversa
| Situação | Melhor caminho |
|---|---|
| Pergunta pontual, resposta para ler agora | Conversa com a Filipa |
| Arquivo único, uma vez | Conversa, pedindo o arquivo |
| Mesmo relatório toda semana ou todo dia | Agente agendado |
| Resultado deve chegar a outras pessoas | Agente com entrega por e-mail |
| Resultado deve alimentar outro sistema (Slack, Teams, integração) | Agente com entrega por webhook |
| Relatório sob demanda, mas sempre igual | Agente sem agendamento, executado com “Executar agora” |
O ciclo de vida de um agente
Cadastrar: em Filipa IA, Agentes, Agentes de IA, crie o agente com nome, modelo, empresas, fuso, agendamento, entrega, formato e a descrição do que ele deve fazer. Ao salvar, o agente fica em Rascunho.
Validar com a Filipa: o botão com o rosto da Filipa envia a descrição para ela analisar. Ela verifica se os dados existem no Vendelo, reescreve a descrição como uma instrução completa e lista as pendências (critérios que você precisa decidir). O prompt reescrito substitui o seu; revise e salve.
Ativar: com o agente salvo e validado, toque em Ativar agente. O agendamento é registrado e o status passa a Ativo. Sem agendamento, o agente ativo só roda por “Executar agora”.
Executar: no horário marcado (gatilho Agendado) ou quando você toca em Executar agora (gatilho Manual), uma execução entra na fila, roda e termina com sucesso ou falha.
Entregar: ao concluir, o Vendelo envia o e-mail ou o webhook com o link do arquivo gerado, válido pelo prazo de retenção definido nas Configurações de IA (sete dias por padrão). A execução e os arquivos ficam no Histórico de execuções.
Pausar e retomar: a qualquer momento você pausa (o agendamento é removido) e retoma (o agendamento volta). Um agente pausado ainda aceita Executar agora.
As telas do subgrupo Agentes
| Tela | Função | Permissão |
|---|---|---|
| Agentes de IA | Lista e cadastro; botões de salvar, validar, ativar, pausar, retomar, executar agora e histórico. | Agentes de IA |
| Histórico de execuções | Execuções de todos os agentes com status, duração, gatilho, resumo, arquivos e situação da entrega. | Execuções de agente de IA |
| Uso de tokens dos agentes | Consumo por execução, com provedor, modelo, tokens e segundos ativos; o rodapé soma os tokens do filtro. | Execuções de agente de IA |
Requisitos
- Agentes habilitados: o master liga “Agentes autônomos habilitados” e escolhe o provedor em Filipa IA, Configurações de IA. Sem isso, o subgrupo Agentes não aparece.
- Provedor com modelos homologados: os modelos oferecidos no cadastro do agente são os do provedor dos agentes. A Filipa foi homologada com os modelos gpt-5.6-luna e superiores (ChatGPT) e claude-sonnet-5 e superiores (Claude). O cadastro do provedor permite incluir modelos inferiores, mas eles não foram validados. Provedores “via assinatura hospedada” são comuns aqui pelo custo previsível.
- Permissões no perfil: Agentes de IA (com edição para operar), Execuções de agente de IA e, para mexer em destinatários e webhook, Canais de entrega dos agentes de IA.
- Filipa liberada para o proprietário: o dono do agente precisa da permissão Chat da Filipa, assistente de IA (ou ser usuário master). Sem ela, cada execução falha com o tipo ai_copilot_access_required e conta para a pausa automática.
- E-mail confirmado: o dono do agente precisa ter e-mail confirmado; a ativação verifica isso.
Segurança: com quem o agente executa
O agente executa com o usuário que o criou (o proprietário). Ele enxerga exatamente o que esse usuário enxerga: mesmas empresas (a instrução validada indica em quais delas trabalhar), mesma carteira, mesmos campos. Se o proprietário perde uma permissão, o agente perde junto.
Ao entregar por e-mail ou webhook, o resultado sai do Vendelo. Escolha destinatários que possam ver aquele conteúdo. A permissão do destinatário no Vendelo não é verificada: o filtro é o do proprietário do agente.
- O agente é somente leitura no Vendelo: consulta e produz, nunca altera.
- A entrega é feita pelo Vendelo, não pelo agente. O agente não envia e-mails nem chama sistemas por conta própria; se a instrução pedir isso, a validação remove.
- Os arquivos gerados ficam armazenados pelo prazo de retenção das Configurações de IA (sete dias por padrão) e são compartilhados por link; depois disso, são removidos.
Falhas e pausa automática
Uma execução pode falhar por dados indisponíveis, limite do provedor ou erro na instrução. A falha fica registrada no histórico com o tipo e a mensagem. Para evitar consumo em loop, o agente é pausado automaticamente após três falhas consecutivas. Uma execução bem-sucedida zera o contador. Depois de corrigir a causa, use Retomar; o contador volta a zero.
Algumas situações não contam como falha para a pausa:
- Instabilidade momentânea na consulta aos dados do Vendelo.
- Falta de cota em provedor por assinatura: a execução volta para Na fila e é retomada quando a cota libera.
- Falha apenas na entrega (e-mail ou webhook): a execução termina como concluída com falha na entrega.
Exemplos de agentes
- Cotações vencendo: toda segunda às 8h, planilha Excel com as cotações abertas que vencem nos próximos sete dias, por vendedor, enviada por e-mail aos supervisores.
- Fila de aprovação com risco: todo dia útil às 7h30, resumo em PDF dos pedidos aguardando aprovação com nível de risco, para os aprovadores.
- Metas do mês: no dia 1 de cada mês, apresentação PowerPoint com meta versus realizado por filial e vendedor do mês anterior, para a diretoria.
- Alerta no Slack: a cada hora, JSON com os pedidos criados na última hora acima de um valor, enviado ao webhook do canal comercial no Slack.
- Clientes inativos: toda sexta, CSV com clientes da carteira sem compras há 90 dias, para a equipe de reativação.
Perguntas frequentes
Quantos agentes posso criar?
Não há limite fixo de cadastro. O que limita é o consumo de IA e a concorrência do provedor. Comece com poucos e acompanhe o uso de tokens.
O agente roda mesmo se eu não estiver logado?
Sim. Ele roda no servidor, no horário do agendamento, com o seu usuário, independentemente de você estar conectado.
Posso ter um agente sem horário?
Sim. Escolha “Sem agendamento (execução manual)” e use Executar agora quando precisar.
O agente pode fazer perguntas durante a execução?
Não. Por isso a validação com a Filipa lista as pendências antes: tudo o que seria pergunta precisa estar decidido na instrução.
Outro usuário pode editar o meu agente?
Depende das permissões do perfil dele. O agente continua executando com o usuário proprietário, mesmo que outro edite a instrução.
Qual a diferença entre gatilho Agendado e Manual?
Agendado é a execução disparada pelo horário; Manual é a disparada por Executar agora. As duas aparecem no histórico com o gatilho indicado.
Próxima leitura
Cadastrando um agente de IA: preencha cada campo do agente, do agendamento à descrição, com boas práticas de instrução.
