👤 Para admins do pipe
🔐 Disponível para todos os planos
🎯 Para quem quer colocar o primeiro AI Agent em produção
A dúvida mais frequente de quem chega ao Pipefy não é "o que um AI Agent faz". É "como eu configuro um para o meu processo agora". Este artigo responde exatamente isso: do acesso à tela até o primeiro agente rodando em produção, com um exemplo concreto que qualquer time consegue replicar.
O caso de uso escolhido é triagem de solicitações por categoria e urgência. É o mais universal: serve para RH, compras, TI e operações. Não exige documentos externos nem configuração avançada. O resultado aparece no card imediatamente após a primeira execução.
📖 O que você vai fazer aqui:
Antes de começar: prepare o pipe
Um AI Agent opera sobre campos que já existem no card. Antes de criar o agente, confirme que o pipe tem os campos que ele vai ler e os campos onde vai escrever o resultado.
Para o exemplo de triagem, o pipe precisa de:
Campos de entrada (o que o agente vai ler):
- Descrição da solicitação — campo de texto longo onde o solicitante explica o pedido
Campos de saída (onde o agente vai escrever o resultado):
- Categoria — campo de seleção com as opções do seu processo (ex: TI, RH, Financeiro, Operacional)
- Urgência — campo de seleção com as opções: Alta, Média, Baixa
Os nomes dos campos de saída fazem parte das instruções do agente. Use nomes descritivos e consistentes. "Categoria da Solicitação" é mais preciso para a IA do que "Campo 1".
Passo 1: acesse a tela de AI Agents
No cabeçalho do pipe, clique em Agentes de IA. Se for a primeira vez, a tela estará vazia. Clique em Novo Agente de IA no canto superior direito.
Passo 2: defina nome e descrição
A primeira tela pede nome e descrição. O campo Descrição é obrigatório e não é apenas organizacional: a IA usa esse texto para entender o propósito do agente e melhorar a qualidade das respostas.
Para o exemplo de triagem:
Nome: Triagem de Solicitações
Descrição: Analisa a descrição da solicitação e classifica automaticamente por categoria e nível de urgência para agilizar o roteamento pela equipe.
Quanto mais específica a descrição, mais o agente entende seu papel. Descreva o que ele faz e para que serve, não apenas como ele se chama.
Passo 3: configure o Conhecimento
A aba Conhecimento define o que o agente sabe além do próprio card. Para o exemplo de triagem, não é necessário adicionar nada: o agente vai operar só com o conteúdo do campo de descrição.
Dois casos em que vale adicionar conhecimento:
- Você quer que o agente classifique com base em critérios específicos da empresa (ex: uma política interna em PDF)
- Você quer que o agente consulte dados de outro pipe antes de tomar a decisão (ex: histórico de solicitações do mesmo solicitante)
Para o primeiro agente, comece sem conhecimento. Adicione fontes depois, quando o comportamento básico já estiver funcionando como esperado.
Passo 4: configure o Comportamento
O comportamento é o núcleo do agente. Ele tem três partes: o gatilho, a instrução e as ações.
4.1 Escolha o gatilho
O gatilho define quando o agente vai agir. Para triagem, o momento ideal é a chegada do card na primeira fase do pipe, quando a descrição já foi preenchida pelo solicitante.
Gatilho recomendado: Quando um card entrar em uma fase — selecione a fase inicial do pipe.
⚠ Evite usar "Quando um card for criado" se o campo de descrição só é preenchido depois. O agente vai ler um campo vazio e o resultado não vai fazer sentido.
4.2 Escreva a instrução
A instrução é o que o agente vai seguir para tomar a decisão. Ela é escrita em linguagem natural, mas precisa ser precisa o suficiente para gerar um resultado consistente.
Quatro princípios que definem a qualidade do prompt:
- Comece com um verbo de ação. É mais claro dizer "Analise" ou "Classifique" do que "Eu quero que você entenda".
- Use os campos dinâmicos, não texto fixo. Em vez de digitar o nome do campo manualmente, use a barra / ou o botão + para inserir o campo como variável dinâmica. Isso garante que o agente sempre leia o conteúdo real do card.
- Instrua os dois caminhos. Diga o que fazer quando a condição é atendida e quando não é. Agentes sem instrução para o caminho negativo frequentemente ficam sem ação.
- Use exemplos dentro do prompt quando o critério for subjetivo. "Classifique como Urgência Alta se o solicitante mencionar prazo inferior a 24 horas ou impacto financeiro imediato" é mais eficaz do que "classifique por urgência".
Exemplo de instrução para o caso de triagem:
Analise o campo [Descrição da Solicitação] e faça o seguinte:1. Classifique a solicitação em uma das categorias: TI, RH, Financeiro ou Operacional. Se não for possível determinar a categoria, use "Outros".2. Defina o nível de urgência: - Alta: solicitação menciona prazo inferior a 24 horas, impacto financeiro imediato ou paralisação de operação. - Média: solicitação menciona prazo de 2 a 5 dias ou impacto moderado. - Baixa: solicitação não menciona prazo ou o prazo é superior a 5 dias. Atualize o campo [Categoria] e o campo [Urgência] com os valores determinados.
A ordem das instruções importa. O agente executa de cima para baixo, na sequência exata em que você escreveu. Coloque a lógica de decisão antes das ações.
4.3 Defina as ações
As ações dizem ao agente o que ele deve fazer com o resultado da análise. Para o exemplo de triagem, a ação é uma: Atualizar campos do card.
No painel de ações, selecione Atualizar campos do card e mapeie:
- Campo Categoria → valor determinado pelo agente
- Campo Urgência → valor determinado pelo agente
Cada comportamento suporta até 3 ações. Se o processo exigir mais, crie um segundo comportamento com outro gatilho ou combine com uma automação complementar.
Passo 5: salve e ative
Após configurar gatilho, instrução e ações, clique em Salvar no canto inferior direito. O agente fica ativo imediatamente. A próxima vez que um card entrar na fase configurada, ele vai executar a análise.
✅ Agente ativo. A partir deste momento, cada card que entrar na fase inicial terá os campos Categoria e Urgência preenchidos automaticamente.
Passo 6: monitore os primeiros resultados
Nas primeiras execuções, abra os cards onde o agente atuou e verifique a aba Atividades. Ela mostra o que o agente fez, campo a campo, com o valor que foi escrito.
Se o resultado não for o esperado, o caminho de ajuste é quase sempre o mesmo:
- Resultado vago ou incorreto: a instrução precisa de mais contexto ou exemplos
- Campo não preenchido: verifique se o campo dinâmico foi inserido como variável, não digitado manualmente
- Agente não executou: verifique se o gatilho está apontando para a fase correta e se o card realmente entrou nela após a ativação
Um agente que se comporta de forma imprevisível quase sempre tem instrução ambígua como causa. Refine o prompt antes de alterar gatilho ou configuração de ações.
Para investigar falhas com mais detalhe, acesse Automações no cabeçalho do pipe e clique na aba Logs. Lá você encontra o status de cada execução e o raciocínio detalhado do agente.
Antes de avançar, confirme que você fez:
☐ Campos de entrada e saída criados no pipe com nomes descritivos
☐ Nome e descrição do agente preenchidos de forma específica
☐ Gatilho apontando para o momento em que as informações já estão disponíveis no card
☐ Instrução com verbo de ação, campos dinâmicos e critérios para os dois caminhos (positivo e negativo)
☐ Primeiros cards monitorados na aba Atividades após a ativação
