👤 Para administradores de pipe e gestores de processo
🔐 Disponível nos planos pagos
🎯 Para quem quer criar um AI Agent configurado para o seu processo, sem começar de uma tela em branco
Criar um AI Agent na tela do Pipefy é direto: você define o nome, escreve as instruções e configura os behaviors um a um. Mas quando o processo já existe e tem estrutura, fases e padrões de uso, começar de uma tela em branco significa ignorar tudo o que o pipe já sabe sobre si mesmo.
Com o MCP Server conectado, o assistente lê o pipe antes de propor qualquer coisa. Os behaviors que ele sugere vêm das fases, das automações e dos campos que existem ali. O que sai do outro lado é uma proposta construída a partir do processo real, e você a valida antes de ativar.
Pré-requisitos para este fluxo: instalação local do MCP Server, habilidade de admin no pipe e a opção de AI Agents habilitada nas preferências do pipe. Faltando o último, a etapa 1 falha sem deixar claro o motivo, então vale conferir antes de começar.
📖 O que você vai encontrar aqui:
Configurar manualmente ou pelo assistente
Os dois caminhos chegam ao mesmo lugar: um AI Agent configurado no Pipefy. A diferença está no ponto de partida.
| Configuração manual | Pelo assistente |
|---|---|
| Você começa com um agente em branco | O assistente começa lendo o pipe existente |
| Você escreve cada behavior do zero | Os behaviors são propostos a partir das fases e dos padrões do processo |
| Você precisa conhecer bem o processo para configurar bem | O processo já está descrito no pipe, e o assistente usa isso |
| Bom quando o processo ainda não existe no Pipefy | Bom quando o processo já está rodando com estrutura definida |
Os dois caminhos são complementares. Se o processo ainda não existe no Pipefy, monte o pipe primeiro e depois peça o agente. Se o processo já roda, o assistente poupa o trabalho de análise manual.
O que o assistente lê antes de propor o agente
Antes de propor qualquer behavior, o assistente inspeciona o pipe. Essa leitura segue uma sequência definida, e é o que diferencia a proposta de um modelo genérico:
- Fases e fluxo de movimentação: quais são as etapas, em que ordem os cards percorrem e onde estão os pontos de decisão
- AI Agents que já existem: a verificação serve especificamente para evitar duplicar um agente que já cobre aquela responsabilidade
- Automações existentes: os eventos que disparam cada uma e as ações que elas executam, para não propor um behavior que competiria com uma automação
- Campos e dados disponíveis: quais informações o card carrega e quais podem alimentar as instruções do agente
O segundo item é o mais importante e o menos óbvio. Checar os agentes existentes antes de propor novos é um passo deliberado do fluxo, não uma gentileza do modelo. É por isso que a proposta não vira um agente duplicado quando você já tem um cobrindo parte do processo.
O fluxo completo, em cinco etapas
A ordem importa: criar, validar, revisar, testar e só então ativar. Ativar antes de validar é o erro mais comum, e o único que exige refazer trabalho.
Etapa 1: criar o agente a partir do pipe
🔓 Requer instalação local · admin no pipe · AI habilitada no pipe
Você digita: Analise o meu pipe de [nome] e crie um AI Agent para o processo, deixando ele desativado
Pipefy executa: lê a estrutura do pipe, mapeia fases, automações e campos, propõe os behaviors e cria o agente
O que retorna: confirmação de que o agente foi criado, com nome e a lista de behaviors propostos
Pedir que o agente seja criado desativado é o hábito que protege o processo. Você revisa e testa antes de ele começar a atuar em cards reais. O padrão de criar desativado e habilitar depois já é recomendado para automações, e vale igual aqui.
Um agente aceita de um a cinco behaviors. Em processos com fases bem definidas, a proposta tipicamente fica em três, mas isso é tendência do resultado e não uma característica do produto. Cada behavior precisa de pelo menos uma ação configurada, senão a criação é recusada com a mensagem de que as instruções precisam conter no mínimo uma ação.
Etapa 2: validar os behaviors antes de qualquer execução
✓ Somente leitura
Você digita: "Valide os behaviors do agente que você criou no pipe [nome]"
Pipefy executa: roda a validação dos behaviors sem executar nenhuma ação no processo
O que retorna: o resultado da validação, apontando behaviors mal formados ou instruções sem ação
Esta etapa é uma verificação prévia: nada é executado no pipe. É o jeito de descobrir problemas de configuração antes de gastar um card de teste, e é a etapa que a maioria pula.
Etapa 3: revisar na tela do Pipefy
✓ Somente leitura
Você digita: "Liste os agentes do pipe [nome] com a configuração de cada um"
Pipefy executa: busca os agentes do pipe e devolve nome, descrição e behaviors configurados
O que retorna: a configuração completa para você conferir, e o nome do agente para localizar na tela
Com o nome em mãos, abra o pipe no Pipefy e vá até a seção de AI Agents para ver o agente. O assistente não devolve um link direto para o agente, então a navegação é pela tela do pipe. Ali você encontra:
- Nome e descrição: gerados a partir do contexto do pipe, não de texto genérico
- Behaviors: de um a cinco, cada um com a sua própria descrição e instruções
- Instruções por behavior: escritas com referência ao que existe no pipe, com campo e fase quando relevante
Detalhe de vocabulário que evita confusão: o que a tela do Pipefy mostra como "Descrição" do behavior é o mesmo campo que o assistente chama de instrução. Se ele disser que gravou a instrução e você não encontrar um campo com esse nome, é a Descrição.
Um agente criado assim não vem com base de conhecimento anexada. As bases de conhecimento são criadas separadamente e vinculadas ao agente depois, então se o seu caso depende de uma base, esse é um passo à parte.
Etapa 4: testar com um card
🔓 Requer instalação local · admin no pipe · AI habilitada no pipe
Você digita: "Crie um card de teste no pipe [nome] e me diga como acompanhar o que o agente faz"
Pipefy executa: cria o card e orienta onde acompanhar a execução dos behaviors
O que retorna: o card de teste e a indicação de onde ver os registros de execução do agente
Os registros de execução do agente mostram qual behavior rodou, com que entrada e o que retornou. É onde você confirma que o comportamento é o esperado antes de deixar o agente atuar em cards reais.
Etapa 5: ativar
🔓 Requer instalação local · admin no pipe · AI habilitada no pipe
Você digita: "Ative o agente [nome] no pipe [nome]"
Pipefy executa: habilita o agente sem reenviar a configuração
O que retorna: confirmação de que o agente está ativo
A ativação usa um comando dedicado que apenas liga e desliga o agente, sem tocar na configuração. Isso importa: é o caminho seguro, porque não passa pela atualização completa do agente e portanto não corre o risco descrito na seção seguinte.
Ao ajustar um agente existente, peça a preservação explicitamente
Este é o cuidado mais importante do artigo, e o menos intuitivo. A atualização de um AI Agent substitui a configuração inteira: para adicionar um behavior, o assistente precisa reenviar todos os anteriores junto.
Se o contexto da conversa estiver incompleto, por sessão nova, conversa longa ou porque o agente foi editado na tela no meio do caminho, os behaviors que não forem reenviados desaparecem. Sem aviso e sem prévia, porque o contrato de confirmação vale apenas para exclusões.
O jeito de evitar isso é ser explícito no pedido e conferir depois:
Em vez de "adicione um behavior de resumo semanal", peça "adicione um behavior de resumo semanal ao agente [nome] do pipe [nome], mantendo os behaviors existentes". Depois, liste os behaviors do agente e confirme que a lista está completa.
Vale lembrar também do limite: cinco behaviors por agente. Se o processo pede mais responsabilidades do que isso, o caminho é um segundo agente com escopo próprio, não um agente sobrecarregado.
O que esperar do agente criado
O agente criado pelo assistente é uma proposta inicial bem fundamentada, não uma solução final. Ele trabalha com o que está visível na estrutura do pipe: se um campo importante não está configurado, ou se uma regra de negócio existe só na cabeça do time, o agente não sabe disso.
O caminho natural é o das cinco etapas: revisar os behaviors, ajustar as instruções com o contexto que o assistente não alcança e testar com card antes de ativar.
Em pipe com poucos dados ou em configuração inicial, a proposta sai mais genérica. Quanto mais o pipe reflete uso real, mais específica ela fica.
Antes de avançar, confirme que você:
☐ Conferiu os três pré-requisitos: instalação local, admin no pipe e AI habilitada no pipe
☐ Pediu o agente desativado e validou os behaviors antes de qualquer execução
☐ Revisou a configuração na tela do Pipefy e ajustou o que o assistente não tinha como saber
☐ Testou com um card antes de ativar
☐ Sabe pedir a preservação dos behaviors existentes ao fazer um ajuste
