n8n

O n8n-nodes-stac é um pacote de node comunitário que adiciona o sub-node Stac Chat Model ao n8n. Ele se conecta ao input Model de qualquer node raiz de IA — AI Agent, Basic LLM Chain, Question and Answer Chain — para que o workflow rode no seu stack em vez de um provedor cobrado por token.

O node conversa com a mesma superfície compatível com OpenAI de todo o resto aqui, então nada muda no seu stack: mesma chave, mesma base URL, mesmo preço fixo mensal por mais que o workflow dispare.

Instale o node#

1. Abra Settings → Community nodes

   Você precisa ser o owner da instância. Veja o guia de instalação do n8n se a seção não aparecer.

2. Instale o n8n-nodes-stac

   Clique em Install a community node, informe o nome do pacote, aceite o aviso de riscos e instale. O n8n recarrega o registro de nodes sozinho — não é preciso reiniciar o container.

3. Ou instale manualmente

   Numa instância self-hosted você pode pular a interface e instalar direto no diretório de nodes customizados do n8n:

   bash

   cd ~/.n8n/nodes
   npm install n8n-nodes-stac

   Reinicie o n8n depois.

Crie a credencial#

O pacote traz um tipo de credencial, Stac API, compartilhado por todos os seus nodes.

A autenticação é por bearer token (Authorization: Bearer <chave>), igual a qualquer outro cliente Stac. O botão Test da credencial chama GET /v1/models, então um teste verde confirma a chave e a base URL de uma só vez.

Adicione ao workflow#

1. Adicione um node raiz de IA

   O AI Agent é o ponto de partida usual, mas qualquer node com input Model funciona.

2. Conecte o Stac Chat Model ao input Model

   Busque "Stac" no painel de nodes — ele aparece em Language Models → Chat Models.

3. Escolha o modelo

   O dropdown Model é preenchido no momento da edição a partir de GET /v1/models, então lista exatamente o que sua chave pode chamar — na maioria dos planos, uma única entrada: o modelo que seu stack roda.

Parâmetros#

Tudo além de Model fica em Options e é opcional.

Como ele se encaixa no n8n#

O node monta o modelo via supplyModel do @n8n/ai-node-sdk, que o próprio n8n fornece em runtime. Duas consequências que vale conhecer:

• Nenhum LangChain empacotado. n8n-workflow e @n8n/ai-node-sdk são peer dependencies, então o processo mantém uma única instância de @langchain/core em vez de duas disputando.
• As execuções são rastreadas pelo próprio n8n. As chamadas ao modelo aparecem na visão de log e tracing do n8n, com prompts e contagem de tokens, não apenas como uma chamada HTTP opaca.

Desenvolvido e testado com o n8n 2.36.9. Versões mais antigas trazem releases anteriores desse SDK e não foram testadas.

AI Assistant do editor#

Isso é diferente do node Chat Model acima: é o AI Assistant nativo do n8n — o recurso que monta, executa e itera um workflow inteiro a partir de um prompt, dentro do próprio editor, em vez de um node dentro de um workflow já montado. Ele também aceita um provedor de modelo próprio, compatível com OpenAI, então dá para apontá-lo para o seu stack.

1. Confirme os requisitos

   Precisa de uma versão recente do n8n self-hosted com suporte ao módulo instance-ai, e de uma sandbox rodando — obrigatória para o Assistant executar o que constrói. Veja a documentação de setup do n8n para as opções de sandbox.

2. Configure as variáveis de ambiente da instância

   A mesma chave da tabela acima serve aqui — não precisa criar outra.

   bash

   N8N_ENABLED_MODULES=instance-ai   # some aos módulos já habilitados
   N8N_INSTANCE_AI_MODEL_URL=https://api.trystac.com/v1
   N8N_INSTANCE_AI_MODEL_API_KEY=<a mesma chave da página API keys>

3. Reinicie a instância

   O módulo só é carregado no boot do n8n.

Resolução de problemas#

• O dropdown de Model está vazio. A credencial não consegue alcançar GET {baseUrl}/models — chave errada, base URL errada, ou a instância sem acesso de rede de saída. Rode o teste da credencial para descobrir qual.
• 401 invalid_api_key. A chave foi revogada ou pertence a um stack deletado. Gere uma nova; veja Erros.
• 429 num workflow movimentado. Os limites de uso são por chave. Dê ao n8n a própria chave para que uma tempestade de retries no workflow não limite sua aplicação.
• O node não aparece depois de instalar. Confira se N8N_COMMUNITY_PACKAGES_ENABLED não está em false e recarregue o editor.

Recursos#

• n8n-nodes-stac no npm
• Código no GitHub
• Documentação de community nodes do n8n

Base de conhecimento#

Os nodes de agente do n8n sempre enviam uma mensagem system própria — o campo "System Message" vem preenchido mesmo que você nunca o edite. Por isso, para fundamentar as respostas nos seus documentos, a chave usada aqui precisa estar com a base de conhecimento ativada:

1. No dashboard, vá em Chaves de API.
2. Na chave usada pela credencial do n8n, abra ⋮ → Configurações.
3. Ligue Base de conhecimento e escolha Ativada.

Uma chave em "automático" — o estado das chaves criadas antes dessa opção existir — nunca consulta a base a partir do n8n, justamente porque o node manda system em toda requisição. O sintoma é silencioso: o modelo responde como se não houvesse documento nenhum, sem erro.

A persona do agente continua vindo do campo "System Message" do node: o trecho recuperado é anexado depois dele, não no lugar dele.

Próximos passos#

• Compatibilidade OpenAI — a superfície que o node fala e o que difere da OpenAI.
• Autenticação — formato da chave, escopo, rotação.
• Base de conhecimento — fundamente as respostas do workflow nos seus documentos, sem nenhum node de busca no canvas.