Anatomy of a workflow agent

Every recipe in this section follows the same five-step pattern. Read this page once and the recipes themselves become short. Come back here whenever you need a refresher on an individual step.

1. Find a workflow

Agents are built on workflows. A workflow encodes the conversation logic — branching, handoff rules, and system prompt configuration. Before you create an agent you pick the workflow it will run, either one you have built yourself (scope: "owned") or one from the public library (scope: "public").

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

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

// Search the public library for a restaurant workflow
const page = await bimpe.workflows.list({ scope: "public", search: "restaurant" });
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"])

# Search the public library for a restaurant workflow
page = client.workflows.list(scope="public", search="restaurant")
workflow = page.data[0]
print(workflow.id, workflow.name)

scope accepts "owned" or "public". The returned WorkflowSummary objects carry id, name, description, tags, and timestamps. Retrieve the full Workflow — which adds system_prompt, rules, flows, and prompt_config — with workflows.retrieve(id).

2. Create an agent

With a workflow id in hand, create the agent. Only name is required; agent_workflow_id wires the workflow. You can also supply a system_prompt, description, persona, language, rules, and timezone at create time or update them later.

const agent = await bimpe.agents.create(
  {
    name: "Restaurant assistant",
    system_prompt: "You help customers place orders and book tables.",
    agent_workflow_id: workflow.id,
  },
  { idempotencyKey: "create-restaurant-agent-v1" },
);

console.log(agent.id);

agent = client.agents.create(
    name="Restaurant assistant",
    system_prompt="You help customers place orders and book tables.",
    agent_workflow_id=workflow.id,
    idempotency_key="create-restaurant-agent-v1",
)

print(agent.id)

Pass an idempotencyKey / idempotency_key so that a retried create cannot produce a duplicate agent.

3. Add a knowledge base

Knowledge bases give the agent grounded information — your menu, your policy doc, a help article. Each entry is either a text source (inline content) or a url source (the SDK fetches and indexes the page).

// Inline text
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Menu",
  content: "Margherita pizza £12. Pasta Arrabbiata £10. Tiramisu £6.",
});

// URL source
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "url",
  name: "Booking policy",
  url: "https://example.com/booking-policy",
});

# Inline text
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Menu",
    "content": "Margherita pizza £12. Pasta Arrabbiata £10. Tiramisu £6.",
})

# URL source
client.agents.knowledge_bases.create(agent.id, {
    "type": "url",
    "name": "Booking policy",
    "url": "https://example.com/booking-policy",
})

Knowledge bases support full CRUD (list, create, update, delete). The agent picks them up immediately after creation.

4. Inspect read-only sub-resources

Several sub-resources on an agent are read-only through the API. You can list them to understand what is connected, but you configure the underlying connections in the Console dashboard.

const integrations = await bimpe.agents.integrations.list(agent.id);
const channels = await bimpe.agents.channels.list(agent.id);
const flows = await bimpe.agents.conversationFlows.list(agent.id);
const actions = await bimpe.agents.actions.list(agent.id);

console.log("Channels:", channels.map((c) => c.type));

integrations = client.agents.integrations.list(agent.id)
channels = client.agents.channels.list(agent.id)
flows = client.agents.conversation_flows.list(agent.id)
actions = client.agents.actions.list(agent.id)

print("Channels:", [c.type for c in channels])

API boundary: what the API can and cannot do

Integrations and channels are read-only in the Console API. You connect a channel (WhatsApp, Messenger, Instagram, web chat) and purchase or connect a voice phone number in the Console dashboard. The API lets you list what is already connected; it cannot create or remove channel connections.

When filtering conversations by channel, the accepted values are whatsapp, messenger, instagram, and webchat, plus the test_* variant of each (e.g. test_whatsapp). There is no voice value in the channel filter enum — voice conversations are not surfaced through the conversations endpoint.

5. Converse

Once an agent is live and channels are connected, conversations flow in automatically. You can send a message into an existing conversation from your server, or stream all new messages in real time.

// Send a message into a conversation
const sent = await bimpe.conversations.messages.send(agent.id, conversationId, {
  message: "Your table for two is confirmed for 7 pm tonight.",
});

// Stream new messages in real time
const controller = new AbortController();

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

# Send a message into a conversation
sent = client.conversations.messages.send(
    agent.id, conversation_id, message="Your table for two is confirmed for 7 pm tonight."
)

# Stream new messages in real time
for event in client.conversations.messages.stream(agent.id, conversation_id):
    print(event.role, event.message)

The stream runs over Server-Sent Events. The SDK handles the ticket exchange, reconnects on dropped connections, and resumes from the last delivered message id — you never miss a message or see one twice. Break out of the loop (or abort the signal in TypeScript) to stop.

Every recipe in the Use cases section links back to this page and assumes you have read it. The recipes themselves focus on the domain-specific details: which workflow to pick, what goes in the knowledge base, and how the conversation flow is structured for that particular scenario.