Frequently Asked Questions About Alejandro AO Agentic RAG n8n Build
23 answers covering everything from basics to advanced usage.
// Basics
What exactly is a Knowledge Base Search tool in n8n?
It's a Vector Store Query node attached as a tool to the AI Agent, with operation set to 'Retrieve Documents (for Agent)'. The agent reads the tool's description to decide when to invoke it, then generates its own search query. You configure it with the same vector store ID used during ingestion, a result limit (4 is a reasonable default), and 'include metadata' enabled so it can cite sources.
What is the two-workflow architecture and why is it recommended?
You split your n8n workspace into an Ingestion Workflow (triggered by a file event: form, email, or Google Drive) and a Retrieval Workflow (triggered by chat or webhook). Both share the same vector store. This decouples document loading from agent conversation — ingestion runs on uploads, retrieval runs on user queries — making each workflow simpler to test, debug, and scale independently.
What is the OpenAI node used as a universal router?
The n8n OpenAI Chat Model node lets you set a custom Base URL (e.g. router.huggingface.co/v1) instead of using provider-specific nodes. This means one node can call any OpenAI-compatible endpoint — Hugging Face inference providers, Ollama, OpenRouter, or Cerebras — just by swapping the base URL and API key credential. It's the flexible backbone for connecting cheap open models to your agent.
What does 'text splitting' mean in n8n?
Text splitting is n8n's term for chunking — dividing extracted document text into smaller pieces before embedding. 'Simple' splitting uses fixed character counts (baseline, prototyping only). Chunking controls retrieval quality: keeping related information in the same chunk gives the agent complete, coherent context. Production systems use semantic or structure-aware splitting via libraries like Unstructured.
// How To
How do I set up Hugging Face credentials for both embeddings and LLM inference?
Go to huggingface.co → Profile → Access Tokens → New Token. Enable 'read repos' and 'call inference providers' permissions. In n8n, add it as an OpenAI-type credential with Base URL set to router.huggingface.co/v1. This single credential serves both your embeddings node and your Chat Model node — no need to create separate credentials for each.
How do I choose an embedding model on Hugging Face?
On huggingface.co/models, filter by Task → NLP → Feature Extraction. Copy the full model ID (e.g. BAAI/bge-m3). Record it carefully — you'll paste this exact ID into two separate nodes (the vector store insert node's embeddings and the Knowledge Base Search tool's embeddings), and they must match precisely or retrieval breaks.
How do I test my Ingestion Workflow before building the agent?
Click 'Execute Step' on the trigger to submit a test file, then execute the vector store insert node. Check the output panel — you should see page content items equal to the number of chunks extracted. Don't proceed to the Retrieval Workflow until ingestion confirms successful output, or you'll debug two broken systems at once.
How do I write an effective tool description for the agent?
The description field is what the agent reads to decide whether to call that tool, so be precise: name the tool, state exactly what data it contains, and give any heuristics. For example: 'Vector search tool for internal client reports — use for questions about our documents. Do not scrape entire Wikipedia pages, you will exceed context.' Vague descriptions cause the agent to skip or misuse the tool.
How do I test that the agent actually calls my tools?
Open the chat trigger's test panel. Send a greeting first to verify basic LLM connectivity. Then ask a document question and check the execution logs to confirm the agent calls the Knowledge Base Search tool. Then ask an internet question and verify it calls the Firecrawl MCP tools. Inspect logs for tool call counts and any thinking loops.
// Troubleshooting
Why do embeddings work but LLM inference calls get rejected?
Your Hugging Face token is likely missing the 'call inference providers' permission. Embeddings and LLM inference are separate capabilities on the token. Regenerate or edit the token to enable both 'read repos' and 'call inference providers', then update the credential in n8n. Without inference provider permission, chat model calls fail while embeddings succeed.
Why did my agent run fail or return a truncated answer?
The most common cause is the agent scraping an entire large page (like a full Wikipedia article) via Firecrawl, which exhausts the LLM's context window. Add explicit heuristics in your system prompt telling the agent not to scrape huge pages. Also check whether your open model's context length is large enough for the retrieved chunks plus conversation history.
Why did my data disappear after restarting n8n?
You're using the in-memory Simple Vector Store, which does not persist across container restarts. It's fine for demos but useless in production. Migrate to an external vector store — Chroma, Qdrant, or Pinecone — which persists your embedded chunks. Keep the store name/ID consistent between the Ingestion and Retrieval Workflows.
Why does my AI-generated workflow JSON fail to import into n8n?
Claude or Codex may hallucinate node names or node types that don't exist in n8n. Always verify each node in the generated JSON is real before relying on it. Be specific when prompting — name the exact node types, integrations, and tool descriptions you need. Paste onto a blank canvas with Ctrl+V and fix any invalid nodes n8n flags.
Why is my whole workflow broken even though individual nodes execute fine?
Executing individual nodes with 'Execute Step' doesn't catch inter-node data-passing bugs — the data shape one node outputs may not match what the next expects. Always run the complete workflow end-to-end before publishing. A node that works in isolation can still fail when receiving real upstream data in a full run.
// Comparisons
How does the Hugging Face Inference Model node compare to the OpenAI node router approach?
The native Hugging Face Inference Model node lets you paste a model ID directly but doesn't provide a searchable model list. The OpenAI Chat Model node with Base URL router.huggingface.co/v1 gives you a universal router that also works with Ollama, OpenRouter, and Cerebras by swapping the base URL. The OpenAI router approach is more flexible for switching providers later.
How does Firecrawl MCP compare to building a custom web-scraping node?
Firecrawl MCP gives your agent sophisticated internet capabilities — Google search, scraping, and crawling — with zero custom integration code; the MCP Client Tool node connects over streamable HTTP and the agent auto-discovers the tools. A custom scraping node requires you to handle search, parsing, rate limits, and error handling yourself. Use Firecrawl MCP unless you have a very specific scraping requirement.
How does n8n's built-in binary data loader compare to Unstructured for ingestion?
n8n's built-in binary Document Loader is fine for prototyping but struggles with tables, images, and unusual PDF layouts. Data extraction is one of the hardest parts of the ETL pipeline. For production, prefer specialised extraction products like Unstructured, which also support structure-aware chunking. The built-in loader with Simple character splitting is a demo-grade baseline only.
// Advanced
When should I use a webhook trigger versus a chat trigger for retrieval?
Use the 'Chat Message Received' trigger when you want a built-in chat UI with a public chat URL — ideal for human users. Use the 'Webhook' trigger (POST endpoint) for programmatic access, such as a CRM or another system calling your agent and receiving a structured response. Add authentication to either if the endpoint is internet-accessible.
How do I let the agent cite page numbers and sources?
Enable 'include metadata' on the Knowledge Base Search (Vector Store Query) tool node. This passes chunk metadata — like page numbers and source filenames — back to the agent alongside the retrieved text. You can then instruct the agent in its system prompt to cite these sources in its answers, giving users verifiable references.
Can I switch inference providers to lower latency or cost?
Yes. Because you're using the OpenAI Chat Model node as a universal router, you can swap the Base URL and API key to point at Cerebras (fast), OpenRouter (broad model access), Ollama (self-hosted), or different Hugging Face providers (Novita, etc.). Check pricing via 'compare providers' on the model page. You can also add custom headers, like a billing org header.
Can one agent use both a document search tool and live web search?
Yes — this is a core strength of Agentic RAG. Attach both the Knowledge Base Search tool and the Firecrawl MCP Client Tool to the same AI Agent. Write a system prompt that names both and gives selection heuristics. The agent decides autonomously whether a question needs internal documents, live web research, or both — and can call each multiple times before answering.
How do I migrate an existing Manual RAG workflow to Agentic RAG?
Replace the hard-coded pipeline (query rewrite → search → re-rank → prompt) with an AI Agent node. Convert your vector search step into a Vector Store Query node set to 'Retrieve Documents (for Agent)' and attach it as a tool with a clear description. Let the agent handle query rewriting implicitly. Keep the same embedding model and vector store so existing embeddings remain valid.
What's the recommended chunk size and result limit for good retrieval?
Start with a result limit of 4 retrieved chunks as a reasonable default on the Knowledge Base Search tool. For chunk size, use Simple character-count splitting only for prototyping; move to semantic or structure-aware splitting for production so related information stays together. Tune both by inspecting whether the agent gets complete, coherent context in your test queries.