Atualize o AI Agent v1 para o Tools Agent
Antes de começar
Passar cada AI Agent na versão 1 para a versão atual do Node, com o Tools Agent e as ferramentas que substituem o modo antigo.
- Lista de workflows afetados no relatório de migração.
- Instância de testes com cópia da sua instância.
- Credencial do modelo de chat usada pelo agente.
A versão 1 do AI Agent saiu do n8n 3.0 e levou junto os modos SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent e ReAct Agent. Um workflow que ainda usa essa versão falha na execução. A versão atual do Node troca todos esses modos pelo Tools Agent, que já era a configuração recomendada e a mais usada.
Um AI Agent v1 que já estava em Tools Agent mantém o mesmo comportamento depois da atualização do Node. O trabalho maior fica com os agentes nos outros modos, porque, na versão atual, eles agem pelas ferramentas ligadas ao conector Tool.
Qual configuração substitui cada modo
| Modo no AI Agent v1 | Na versão atual |
|---|---|
| Tools Agent | Mesmo comportamento. Só é preciso atualizar o Node |
| SQL Agent | Tools Agent com um Node Postgres ou MySQL ligado como ferramenta |
| Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent e ReAct Agent | Tools Agent com as ferramentas que o agente usava |
O seletor de tipo de agente está obsoleto desde o n8n 1.82.0. Desde então, todo AI Agent novo já funciona como Tools Agent. A versão 1 costuma aparecer em workflows antigos e em templates importados antes dessa versão.
Procedimento
- Abra o relatório de migração e selecione o item do AI Agent para ver os workflows afetados. Ordene por quantidade de execuções e comece pelos agentes mais usados.
- No ambiente de testes, abra um workflow e anote o modo do agente, o modelo, a memória, as ferramentas ligadas e o prompt de sistema.
- Monte três ou quatro perguntas de teste que obriguem o agente a usar cada ferramenta. Execute e guarde as respostas da versão 1.
- Adicione um AI Agent novo ao lado do antigo. Ligue o mesmo modelo, a mesma memória e as mesmas ferramentas. Depois, copie o prompt de sistema.
- Se o agente antigo estava em SQL Agent, ligue ao conector Tool um Node Postgres ou MySQL com a credencial do banco que o agente consultava.
- Ligue a entrada e a saída do agente novo no lugar do antigo e apague o Node antigo.
- Repita as perguntas de teste e compare com as respostas guardadas.
O Tools Agent exige pelo menos uma ferramenta ligada. Um agente que só conversava, sem ferramenta, precisa de uma, mesmo que simples, como o Calculator.
O que conferir depois
- Chamadas de ferramenta. Abra a execução e confira, no painel do agente, quais ferramentas ele chamou em cada pergunta. Um agente em ReAct que descrevia o raciocínio no texto agora decide pelas descrições das ferramentas, por isso uma descrição vaga faz o agente escolher a ferramenta errada.
- Consultas ao banco. No caso do SQL Agent, confira que a ferramenta Postgres ou MySQL usa uma credencial com permissão só de leitura quando o agente não deveria alterar registros.
- Formato da resposta. Se o workflow depois do agente lê um campo da resposta, confira que o campo continua com o mesmo nome. O Tools Agent pode usar um output parser para entregar um formato fixo.
- Templates guardados. Atualize também os templates e os workflows exportados que você reaproveita, para o AI Agent v1 não voltar em uma importação futura.
O guia sobre as ferramentas do agente explica como escrever descrições que ajudam o modelo a escolher a ferramenta certa.
Confira o resultado
Com as mesmas perguntas de teste, o agente na versão atual chama as ferramentas esperadas e entrega respostas equivalentes às da versão 1.
