> For the complete documentation index, see [llms.txt](https://docs.snackprompt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snackprompt.com/bring-your-data-into-ai/how-to/get-started-with-integrations/how-to-integrate-with-flowise.md).
# How to Integrate with Flowise
Learn how to use the SnackPrompt AI Engine API as an external knowledge source in Flowise chatbots and AI workflows.
### Overview
Flowise is a visual tool for building LLM applications. It offers several ways to integrate external APIs:
| Method | Use Case | Description |
| --------------------- | -------------------- | ---------------------------------------------- |
| **Custom Tool** | Agent with tools | Agent decides when to query the API |
| **HTTP Request Node** | Direct RAG | Call API at specific point in the flow |
| **Custom Retriever** | Replace vector store | Use external API instead of built-in retriever |
| **API Chain** | Sequential calls | Chain multiple API calls together |
### Integration Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Flowise │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Chat │───▶│ LLM Chain │───▶│ Response │ │
│ │ Input │ │ or Agent │ │ │ │
│ └─────────────┘ └──────┬──────┘ └────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Custom Tool │ │
│ │ or Chain │ │
│ └──────┬──────┘ │
└────────────────────────────┼────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ SnackPrompt AI Engine API │
│ /v1/kb/search or /v1/kb/chat│
└──────────────────────────────┘
```
***
### Method 1: Custom Tool (Recommended for Agents)
Use when you want the **agent to autonomously decide** when to search your knowledge base.
#### Step 1: Create a Custom Tool
1. In Flowise, go to **Tools** in the sidebar
2. Click **Add New**
3. Configure the tool:
**Tool Configuration:**
| Field | Value |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | `search_knowledge_base` |
| Description | `Use this tool to search for information in the company knowledge base. Send a natural language query to find relevant documents about products, policies, procedures, etc. Returns relevant text snippets.` |
#### Step 2: Configure the Tool Code
```javascript
const fetch = require('node-fetch');
const searchKnowledgeBase = async (query) => {
const response = await fetch('https://api-integrations.snackprompt.com/v1/kb/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.SNACKPROMPT_API_KEY
},
body: JSON.stringify({
query: query,
filters: {
tenant_id: process.env.SNACKPROMPT_TENANT_ID
},
limit: 5
})
});
const data = await response.json();
if (!data.items || data.items.length === 0) {
return 'No relevant information found in the knowledge base.';
}
return data.items
.map((item, index) => `[${index + 1}] ${item.payload.original_text}`)
.join('\n\n');
};
module.exports = { searchKnowledgeBase };
```
#### Step 3: Build the Agent Flow
1. Add **Chat Trigger** node
2. Add **Tool Agent** or **OpenAI Function Agent** node
3. Connect your **Custom Tool**
4. Add **Chat Model** (OpenAI, Anthropic, etc.)
```
[Chat Trigger] → [Tool Agent] → [Response]
│
├── [Chat Model: GPT-4]
└── [Custom Tool: search_knowledge_base]
```
***
### Method 2: HTTP Request Chain
Use when you want a **deterministic flow** where the search always happens.
#### Step 1: Create the Flow
1. Add **Chat Trigger** node
2. Add **HTTP Request** node
3. Add **LLM Chain** node for response generation
#### Step 2: Configure HTTP Request Node
**Request Configuration:**
**Headers:**
```json
{
"Content-Type": "application/json",
"x-api-key": "{{$env.SNACKPROMPT_API_KEY}}"
}
```
**Body:**
```json
{
"query": "{{$input}}",
"filters": {
"tenant_id": "{{$env.SNACKPROMPT_TENANT_ID}}"
},
"limit": 5
}
```
#### Step 3: Process and Format Results
Add a **JavaScript Function** node to format the results:
```javascript
function formatResults(data) {
if (!data.items || data.items.length === 0) {
return 'No relevant information found.';
}
return data.items
.map((item, index) => `[${index + 1}] ${item.payload.original_text}`)
.join('\n\n');
}
return formatResults($input);
```
#### Step 4: Generate Response with LLM
Add **LLM Chain** with prompt:
```
You are a helpful assistant. Answer the user's question based ONLY on the following context.
Context:
{context}
User Question: {question}
If the context doesn't contain relevant information, say "I don't have information about that."
```
***
### Method 3: Chat Endpoint for Complete Responses
Use the `/v1/kb/chat` endpoint when you want the **API to handle all the RAG**.
#### Simple Chatbot Flow
```
[Chat Trigger] → [HTTP Request: /chat] → [Parse Response] → [Output]
```
#### HTTP Request Configuration
**Headers:**
```json
{
"Content-Type": "application/json",
"x-api-key": "{{$env.SNACKPROMPT_API_KEY}}"
}
```
**Body:**
```json
{
"query": "{{$input}}",
"filters": {
"tenant_id": "{{$env.SNACKPROMPT_TENANT_ID}}",
"tag_names": ["Support", "FAQ"]
}
}
```
#### Parse Response
Extract the `answer` field from the response:
```javascript
return $input.answer;
```
***
### Method 4: Custom Retriever Node
For advanced users who want to replace Flowise's built-in retrievers.
#### Step 1: Create Custom Retriever
Create a custom node that implements the retriever interface:
```javascript
const { BaseRetriever } = require('langchain/schema/retriever');
const { Document } = require('langchain/document');
class SnackPromptRetriever extends BaseRetriever {
constructor(config) {
super();
this.apiKey = config.apiKey;
this.tenantId = config.tenantId;
this.limit = config.limit || 5;
this.tagNames = config.tagNames || [];
}
async getRelevantDocuments(query) {
const response = await fetch('https://api-integrations.snackprompt.com/v1/kb/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': this.apiKey
},
body: JSON.stringify({
query: query,
filters: {
tenant_id: this.tenantId,
tag_names: this.tagNames
},
limit: this.limit
})
});
const data = await response.json();
return data.items.map(item => new Document({
pageContent: item.payload.original_text,
metadata: {
id: item.payload.snack_item_id,
score: item.score
}
}));
}
}
module.exports = { SnackPromptRetriever };
```
#### Step 2: Use in Conversational Retrieval Chain
Connect your custom retriever to a **Conversational Retrieval QA Chain**:
```
[Chat Trigger] → [Conversational Retrieval QA Chain] → [Response]
│
├── [Chat Model]
├── [Custom Retriever: SnackPrompt]
└── [Memory]
```
***
### Practical Use Cases
#### 1. Simple Support Chatbot
```
[Chat Trigger] → [HTTP: /chat] → [Response]
```
Direct integration for simple Q\&A chatbots.
#### 2. Agent with Multiple Tools
```
[Chat Trigger] → [Tool Agent] → [Response]
│
├── [Tool: search_knowledge_base]
├── [Tool: search_products]
└── [Tool: calculator]
```
Agent that can search different knowledge bases and perform calculations.
#### 3. RAG with Memory
```
[Chat Trigger] → [Conversational Retrieval Chain] → [Response]
│
├── [Custom Retriever]
└── [Buffer Memory]
```
Chatbot that remembers conversation history while retrieving from knowledge base.
#### 4. Multi-Source RAG
```
[Chat Trigger] → [Router] → [Merge] → [LLM Chain] → [Response]
│
├── [HTTP: tag=Sales]
└── [HTTP: tag=Support]
```
Search multiple knowledge bases and combine results.
#### 5. Hybrid Search
```
[Chat Trigger] → [Parallel]
│
├── [HTTP: SnackPrompt Search]
└── [Vector Store: Local]
│
▼
[Merge Results] → [LLM Chain] → [Response]
```
Combine external API results with local vector store.
***
### Environment Variables
Set these in your Flowise deployment:
| Variable | Description |
| ----------------------- | ------------------------ |
| `SNACKPROMPT_API_KEY` | Your SnackPrompt API key |
| `SNACKPROMPT_TENANT_ID` | Your tenant ID |
#### Setting Environment Variables
**Docker:**
```yaml
environment:
- SNACKPROMPT_API_KEY=your_api_key
- SNACKPROMPT_TENANT_ID=your_tenant_id
```
**Local:**
```bash
export SNACKPROMPT_API_KEY=your_api_key
export SNACKPROMPT_TENANT_ID=your_tenant_id
```
***
### Configuration Tips
#### 1. Tool Description is Critical
For agents, the tool description determines when it's used:
```
✅ Good description:
"Search the company knowledge base for information about products,
pricing, policies, and procedures. Use when the user asks about
company-specific information that requires factual answers."
❌ Bad description:
"Search API"
```
#### 2. Limit Results
Too many results can confuse the LLM:
```javascript
{
"limit": 3 // Start small, increase if needed
}
```
#### 3. Use Filters
Filter by tags when you know the context:
```javascript
{
"filters": {
"tenant_id": "...",
"tag_names": ["FAQ", "Products"]
}
}
```
#### 4. Handle Errors
Add error handling in your JavaScript nodes:
```javascript
try {
const response = await fetch(url, options);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('Search failed:', error);
return { items: [], error: error.message };
}
```
#### 5. Cache Responses
For frequently asked questions, consider caching:
```javascript
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
async function cachedSearch(query) {
const cacheKey = query.toLowerCase().trim();
const cached = cache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const data = await searchKnowledgeBase(query);
cache.set(cacheKey, { data, timestamp: Date.now() });
return data;
}
```
***
### Complete Example: Customer Support Bot
#### Flow Structure
1. **Chat Trigger**: Receives user message
2. **Tool Agent**: Processes with GPT-4
3. **Custom Tools**: Search knowledge base
4. **Response**: Returns answer with sources
#### Agent System Prompt
```
You are a helpful customer support assistant for Company X.
Your capabilities:
- Search the knowledge base for product information, policies, and FAQs
- Provide accurate answers based on the retrieved information
- Cite sources when providing information
Guidelines:
- Always search the knowledge base before answering product-related questions
- If you can't find relevant information, say so honestly
- Be concise but thorough in your responses
- Format responses with bullet points when listing multiple items
```
#### Tool Configuration
| Tool | Name | Description |
| --------------- | ----------------- | --------------------------------------------------- |
| Search | `search_kb` | Search for product info, policies, and FAQs |
| Search Products | `search_products` | Search specifically for product details and pricing |
***
### Troubleshooting
#### Error: "tenant\_id is required"
Ensure `tenant_id` is inside the `filters` object:
```javascript
// ❌ Wrong
{ "query": "...", "tenant_id": "..." }
// ✅ Correct
{ "query": "...", "filters": { "tenant_id": "..." } }
```
#### Agent doesn't use the tool
1. Improve the tool description
2. Add examples in the system prompt
3. Test with explicit queries like "search for..."
#### Empty results
1. Verify environment variables are set
2. Check tenant\_id is correct
3. Remove tag filters to search all content
4. Test the API directly with curl
#### Timeout errors
1. Increase timeout in HTTP Request node
2. Reduce the `limit` parameter
3. Check network connectivity
***
### Related
* [Endpoints Reference](/bring-your-data-into-ai/reference/endpoints.md)
* [Available Filters](/bring-your-data-into-ai/reference/filters.md)
* [Error Hand](/bring-your-data-into-ai/how-to/how-to-handle-errors.md)
### External Resources
* [Flowise Documentation](https://docs.flowiseai.com/)
* [Flowise GitHub](https://github.com/FlowiseAI/Flowise)
* [LangChain Custom Retrievers](https://js.langchain.com/docs/modules/data_connection/retrievers/)
* [Building Custom Tools in Flowise](https://docs.flowiseai.com/tools/custom-tool)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.snackprompt.com/bring-your-data-into-ai/how-to/get-started-with-integrations/how-to-integrate-with-flowise.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.