Agente de IA

Execute agentes de IA dentro dos seus fluxos

O nó IA Agente utiliza um agente de IA personalizado para tomar decisões e executar tarefas de forma autônoma dentro de um Spaceflow. Durante a execução do fluxo, o agente opera sobre os dados do workspace usando as mesmas ferramentas de IA disponíveis na plataforma.

O agente utilizado é um dos configurados em Configurações > Agentes de IA, herdando seu tipo, modelo, regras e ferramentas.

Quando usar

Use este nó quando a etapa depende de uma decisão que não cabe em uma condicional fixa. Diferente dos demais nós de IA, que produzem um resultado a partir de uma instrução única, o IA Agente pode encadear várias ações até chegar ao resultado: consultar um registro, avaliar o que encontrou e agir conforme a situação.

Exemplos de uso:

• Classificar uma solicitação recebida e encaminhá-la conforme o conteúdo.
• Consultar registros relacionados antes de preencher um campo.
• Resolver uma etapa que exigiria triagem manual.

Consulta a várias categorias em um só nó

Dentro da mesma etapa, o agente encadeia chamadas de ferramenta até concluir o que a instrução pediu. É esse encadeamento que permite varrer o workspace inteiro atrás de um valor, sem montar um nó de leitura para cada categoria.

A ferramenta de listagem de registros consulta uma categoria por vez. Quando a instrução pede uma busca ampla, o agente repete essa consulta categoria a categoria dentro do próprio nó e reúne tudo em um resultado só. Ao final, ele informa em quais categorias procurou e devolve os registros com correspondência, identificando a categoria e o código de referência de cada um.

O resultado chega ao nó seguinte como texto, dentro do campo text da saída, e não como uma lista de registros com os campos separados um a um. Os valores ficam acessíveis aos próximos nós, mas quem precisa de um campo isolado tem de extraí-lo desse texto.

A relação de categorias sem correspondência, logo abaixo dos itens, é o que comprova que a varredura passou por todas as categorias do workspace e não parou na primeira.

Dois campos do nó definem o alcance da varredura:

• Máximo de passos — quantas chamadas de ferramenta o agente pode fazer na etapa. Uma varredura completa gasta pelo menos uma chamada por categoria, então um limite baixo interrompe a busca antes do fim.
• Filtro de ferramentas — quais ferramentas o agente pode usar. Cada ferramenta traz a descrição do próprio escopo ao lado do nome, e é ali que se confirma se a consulta vale para uma categoria ou para o workspace inteiro.

A mesma lista de ferramentas aparece na criação do agente, em Configurações > Agentes de IA.

Buscar por referência de relacionamento

Além de buscar por texto livre, o agente pode localizar registros a partir da referência de um relacionamento. Isso permite reunir, em uma única etapa, todos os itens vinculados a um registro específico, mesmo que estejam espalhados por categorias diferentes.

O cenário mais comum é o de um registro central — como um cliente — que se relaciona com itens de várias categorias — como contratos, serviços e faturas. Em vez de montar um nó de leitura para cada categoria, o agente recebe a referência do cliente e varre o workspace atrás de itens que apontem para essa mesma referência em seus campos de relacionamento.

Para que a busca funcione:

• A instrução deve indicar a referência a ser usada como ponto de partida.
• O Filtro de ferramentas deve incluir a ferramenta de consulta que opera sobre relacionamentos.
• O Máximo de passos deve comportar pelo menos uma chamada por categoria a ser verificada.

O resultado chega ao nó seguinte como texto, no campo text, com os itens agrupados por categoria. Quem precisar de um campo isolado extrai o valor desse texto, da mesma forma que na busca por texto livre.

Consultar e gravar na mesma etapa

O nó não se limita a leitura. Com uma ferramenta de escrita habilitada no Filtro de ferramentas, o agente usa o que encontrou na consulta e grava o resultado dentro da própria etapa, sem depender de um nó de CRUD depois dele.

A categoria de destino da gravação não precisa ter sido consultada na etapa de busca. Basta que a instrução indique onde gravar e que a ferramenta de criação esteja liberada no filtro. Campos de relacionamento são preenchidos com o registro correspondente encontrado na busca.

Cada chamada de ferramenta consome um passo, e a gravação entra nessa mesma conta. Ao somar busca ampla e criação na mesma etapa, dimensione o Máximo de passos para cobrir as duas partes.

Para o que a ferramenta de criação aceita e seus limites, consulte Criar Item.

Execução sem membro associado

As ferramentas do nó funcionam mesmo sem um membro associado à execução. Isso importa nos fluxos disparados por webhook ou por agendamento, em que não há um usuário logado por trás da execução: o agente consegue operar normalmente nesses cenários.

Como configurar

1. No editor do fluxo, adicione o nó IA Agente ao ponto desejado.
2. Selecione o agente que executará a etapa.
3. Descreva a instrução da etapa, indicando o que deve ser feito e o que se espera como resultado.
4. Defina o que segue para os próximos nós a partir do resultado.

Para acompanhar o que o agente fez em cada execução, consulte Spaceflow.

Para criar e configurar agentes, consulte Agentes de IA.

Passo a passo: configurar o nó e conferir o resultado

Da inclusão do nó no canvas até a resposta na tela de execução:

Tutorial guiado