Product Recommendation Agent

Deliver personalised product suggestions through web chat or WhatsApp by grounding the agent in your product catalogue knowledge base.

DifficultyIntermediate

TrackDeveloper Track

ChannelsWeb ChatWhatsApp

IntegrationsProduct catalogue (knowledge base)CRM (optional)

What you'll build

An agent that learns what a customer is looking for and surfaces relevant products from your catalogue, with optional CRM context to personalise suggestions based on purchase history.

Prerequisites

BimpeAI account with an API key (sk_…)
Read Anatomy of a workflow agent first — this recipe skips steps covered there
A product catalogue accessible as a URL or structured text
(Optional) CRM integration connected in the Console dashboard

Steps

1. Find the workflow

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

const page = await bimpe.workflows.list({ scope: "public", search: "product recommendation" });
const workflow = page.data[0];
console.log(workflow.id, workflow.name);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

page = client.workflows.list(scope="public", search="product recommendation")
workflow = page.data[0]
print(workflow.id, workflow.name)

2. Create the agent

const agent = await bimpe.agents.create(
  {
    name: "Product recommender",
    system_prompt:
      "You help customers discover products that match their needs. " +
      "Ask one or two clarifying questions about use case, budget, and preferences " +
      "before surfacing recommendations. Always explain why each product fits.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-recommender-agent-v1" },
);

console.log(agent.id);

agent = client.agents.create(
    name="Product recommender",
    system_prompt=(
        "You help customers discover products that match their needs. "
        "Ask one or two clarifying questions about use case, budget, and preferences "
        "before surfacing recommendations. Always explain why each product fits."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-recommender-agent-v1",
)

print(agent.id)

Index your product catalogue. A url source is ideal if your catalogue is kept up to date at a stable endpoint; use text for a static export. Add a second entry for recommendation rules so the agent applies consistent logic.

// Live catalogue
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "url",
  name: "Product catalogue",
  url: "https://example.com/catalogue.json",
});

// Recommendation rules
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Recommendation rules",
  content:
    "Always surface 2-3 options across different price points.\n" +
    "Highlight the best-value option.\n" +
    "Do not recommend items marked Out of stock.\n" +
    "If budget is under £50, focus on the budget range first.",
});

# Live catalogue
client.agents.knowledge_bases.create(agent.id, {
    "type": "url",
    "name": "Product catalogue",
    "url": "https://example.com/catalogue.json",
})

# Recommendation rules
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Recommendation rules",
    "content": (
        "Always surface 2-3 options across different price points.\n"
        "Highlight the best-value option.\n"
        "Do not recommend items marked Out of stock.\n"
        "If budget is under £50, focus on the budget range first."
    ),
})

4. Connect channels and integrations (dashboard)

Channels and integrations are dashboard-only

The API cannot create channel connections or integrations. Connect them in the Console dashboard. The SDK lists what is already active, which is useful for verifying setup before going live.

Open Console dashboard → Agents → select your agent.
Under Channels, enable the web chat widget and copy the embed snippet for your storefront.
Under Channels, connect your WhatsApp Business number.
(Optional) Under Integrations, connect your CRM so the agent can personalise based on purchase history.

5. Verify conversation flows and go live

List conversation flows and channels to confirm setup before directing traffic to the agent.

const flows = await bimpe.agents.conversationFlows.list(agent.id);
const channels = await bimpe.agents.channels.list(agent.id);
console.log("Flows:", flows.map((f) => f.name));
console.log("Channels:", channels.map((c) => c.type));

flows = client.agents.conversation_flows.list(agent.id)
channels = client.agents.channels.list(agent.id)
print("Flows:", [f.name for f in flows])
print("Channels:", [c.type for c in channels])

Full example

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

// 1. Find workflow
const page = await bimpe.workflows.list({ scope: "public", search: "product recommendation" });
const workflow = page.data[0];

// 2. Create agent
const agent = await bimpe.agents.create(
  {
    name: "Product recommender",
    system_prompt:
      "You help customers discover products that match their needs. " +
      "Ask one or two clarifying questions before surfacing recommendations.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-recommender-agent-v1" },
);

// 3. Add catalogue and rules knowledge bases
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "url",
  name: "Product catalogue",
  url: "https://example.com/catalogue.json",
});

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Recommendation rules",
  content:
    "Always surface 2-3 options across different price points.\n" +
    "Highlight the best-value option.\n" +
    "Do not recommend items marked Out of stock.",
});

// 4. Verify connected resources (configured in the dashboard)
const flows = await bimpe.agents.conversationFlows.list(agent.id);
const channels = await bimpe.agents.channels.list(agent.id);
console.log("Agent ID:", agent.id);
console.log("Flows:", flows.map((f) => f.name));
console.log("Channels:", channels.map((c) => c.type));

// 5. Stream messages in an active conversation
const controller = new AbortController();

for await (const event of bimpe.conversations.messages.stream(
  agent.id,
  "<conversation_id>",
  { signal: controller.signal },
)) {
  console.log(event.role, event.message);
}

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

# 1. Find workflow
page = client.workflows.list(scope="public", search="product recommendation")
workflow = page.data[0]

# 2. Create agent
agent = client.agents.create(
    name="Product recommender",
    system_prompt=(
        "You help customers discover products that match their needs. "
        "Ask one or two clarifying questions before surfacing recommendations."
    ),
    agent_workflow_id=workflow.id,
    idempotency_key="create-recommender-agent-v1",
)

# 3. Add catalogue and rules knowledge bases
client.agents.knowledge_bases.create(agent.id, {
    "type": "url",
    "name": "Product catalogue",
    "url": "https://example.com/catalogue.json",
})

client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Recommendation rules",
    "content": (
        "Always surface 2-3 options across different price points.\n"
        "Highlight the best-value option.\n"
        "Do not recommend items marked Out of stock."
    ),
})

# 4. Verify connected resources (configured in the dashboard)
flows = client.agents.conversation_flows.list(agent.id)
channels = client.agents.channels.list(agent.id)
print("Agent ID:", agent.id)
print("Flows:", [f.name for f in flows])
print("Channels:", [c.type for c in channels])

# 5. Stream messages in an active conversation
for event in client.conversations.messages.stream(agent.id, "<conversation_id>"):
    print(event.role, event.message)

Deploy

Store your API key in BIMPEAI_API_KEY. After each catalogue update, call knowledgeBases.update or delete and recreate the catalogue entry so the agent reflects the latest inventory. Use a stable idempotencyKey to prevent duplicate agents on redeploy.

Variations

Add a seasonal knowledge base entry (e.g. "Summer picks 2026") and update it each season.
Restrict recommendations to a price range by adding the constraint to system_prompt (e.g. "Only recommend items under £100 unless the customer asks for premium options").
Connect a CRM integration in the dashboard to let the agent reference past orders and avoid repeating previous purchases.