> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# n8n integration guide
n8n is a no-/low-code workflow automation framework. This guide shows you how to connect [SambaCloud](https://cloud.sambanova.ai?utm_source=n8n\&utm_medium=external\&utm_campaign=cloud_signup) models to n8n through its OpenAI-compatible Chat Model node.
## Prerequisites
Before you begin, ensure you have:
* An n8n account, cloud or self-hosted, on a current release. The Advanced AI cluster nodes this guide uses have shipped since the 1.x line and n8n is now on 2.x, so any maintained version has them. If you self-host an older build, confirm **AI Agent** appears in the node search before going further
* A SambaCloud API key. Get one by creating a [SambaCloud](https://cloud.sambanova.ai?utm_source=n8n\&utm_medium=external\&utm_campaign=cloud_signup) account and generating a key from the API keys tab
The OpenAI Chat Model node is a sub-node – it can't run on its own. It must be attached to a root node such as **AI Agent** or **Basic LLM Chain**. This guide uses AI Agent.
## Open or create a workflow
Log in to the n8n platform and select the **+** button. Alternatively, select the **Create Workflow** button to start a new workflow.
## Add an AI Agent node
On the canvas, select **Add first step** or the **+** button, search for **AI Agent**, and add it. The AI Agent node is the root node that runs the model and any tools you attach. It appears on the canvas with empty connector slots underneath, one of which is **Chat Model**.
## Add the OpenAI Chat Model sub-node
Select the **+** on the AI Agent node's **Chat Model** connector and choose **OpenAI Chat Model**. SambaCloud is OpenAI-compatible, so this node works against it without a SambaNova-specific node.
## Configure your credentials
In the OpenAI Chat Model panel, open the **Credential to connect with** dropdown and select **Create new credential**. Enter your SambaCloud API key as the **API Key**, then set **Base URL** to `https://api.sambanova.ai/v1`.
The **Base URL** field is the part that is easy to miss. Leave it at its OpenAI default and every request goes to OpenAI with a SambaNova key, which fails on the first call rather than at save time.
Save the credential. n8n runs a connection test and shows **Connection tested successfully** when the key and Base URL are both accepted.
## Select a model
Click the **Model** dropdown. n8n populates it by calling `/models` on the Base URL you configured, so once the credential saves you see SambaCloud's current catalog.
| Your workflow | Model to pick |
| :- | :- |
| An agent that calls tools, which is most AI Agent workflows | `Meta-Llama-3.3-70B-Instruct` |
| Reads images, and attaches no tools | `gemma-4-31B-it` |
These two needs cannot be met by one model today. AI Agent drives tools through function calling, and `gemma-4-31B-it` is not listed under [Function calling](/docs/en/features/function-calling), so an agent on gemma with tools attached answers from the model alone and never calls them. Nothing in the n8n execution log reports this, so it reads as the agent ignoring your tools. Pick `gemma-4-31B-it` only for image input without tools.
The model IDs in the screenshot above are from an earlier catalog and several have since been retired. Trust the dropdown, which lists what SambaCloud serves right now, over the names in the image. You can check the same list yourself with `curl https://api.sambanova.ai/v1/models`, which needs no API key, or see [SambaCloud models](/docs/en/models/sambacloud-models).
If the dropdown is empty, see [Troubleshooting](#troubleshooting).
## Troubleshooting
This usually means the credential test succeeded but the `/models` call failed. Confirm the Base URL is exactly `https://api.sambanova.ai/v1` with no trailing slash issues, and that the API key is valid.
This was reported against n8n's standalone **OpenAI** node (v2, "Message a model") with a custom Base URL: the credential test passes because it and the runtime node do not build the same final URL. See [n8n-io/n8n#21651](https://github.com/n8n-io/n8n/issues/21651), filed against a different OpenAI-compatible provider and closed as completed on 2026-05-26, so a current n8n should not hit it.
If you do, check whether `/v1` ends up missing or duplicated in the final URL, and use the **OpenAI Chat Model** sub-node with AI Agent as this guide does, which was unaffected.
Two causes. Built-in tool calling with the OpenAI Chat Model node works only when it is connected to an **AI Agent** node, not a Basic LLM Chain. If you are already on AI Agent, check the model: tool calling needs a model listed under [Function calling](/docs/en/features/function-calling), and `gemma-4-31B-it` is not one of them, so an agent using it answers without ever calling your tools and logs no error.
Re-check the API key was copied without extra whitespace, and that it hasn't been revoked in the SambaCloud dashboard.
## Example: Household budgeting agent
For a concrete example, check out [this sample workflow](https://github.com/sambanova/integrations/tree/main/n8n) that builds a simple household budgeting agent. It can serve as a template for building more advanced agentic workflows using SambaCloud and n8n.