DEV Community: KaibanJS

Put Your Multi-Agent Pipeline on WhatsApp, Telegram, and Discord — With One HTTP Endpoint

Dariel Vila — Fri, 20 Mar 2026 19:27:36 +0000

TL;DR: If you already run a multi-agent system (or any custom agent stack), you don’t need a separate bot per channel. Implement **POST /v1/responses** in the OpenResponses shape, register it in OpenClaw as a custom provider, and your workflow answers users on every messaging surface OpenClaw supports. KaibanJS is a TypeScript/JavaScript framework for building those multi-agent workflows with explicit agents, tasks, and teams — and the repo ships a ready-made adapter in playground/openclaw-openresponses so your KaibanJS Team becomes an OpenClaw “model.” Swap the team definition; keep the HTTP contract.

The problem every agent builder hits

You ship something clever: a research → write → review pipeline, a RAG agent with tools, or a DAG of specialists. It works in Node or in your IDE. Then someone asks: “Can we talk to it on Telegram?”

Gateways like OpenClaw exist so you don’t reimplement webhooks, auth, rate limits, and message formatting for every platform. The catch is that those gateways usually assume one model call per turn. Your system is not that — it’s orchestration, state, and multiple steps.

The fix is not to fork OpenClaw. The fix is a thin adapter that speaks the same language the gateway already speaks.

What is KaibanJS?

KaibanJS is an open-source JavaScript/TypeScript framework for multi-agent systems. It takes inspiration from Kanban: you define agents (who does the work), tasks (what needs to happen, with descriptions and expected outputs), and a Team that wires tasks into a workflow — so orchestration stays explicit instead of hiding inside one giant prompt.

In practice you get:

Structured workflows — task graphs and handoffs between agents, not only a single chat completion.
Observable state — workflow status, logs, and stats (including LLM usage) you can use for UI, debugging, or mapping into APIs like OpenResponses.
Tools and LLMs — agents can use tools in a way that fits the broader JS ecosystem; teams can pass **env** (for example API keys) into the run.

You can explore the Kaiban Board playground (think Trello-style visibility for agents and tasks), skim the docs, or install from npm / GitHub. The OpenClaw integration does not require the browser board — it runs Node-side and calls Team.start() from your adapter.

OpenResponses: one contract, any backend

OpenResponses is an open API spec (aligned with the OpenAI Responses API) for:

Request bodies with input as a string or a structured message list
Optional **stream: true** and Server-Sent Events (SSE) for token-style delivery
Responses with an **output** array of assistant messages and **usage** metadata

OpenClaw treats a server that implements this as just another model provider. You point baseUrl at your adapter, set api: "openai-responses", and agents use providerId/modelId. No channel-specific code in your repo.

How the KaibanJS ↔ OpenClaw integration is built

The integration is intentionally two layers: (1) HTTP + OpenResponses in the adapter, (2) your Team in a separate module. OpenClaw never imports KaibanJS — it only sees REST.

1. Express server (`src/index.ts`)

A minimal Express app:

Parses JSON bodies (size-limited).
Exposes **GET /health** for probes.
Protects **POST /v1/responses** with optional Bearer auth: if KAIBAN_OPENRESPONSES_SECRET is set, the Authorization header must match; if empty, auth is skipped for local dev.

All OpenResponses logic lives in **handleOpenResponses** from adapter.ts.

2. From HTTP request to `Team.start()`

Inside **handleOpenResponses** the pipeline is:

**normalizeBody(req.body)** — OpenClaw may wrap the spec payload in a top-level **body** property; the adapter unwraps it so the rest of the code always sees a normal OpenResponses object.
**extractUserMessage(body)** — Reads input: either a string or an array of message items. For arrays, it uses the last user message and concatenates text from content parts (aligned with the OpenResponses input model).
**createTeam({ topic: userMessage })** — Builds a fresh Team instance per request (see below). The user’s text is passed as the **topic** input, which flows into task descriptions via {topic} placeholders.
**await team.start({ inputs: { topic: userMessage } })** — Runs the full KaibanJS workflow and returns a **workflowResult** with status, **result, and optional `stats* (e.g. llmUsageStats*` for token counts).

If there is no usable user message, the adapter responds with 400 and an invalid_request_error payload — same spirit as other OpenResponses providers.

3. Mapping KaibanJS results to OpenResponses

Success (JSON) — Builds a response with object: "response", status: "completed", an **output** array containing one assistant message whose content is **output_text. The text comes from `resultToText*: if the workflow result is an object with a result field, that value is used; otherwise the value is stringified. usage is filled from workflowResult.stats.llmUsageStats*` when present.
Blocked workflow — If **workflowResult.status === "BLOCKED", the adapter returns **422 with type: "workflow_blocked". The message is resolved via **extractWorkflowErrorMessage(team), which walks `workflowLogs**` on the team store so operators see something actionable, not a generic failure string.
Throws / errored runs — 500 JSON (or **response.failed** on SSE if headers were already sent), again preferring log-derived messages when available.

So OpenClaw still thinks it called a “model,” but under the hood it triggered a multi-step KaibanJS pipeline with proper status and usage metadata.

4. Streaming path

When the client sends **stream: true, the adapter sets **SSE headers, then emits the OpenResponses event sequence: response.created → response.in_progress (while the team runs) → response.output_item.added → response.content_part.added → response.output_text.delta / done → response.content_part.done → response.output_item.done → response.completed, then **[DONE]**.

During execution it subscribes to team changes with **team.subscribeToChanges(..., ['teamWorkflowStatus'])** so clients get **response.in_progress** updates while the workflow moves. After **team.start()** resolves, the final text is sent as deltas/done events (the reference implementation can emit the full text as a single delta — still spec-shaped and easy for OpenClaw to forward).

5. Swappable team (`src/team/index.ts`)

The default Content Creation Team is a straight line: ResearchBot → WriterBot → ReviewBot, each bound to a **Task** that references {topic} in its description. The **Team** is created with **inputs: { topic }** and **env** (e.g. **OPENAI_API_KEY**) for the LLM provider.

Replacing the team means editing only this factory (or pointing createTeam at another module). The adapter’s OpenResponses contract and OpenClaw **models.providers** config stay the same — that separation is the main maintainability win.

Important: This stack is server-side only (secrets, long-running orchestration, Node APIs). Official step-by-step (env vars, troubleshooting, curl examples): OpenClaw Integration via OpenResponses API | KaibanJS.

What the playground repo layout looks like

Path: **playground/openclaw-openresponses**

Piece	Role
`src/index.ts`	Express app, CORS, JSON, `/health`, Bearer auth, `POST /v1/responses`
`src/adapter.ts`	`handleOpenResponses`: normalize → extract message → `team.start` → JSON or SSE
`src/sse.ts`	Helpers to write SSE events and `[DONE]`
`src/team/index.ts`	`createTeam({ topic })` — swap this for your own KaibanJS workflow

Architecture in one glance

User (WhatsApp / Telegram / Discord / …)
  → OpenClaw gateway
  → POST https://your-adapter/v1/responses  (Bearer secret)
  → Your handler: normalize → extract message → run pipeline
  → OpenResponses JSON or SSE
  → OpenClaw → user

Your only long-lived integration surface with OpenClaw is that HTTP contract. Everything else — LangGraph, CrewAI, custom code, or KaibanJS — stays behind the adapter.

Run the playground locally

Prerequisites: Node.js 18+, an **OPENAI_API_KEY** (the default team uses OpenAI), and optionally OpenClaw already running for end-to-end tests.

cd playground/openclaw-openresponses
cp .env.example .env
# Set PORT, KAIBAN_OPENRESPONSES_SECRET, OPENAI_API_KEY
npm install
npm run dev

Defaults: server on http://localhost:3100, responses at POST /v1/responses.

Smoke-test without streaming:

curl -s -X POST http://localhost:3100/v1/responses \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"model":"kaiban","input":"Write a short paragraph about TypeScript."}'

With streaming:

curl -N -X POST http://localhost:3100/v1/responses \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"model":"kaiban","stream":true,"input":"One sentence about AI."}'

If KAIBAN_OPENRESPONSES_SECRET is empty, the playground skips auth — fine for local hacking, not for anything exposed to a network.

If you reimplement the adapter elsewhere

The previous section covers how this repo does it end-to-end. For any language or stack, keep the same invariants:

Unwrap a top-level **body** wrapper when the gateway sends one.
Accept **input** as a string or a message array; derive a single “user turn” text (or a structured object if you extend the contract deliberately).
Always return a sensible **usage** object (zeros are fine) so clients stay happy.
Map blocked workflows to 422 / workflow_blocked and unexpected failures to 500 / workflow_error; in SSE mode, emit **response.failed** before **[DONE]** when things go wrong after the stream started.

For KaibanJS specifically, aligning **extractUserMessage** with your **Team inputs** (today: **topic**) is the one place HTTP meets orchestration — keep them in sync when you rename or split inputs.

Wire it into OpenClaw

Config lives in **~/.openclaw/openclaw.json** (JSON5 is supported).

Rule that trips people up: do not put provider, endpoint, or auth inside agents.list. The backend is defined only under **models.providers; agents reference `providerId/modelId**`.

Register the provider

{
  models: {
    mode: "merge",
    providers: {
      "kaiban-adapter": {
        baseUrl: "http://localhost:3100/v1",
        apiKey: "${KAIBAN_OPENRESPONSES_SECRET}",
        api: "openai-responses",
        models: [
          {
            id: "kaiban",
            name: "KaibanJS Team",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

**baseUrl must include /v1** — OpenClaw appends /responses.
**apiKey** must match **KAIBAN_OPENRESPONSES_SECRET** on the adapter.

Point an agent at the model

{
  agents: {
    list: [
      {
        id: "kaiban-team",
        default: true,
        model: "kaiban-adapter/kaiban",
      },
    ],
    defaults: {
      model: { primary: "kaiban-adapter/kaiban" },
      timeoutSeconds: 600,
    },
  },
}

Multi-agent runs are slow compared to a single completion. Bump timeoutSeconds (300–600s is a sensible range) so OpenClaw doesn’t cancel mid-pipeline.

After edits, restart the OpenClaw daemon so channel integrations pick up the new provider — don’t assume hot reload for Telegram/WhatsApp/Discord.

Swapping the “model” for your own system

The pattern generalizes beyond KaibanJS:

HTTP server with POST /v1/responses (+ optional Bearer auth).
Parse OpenResponses input (and the OpenClaw body wrapper if present).
Run your stack — one function call, one job queue message, whatever fits.
Return OpenResponses JSON; optionally implement SSE for streaming.
Map errors to status codes your operators can grep (e.g. validation vs internal failure).

The KaibanJS playground is one reference implementation: replace src/team/index.ts with another createTeam (or call a different service from handleOpenResponses) and you keep OpenClaw config unchanged.

Security and ops (the boring stuff that matters)

Don’t expose the adapter to the public internet without hardening — treat it like a high-privilege endpoint that runs your full pipeline per request.
Generate a strong secret (openssl rand -base64 32) and set it in both the adapter env and OpenClaw’s provider apiKey.
Verify with curl against /v1/responses before debugging Telegram timeouts — isolates “adapter vs gateway vs channel”.

Summary

KaibanJS gives you explicit multi-agent workflows in TypeScript/JavaScript — agents, tasks, teams, observable runs — so a “reply” to a user can be the outcome of a whole pipeline, not one completion.
OpenClaw gives you reach across messaging channels without per-platform bots.
OpenResponses gives you a stable HTTP contract so the gateway treats your adapter like any other provider.
**playground/openclaw-openresponses** is the reference glue: Express + **handleOpenResponses** maps OpenClaw’s requests to **Team.start()**, maps **workflowResult** and workflow logs back to JSON/SSE, and keeps your team definition in one swappable file.

If you’re building agentic backends in JavaScript/TypeScript, this is a practical path: one HTTP surface to OpenClaw, KaibanJS for orchestration and observability inside your process.

Further reading

KaibanJS · Documentation · GitHub · npm
OpenClaw Integration via OpenResponses API (KaibanJS docs)
Integrate Any Agent Backend with OpenClaw (Hugging Face — pattern + motivation)
Playground README in-repo: playground/openclaw-openresponses/README.md

Cross-posting tip for dev.to: after publishing, add a canonical URL in front matter if you mirror this on your blog; use #discuss or #watercooler only if you want conversation rather than a straight tutorial.

Building a Multi-Agent Baggage Compensation Bot with KaibanJS,A2A, MCP, and Tavily

Dariel Vila — Fri, 27 Feb 2026 02:04:29 +0000

TL;DR — We built an AI pipeline that turns a baggage damage claim (plain text) into a policy-backed compensation offer. It uses KaibanJS (multi-agent orchestration), Kaiban MCP (card lifecycle as tools), Tavily (real-time product prices), and A2A (platform → agent triggers). Everything is TypeScript, tool-calling based, and runs from a single repo. Here’s the stack, the flow, and how to run it.

What we’re building

A multi-agent system that:

Receives a “card” from the Kaiban platform (description = claim text).
Extracts and validates the claim (passenger, items, damage).
Calculates compensation using airline policy (mock), historical payouts (mock), and real-time market prices via Tavily (up to 5 items).
Writes the offer back to the card and moves it to done (or blocked on error).

All platform interaction happens through MCP tools — no Kaiban SDK in the agent code. That makes the agent a pure “tool-calling” pipeline and keeps the same pattern you’d use for any LLM + tools setup.

Tech stack

Layer	Tech
Runtime	Node.js
Language	TypeScript
Multi-agent	KaibanJS (open-source)
Platform integration	Kaiban MCP (Streamable HTTP), A2A
LLM	OpenAI (via KaibanJS)
Real-time data	Tavily (product price search)
Validation / schemas	Zod

High-level flow

Kaiban board: card created (description = claim text) in column "todo"
       │
       ▼  A2A request to your endpoint
Executor: parse activity → get_card (MCP) → validate (has description, column = todo)
       │
       ▼  Start KaibanJS team with card_id, board_id, team_id, agent_id
Task 0  →  get_card, move_card to "doing", return claim text (userMessage)
Task 1  →  Extract & validate claim (passenger, items, damage)
Task 2  →  get_airline_policy + get_historical_payouts + search_product_market_price (Tavily × up to 5)
           → apply depreciation & caps → compensation amount + breakdown
Task 3  →  Generate offer text (or "please provide X")
Task 4  →  update_card (result = offer), move_card to "done", create_card_activities
       │
       ▼  On any error: move_card to "blocked", create_card_activities (audit)

The executor is a thin A2A handler: it receives the webhook, validates the card via MCP, runs the team, and on failure moves the card to blocked via MCP so nothing gets lost.

Why MCP instead of the Kaiban SDK?

We use the Kaiban MCP server so that agents never touch the Kaiban SDK. All they see are tools: get_card, move_card, update_card, create_card_activities. Benefits for devs:

One mental model — Same “LLM calls tools” pattern for both platform (Kaiban) and data (Tavily). No mixing SDK calls and tool calls in agent code.
Schema from the server — MCP exposes JSON Schema for each tool; we convert to Zod so KaibanJS (and the LLM) get correct parameter definitions and fewer bad tool calls.
Protocol, not vendor lock-in — MCP is an open protocol. Your agent code doesn’t depend on @kaiban/sdk; it just depends on “something that exposes these tools.”

If you prefer a controller-driven style where your app code uses the Kaiban SDK and the “agent” only does domain logic, the platform supports that too (see other kaiban-agents-starter examples). For this example we wanted to show a fully tool-based integration.

Code highlights

1. MCP client: Streamable HTTP + Zod

We use @modelcontextprotocol/sdk with Streamable HTTP and turn each MCP tool into a KaibanJS-compatible tool with a Zod schema:

// kaiban-mcp-client.ts (simplified)
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { convertJsonSchemaToZod } from 'zod-from-json-schema';

export async function getKaibanTools(): Promise<KaibanJSTool[]> {
  const client = await getMcpClient();
  const { tools: mcpTools } = await client.listTools();
  return mcpTools.map((t) => {
    const schema = inputSchemaToZod(t.inputSchema, t.name);
    return {
      name: t.name,
      description: t.description ?? `MCP tool: ${t.name}`,
      schema,
      async invoke(input: Record<string, unknown>): Promise<string> {
        const result = await client.callTool({ name: t.name, arguments: input });
        return stringifyToolContent(result.content);
      },
    };
  });
}

getMcpClient() builds the transport with KAIBAN_MCP_URL and Authorization: Bearer KAIBAN_API_TOKEN. The important bit: JSON Schema → Zod so the LLM gets proper tool schemas and we avoid vague or wrong arguments.

2. Tavily as a tool (real-time prices)

The Compensation Calculation Agent has three tools. Two are mocks (policy, historical payouts); the third is Tavily for real product prices:

// One call per product; agent is instructed to use max 5 per claim
const searchProductMarketPriceTool = new DynamicStructuredTool({
  name: 'search_product_market_price',
  description:
    'Searches for current market price of a product in USD. Call once per product; use for up to 5 products per claim.',
  schema: z.object({
    productName: z.string().describe('e.g. "Samsonite 28 inch spinner luggage"'),
  }),
  func: async (input) => {
    const client = await getTavilyClient();
    if (!client) return JSON.stringify({ success: false, mockValue: 120, currency: 'USD' });
    const response = await client.search(`${input.productName} current price buy USD`);
    // ... parse and return summary with price info
    return JSON.stringify({ success: true, summary, currency: 'USD' });
  },
});

We use LangChain’s DynamicStructuredTool here so it plugs into KaibanJS’s tool layer. The agent is prompted to call this once per damaged item (up to 5), then apply policy (depreciation, caps) and output a breakdown.

3. Executor: A2A → validate → team → or block

The executor receives the A2A body, pulls Kaiban activity (card_id, board_id, team_id), fetches the card via MCP, and only runs the team if the card has a description and is in todo:

const card = await getCard(cardId);
if (!card?.description || card.column_key !== 'todo') {
  logger.debug('Skipping card: no description or not in todo');
  continue;
}

try {
  await processDamagedBaggageCompensationRequest(context);
} catch (error) {
  logger.error('Failed to process card', { error, cardId });
  await moveCardToBlocked(cardId, boardId, teamId, {
    id: ourAgentId,
    type: 'agent',
    name: OUR_AGENT_NAME,
  });
}

So: one place for “run the pipeline” and “on failure, move to blocked.” All via MCP.

4. Team definition (async because of MCP tools)

The team is created asynchronously because we need to fetch Kaiban tools first:

export async function createDamagedBaggageCompensationTeam(
  context: DamagedBaggageCompensationTeamContext,
) {
  const kaibanTools = await getKaibanTools();
  const kaibanCardSyncAgent = new Agent({
    name: 'Kaiban Card Sync Agent',
    role: 'Kaiban Platform Sync',
    goal: 'Use Kaiban MCP tools to get card, move card to doing/done, update card result, and create card activities.',
    tools: kaibanTools,
  });
  // ... Claim Extraction, Compensation Calculation (policy + historical + Tavily), Compensation Offer agents
  // ... Tasks 0–4
  return new Team({
    name: 'Damaged Baggage Compensation Team',
    agents: [
      kaibanCardSyncAgent,
      claimExtractionValidationAgent,
      compensationCalculationAgent,
      compensationOfferAgent,
    ],
    tasks: [
      getCardAndMoveToDoingTask,
      extractAndValidateClaimTask,
      compensationCalculationTask,
      generateCompensationOfferTask,
      updateCardWithOfferAndMoveToDoneTask,
    ],
    inputs: { card_id, board_id, team_id, agent_id, agent_name },
    env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY || '' },
  });
}

Task 0 and Task 4 are both assigned to kaibanCardSyncAgent; the rest are specialized agents. Inputs are the IDs from the A2A activity so the sync agent can call get_card(card_id), move_card(card_id, column_key, actor), etc.

Get it running

git clone https://github.com/kaiban-ai/kaiban-agents-starter.git
cd examples/damaged-baggage-compensation-mcp-kaibanjs
npm install
cp .env.example .env

Edit .env:

KAIBAN_MCP_URL (or KAIBAN_TENANT + KAIBAN_ENVIRONMENT) and KAIBAN_API_TOKEN
OPENAI_API_KEY
TAVILY_API_KEY (optional; falls back to mock price if missing)
A2A_BASE_URL (your public URL, e.g. https://your-server.com)
KAIBAN_AGENT_ID or KAIBAN_DAMAGED_BAGGAGE_COMPENSATION_AGENT_ID (from Kaiban after you register the agent)

Agent card: GET {A2A_BASE_URL}/damagedBaggageCompensation/a2a/.well-known/agent-card.json
Agent endpoint: POST {A2A_BASE_URL}/damagedBaggageCompensation/a2a

Assign the agent to a board, then create a card with the description set to a claim (e.g. copy from GET .../damagedBaggageCompensation/samples/baggage-claim-example.txt). Put the card in the todo column. Start the server:

npm run dev

The platform will send an A2A request; the executor will run the team and the card will move todo → doing → done (or blocked on error).

Tests

Tests mock MCP, Tavily, and KaibanJS so you don’t need live credentials:

npm test

Use the same pattern to add tests for new tasks or tools.

Takeaways

Multi-agent + tools — KaibanJS gives you a clear split: one agent for “platform sync” (MCP tools), others for extraction, calculation, and copy. Each task has a single agent and a defined output schema (Zod).
MCP for platform — Using Kaiban MCP (instead of the SDK in agent code) keeps the pipeline tool-only and schema-driven; you can reuse the same MCP client in other agents.
Real-time data in the loop — Tavily shows how to plug a third-party API into an LLM tool (one call per product, cap at 5) so compensation is grounded in current prices.
Failure = visible — Moving failed cards to blocked via MCP and logging activities means every run is auditable and nothing drops on the floor.

Integrating KaibanJS Teams with Kaiban.io: Enterprise Workflow Automation via A2A Protocol

Dariel Vila — Fri, 16 Jan 2026 21:17:59 +0000

Introduction

In today's enterprise landscape, AI agents need to seamlessly integrate with existing workflow management systems. While building intelligent agents is powerful, their true value is unlocked when they can participate in collaborative workflows, update task statuses automatically, and provide visibility across teams.

This article explores how to integrate KaibanJS—a multi-agent framework for building collaborative AI teams—with Kaiban.io—an enterprise workflow management platform—using the standardized A2A (Agent-to-Agent) protocol.

We'll build a real-world example: an Airline Revenue Management Agent that processes cards from a Kanban board, analyzes Excel data, and automatically updates card statuses through the workflow lifecycle.

What is KaibanJS?

KaibanJS is an open-source TypeScript framework for building multi-agent AI systems. It enables developers to create collaborative teams of AI agents that work together to solve complex problems through structured workflows.

Key features:

Multi-agent collaboration: Define teams of specialized agents working together
Workflow-driven execution: Create sequential or parallel workflows using WorkflowDrivenAgent
Type-safe schemas: Built-in support for Zod schemas for validation
Tool integration: Agents can use custom tools for external operations
Flexible orchestration: Supports both simple task execution and complex multi-step workflows

Example: A Simple KaibanJS Team

import { Agent, Task, Team } from 'kaibanjs';

const analystAgent = new Agent({
  name: 'Data Analyst',
  role: 'Business Intelligence Specialist',
  goal: 'Analyze revenue data and provide insights',
});

const analysisTask = new Task({
  title: 'Analyze Revenue Data',
  description: 'Process Excel data and generate revenue insights',
  agent: analystAgent,
  expectedOutput: 'Revenue analysis report',
});

const team = new Team({
  name: 'Revenue Analysis Team',
  agents: [analystAgent],
  tasks: [analysisTask],
  inputs: { excelUrl: 'https://example.com/data.xlsx' },
});

const { result } = await team.start();

What is Kaiban.io?

Kaiban.io is an AI Agent Management System for airlines and enterprise organizations. As described on kaiban.io, it serves as a "command center for your AI workforce," providing a unified platform to safely deploy, train, and manage AI agents alongside existing teams and systems.

The platform addresses the challenge of AI agent fragmentation in enterprise environments by providing governance, visibility, and control over agent deployments. Kaiban.io integrates directly into existing systems and workflows without requiring costly infrastructure migrations, enabling organizations to start small and scale safely into connected multi-agent ecosystems.

Core Management Modules

Kaiban.io is built around three core management modules:

Agent Workflow Manager: Provides Kanban boards with card-based task management, real-time visibility into agent activities, and automatic status transitions (TODO → DOING → DONE → BLOCKED). This is the primary interface for our integration.
Agent Knowledge Manager: Captures and stores AI-generated knowledge in a centralized, organization-owned repository, preventing data silos and vendor lock-in.
Agent Lifecycle Manager: Manages the complete agent lifecycle—from recruitment and training to monitoring, enhancement, and retirement—with standardized processes and performance benchmarks.

A2A Protocol Integration

Kaiban.io supports the standardized A2A (Agent-to-Agent) protocol, enabling seamless integration with any agent framework, including KaibanJS, LangChain, AutoGen, and others. This SDK-agnostic approach eliminates vendor lock-in.

The platform acts as an orchestration layer:

Sends card activities to agents via A2A protocol messages when cards are created, moved, or updated
Receives status updates from agents, automatically updating card states and workflow progress
Provides discovery through agent cards that describe agent capabilities
Enables interoperability between agents built with different SDKs using the same standard

For our integration, the Agent Workflow Manager is the primary interaction point, managing the Kanban board where agents process cards and update their status automatically.

The A2A Protocol

The Agent-to-Agent (A2A) protocol is a standardized specification for agent communication. It defines how agents discover each other, exchange messages, and report execution status.

A2A Protocol Components

Agent Card: A JSON metadata file describing the agent's capabilities
Message Endpoint: HTTP endpoint receiving A2A protocol messages
Task Lifecycle: submitted → working → completed (or failed)
Event Bus: Communication channel for status updates

The protocol enables interoperability—agents built with different SDKs can communicate using the same standard.

Architecture Overview

When integrating KaibanJS with Kaiban.io, the architecture follows this flow:

Kaiban.io Platform
    ↓ (Card created/moved)
    ↓ (A2A message with KaibanActivityPart)
A2A Executor
    ↓ (Extract activity)
Kaiban Controller
    ↓ (Process workflow)
KaibanJS Team
    ↓ (Execute agents)
Business Logic
    ↓ (Update card status)
Kaiban SDK
    ↓ (API calls)
Kaiban.io Platform (Card updated)

Key Components

Agent Card (card.ts): Defines agent metadata for discovery
A2A Executor (executor.ts): Handles A2A protocol lifecycle
Kaiban Controller (kaiban-controller.ts): Manages workflow state and card updates
KaibanJS Team (agent.ts): Contains the business logic with AI agents

Implementation: Airline Revenue Management Agent

Let's build a complete integration example. This agent processes cards from a Kaiban board, extracts Excel URLs and route information, downloads the data, and performs revenue management analysis.

Step 1: Agent Card Configuration

The agent card is served at /.well-known/agent-card.json and provides discovery information:

// src/agents/airline-revenue-management/card.ts
import { AgentCard } from '@a2a-js/sdk';

export const revenueManagementAgentCard = (url: string): AgentCard => ({
  name: 'Airline Revenue Management Agent',
  description:
    'Agent that analyzes airline route data from Excel files and generates optimal fare recommendations',

  protocolVersion: '0.3.0',
  version: '0.1.0',
  url,

  defaultInputModes: ['text'],
  defaultOutputModes: ['text'],

  skills: [
    {
      id: 'revenue-management',
      name: 'Revenue Management Analysis',
      description: 'Analyzes airline route data and generates fare recommendations',
      tags: ['revenue-management', 'airline', 'pricing', 'excel-analysis'],
    },
  ],

  capabilities: {
    streaming: true,
    pushNotifications: false,
    stateTransitionHistory: false,
  },
});

Step 2: A2A Executor

The executor implements the A2A protocol, handling task lifecycle and routing activities to the Kaiban controller:

// src/agents/airline-revenue-management/executor.ts
import { AgentExecutor, ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
import { A2ADataPartType, KaibanActivityPart } from '@kaiban/sdk';
import { RevenueManagementKaibanController } from './controller/kaiban-controller';

class RevenueManagementAgentExecutor implements AgentExecutor {
  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
    const { taskId, contextId, userMessage } = requestContext;

    // Phase 1: Acknowledge task receipt
    eventBus.publish({
      kind: 'task',
      id: taskId,
      contextId,
      status: {
        state: 'submitted',
        timestamp: new Date().toISOString(),
      },
    });

    // Phase 2: Extract Kaiban activities from message
    const userMessageData = userMessage.parts.filter((part) => part.kind === 'data');

    if (userMessageData.length > 0) {
      eventBus.publish({
        kind: 'status-update',
        taskId,
        contextId,
        status: {
          state: 'working',
          timestamp: new Date().toISOString(),
        },
        final: false,
      });

      const kaibanController = await RevenueManagementKaibanController.build();

      // Phase 3: Process each Kaiban activity
      for (const messageData of userMessageData) {
        if (messageData.data.type === A2ADataPartType.KAIBAN_ACTIVITY) {
          const part = messageData as KaibanActivityPart;
          await kaibanController.processKaibanActivity(part.data.activity);
        }
      }
    }

    // Phase 4: Signal completion
    eventBus.publish({
      kind: 'status-update',
      taskId,
      contextId,
      status: {
        state: 'completed',
        timestamp: new Date().toISOString(),
      },
      final: true,
    });

    eventBus.finished();
  }
}

export const revenueManagementAgentExecutor = new RevenueManagementAgentExecutor();

Step 3: Kaiban Controller

The controller manages the workflow lifecycle, updating cards as they progress through stages:

// src/agents/airline-revenue-management/controller/kaiban-controller.ts
import { Activity, ActivityType, CardStatus, createKaibanClient, KaibanClient } from '@kaiban/sdk';
import { processRevenueManagementRequest } from './agent';

const TODO_COLUMN_KEY = 'todo';
const DOING_COLUMN_KEY = 'doing';
const DONE_COLUMN_KEY = 'done';
const BLOCKED_COLUMN_KEY = 'blocked';

export class RevenueManagementKaibanController {
  constructor(
    private readonly kaibanActor: ActivityActor,
    private readonly kaibanClient: KaibanClient,
  ) {}

  static async build() {
    const tenant = process.env.KAIBAN_TENANT;
    const token = process.env.KAIBAN_API_TOKEN;
    const agentId = process.env.KAIBAN_AGENT_ID;
    const baseUrl = process.env.KAIBAN_API_URL || `https://${tenant}.kaiban.io/api`;

    const kaibanClient = createKaibanClient({ baseUrl, tenant, token });
    const agent = await kaibanClient.agents.get(agentId);

    return new RevenueManagementKaibanController(
      { id: agent.id, type: 'agent', name: agent.name },
      kaibanClient,
    );
  }

  async processKaibanActivity(activity: Activity) {
    switch (activity.type) {
      case ActivityType.CARD_CREATED:
      case ActivityType.CARD_CLONED:
      case ActivityType.CARD_AGENT_ADDED:
      case ActivityType.CARD_COLUMN_CHANGED:
        await this.processCardCreatedActivity(activity);
        break;
    }
  }

  private async processCardCreatedActivity(activity: Activity) {
    const card = await this.kaibanClient.cards.get(activity.card_id);

    // Skip if card doesn't meet requirements
    if (
      !card?.description ||
      card.column_key !== TODO_COLUMN_KEY ||
      activity.actor.id === this.kaibanActor.id
    ) {
      return;
    }

    // Stage 1: Move to DOING
    await this.kaibanClient.cards.update(card.id, {
      column_key: DOING_COLUMN_KEY,
      status: CardStatus.DOING,
    });

    try {
      // Stage 2: Process with KaibanJS team
      const result = await processRevenueManagementRequest(card.description);

      // Stage 3: Update card and move to DONE
      await this.kaibanClient.cards.update(card.id, {
        result: result,
        column_key: DONE_COLUMN_KEY,
        status: CardStatus.DONE,
      });
    } catch (error) {
      // Error handling: Move to BLOCKED
      await this.kaibanClient.cards.update(card.id, {
        column_key: BLOCKED_COLUMN_KEY,
        status: CardStatus.BLOCKED,
      });
    }
  }
}

Step 4: KaibanJS Team with Workflow

The team uses a WorkflowDrivenAgent with three sequential steps:

// src/agents/airline-revenue-management/controller/agent.ts
import { Agent, Task, Team } from 'kaibanjs';
import { createStep, createWorkflow } from '@kaibanjs/workflow';
import { z } from 'zod';
import * as XLSX from 'xlsx';

// Step 1: Extract URL and routes from user message
const extractUrlAndRoutesStep = createStep({
  id: 'extract-url-and-routes',
  inputSchema: z.object({ userMessage: z.string() }),
  outputSchema: z.object({
    excelUrl: z.string().url(),
    route: z.string(),
  }),
  execute: async ({ inputData }) => {
    const { userMessage } = inputData;
    // Use an extraction team to parse the message
    const extractionTeam = createExtractionTeam(userMessage);
    const result = await extractionTeam.start();
    return result.result;
  },
});

// Step 2: Download and parse Excel file
const downloadParseAndExtractRouteStep = createStep({
  id: 'download-parse-extract-route',
  inputSchema: z.object({
    excelUrl: z.string().url(),
    route: z.string(),
  }),
  outputSchema: z.object({
    route: z.string(),
    origin: z.string(),
    destination: z.string(),
    cyForecast: z.string(),
    pyData: z.string(),
    competitorFares: z.string(),
  }),
  execute: async ({ inputData }) => {
    const { excelUrl, route } = inputData;

    // Download Excel file
    const response = await fetch(excelUrl);
    const arrayBuffer = await response.arrayBuffer();
    const workbook = XLSX.read(new Uint8Array(arrayBuffer), { type: 'array' });

    // Parse sheets and extract route data
    const cyForecast = workbook.Sheets['CY Forecast'];
    const pyData = workbook.Sheets['PY Data'];
    const competitorFares = workbook.Sheets['Competitor Fares'];

    // Find route-specific data...
    // Return extracted data
    return {
      route,
      origin: route.split('-')[0],
      destination: route.split('-')[1],
      cyForecast: JSON.stringify(/* parsed data */),
      pyData: JSON.stringify(/* parsed data */),
      competitorFares: JSON.stringify(/* parsed data */),
    };
  },
});

// Step 3: Execute revenue management analysis
const executeAnalysisStep = createStep({
  id: 'execute-analysis',
  inputSchema: z.object({
    route: z.string(),
    origin: z.string(),
    destination: z.string(),
    cyForecast: z.string(),
    pyData: z.string(),
    competitorFares: z.string(),
  }),
  outputSchema: z.unknown(),
  execute: async ({ inputData }) => {
    // Execute the revenue management analysis team
    const analysisTeam = revenueManagementAnalysisTeam;
    const { result } = await analysisTeam.start(inputData);
    return result;
  },
});

// Create workflow
const analysisWorkflow = createWorkflow({
  id: 'revenue-management-analysis-workflow',
  inputSchema: z.object({ userMessage: z.string() }),
  outputSchema: z.record(z.unknown()),
});

// Chain steps
analysisWorkflow
  .then(extractUrlAndRoutesStep)
  .then(downloadParseAndExtractRouteStep)
  .then(executeAnalysisStep);
analysisWorkflow.commit();

// Create WorkflowDrivenAgent
const workflowAnalysisAgent = new Agent({
  type: 'WorkflowDrivenAgent',
  name: 'Revenue Management Workflow Agent',
  workflow: analysisWorkflow,
});

export const processRevenueManagementRequest = async (userMessage: string) => {
  const team = new Team({
    name: 'Airline Revenue Management Team',
    agents: [workflowAnalysisAgent],
    tasks: [
      /* tasks */
    ],
    inputs: { userMessage },
  });

  const { result } = await team.start();
  return JSON.stringify(result);
};

Step 5: Request Handler Setup

Finally, wire everything together in the Express server:

// src/agents/airline-revenue-management/handler.ts
import { DefaultRequestHandler } from '@a2a-js/sdk/server';
import { A2AExpressApp } from '@a2a-js/sdk/server/express';
import express from 'express';
import { revenueManagementAgentCard } from './card';
import { tasksStore, revenueManagementAgentExecutor } from './executor';

export const createRevenueManagementAgentHandler = (agentUrl: string) => {
  return new DefaultRequestHandler(
    revenueManagementAgentCard(agentUrl),
    tasksStore,
    revenueManagementAgentExecutor,
  );
};

export const setupRevenueManagementAgentRoutes = (app: express.Express, baseUrl: string) => {
  const agentPath = '/airlineRevenueManagement/a2a';
  const agentUrl = `${baseUrl}${agentPath}`;

  new A2AExpressApp(createRevenueManagementAgentHandler(agentUrl)).setupRoutes(app, agentPath);

  return {
    agentUrl,
    cardUrl: `${agentUrl}/.well-known/agent-card.json`,
  };
};

Workflow Lifecycle

When a card is created in Kaiban.io, the following lifecycle occurs:

1. Card Created (TODO)

User creates a card in the Kanban board with a description containing Excel URL and route
Kaiban.io sends a CARD_CREATED activity via A2A protocol

2. Processing Started (DOING)

A2A executor receives the activity and routes it to the Kaiban controller
Controller moves the card to DOING column
KaibanJS team begins processing:
- Extracts Excel URL and route from card description
- Downloads and parses Excel file
- Executes revenue management analysis

3. Analysis Complete (DONE)

Team completes analysis and generates recommendations
Controller updates card with results
Card moves to DONE column
All activities are logged for audit trail

4. Error Handling (BLOCKED)

If processing fails (invalid Excel, missing route, etc.)
Card moves to BLOCKED column
Error details are logged for manual review

Setup Instructions

1. Clone the Starter Repository

git clone https://github.com/kaiban-ai/kaiban-agents-starter.git
cd kaiban-agents-starter/examples/airline-revenue-management-kaibanjs

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file:

# Kaiban.io Platform Configuration
KAIBAN_TENANT=your-tenant
KAIBAN_API_TOKEN=your-api-token
KAIBAN_AGENT_ID=your-agent-id
KAIBAN_API_URL=https://your-tenant.kaiban.io/api

# A2A Protocol Configuration
A2A_BASE_URL=http://localhost:4000
PORT=4000

# AI Configuration
OPENAI_API_KEY=your-openai-api-key

4. Start the Server

npm run dev

The server will start on port 4000 with these endpoints:

Agent Card: http://localhost:4000/airlineRevenueManagement/a2a/.well-known/agent-card.json
Agent Endpoint: POST http://localhost:4000/airlineRevenueManagement/a2a

5. Register Agent in Kaiban.io

Log into your Kaiban.io dashboard
Navigate to Agents section
Register your agent using:
- Agent Card URL: http://your-public-url/airlineRevenueManagement/a2a/.well-known/agent-card.json
- Agent Endpoint URL: http://your-public-url/airlineRevenueManagement/a2a
Assign the agent to a Kanban board

6. Test the Integration

Create a card in your Kaiban board with a description like:

   Analyze route LHR-SLC using data from https://example.com/pricing-analysis.xlsx

The agent will automatically:
- Extract the URL and route
- Download and parse the Excel file
- Perform revenue management analysis
- Update the card with results

Benefits of This Integration

1. SDK Agnostic

The A2A protocol works with any agent framework. You can build agents with KaibanJS, LangChain, AutoGen, or any other SDK.

2. Standardized Communication

The A2A protocol provides a standard way for agents to communicate, reducing integration complexity.

3. Automatic Workflow Management

Cards automatically transition through workflow states based on agent execution, providing visibility and traceability.

4. Enterprise Visibility

Full audit trail of all activities, status changes, and agent interactions in a centralized platform.

5. Real-time Collaboration

Teams can collaborate on cards, assign agents, and track progress in real-time through the Kaiban board interface.

Conclusion

Integrating KaibanJS with Kaiban.io via the A2A protocol enables powerful enterprise workflow automation. Agents built with KaibanJS can seamlessly participate in Kanban workflows managed by Kaiban.io's Agent Workflow Manager, automatically update card statuses, and provide full visibility into AI-driven processes.

The standardized A2A protocol ensures interoperability between KaibanJS agents and the Kaiban platform, while KaibanJS provides a powerful framework for building multi-agent AI systems. Together, they enable developers to:

Integrate naturally with existing enterprise workflows and systems
Maintain full governance and visibility into agent execution
Scale safely from single agents to connected multi-agent ecosystems
Deliver measurable value through standardized processes and performance tracking

This integration demonstrates how KaibanJS can work alongside enterprise platforms like Kaiban.io to transform AI agents from isolated experiments into reliable, governed, and high-impact operational capabilities—all without disrupting existing operations.

Additional Resources

Structured Output Chaining in KaibanJS: Bridging LLM and Workflow Agents

Dariel Vila — Fri, 09 Jan 2026 14:10:34 +0000

When building production AI systems, you often need the best of both worlds: the creativity and adaptability of LLM-based agents combined with the reliability and determinism of structured workflows. KaibanJS's structured output chaining feature makes this seamless.

In this article, we'll explore how to chain ReactChampionAgent (LLM-powered) with WorkflowDrivenAgent (workflow-based) to build robust AI systems using a real-world product review analysis use case.

The Challenge: Combining LLM and Deterministic Processing

Modern AI applications frequently require:

LLM-powered analysis to extract insights from unstructured data
Deterministic processing to validate, transform, and aggregate that data
Type-safe data flow between these different processing stages

Traditional approaches require manual data transformation, error-prone mappings, and brittle integration points. KaibanJS solves this with automatic structured output chaining.

What is Structured Output Chaining?

Structured output chaining automatically passes validated, schema-constrained outputs from one agent to another within a team. When a ReactChampionAgent task has an outputSchema that matches a WorkflowDrivenAgent workflow's inputSchema, the system handles the data transfer seamlessly.

Key Benefits:

✅ Type Safety: Full end-to-end validation with Zod schemas
✅ Zero Configuration: Automatic detection and mapping
✅ Error Prevention: Schema validation catches mismatches early
✅ Developer Experience: Write clean, declarative code

Real-World Example: Product Review Analysis

Let's build a complete review analysis system that:

Processes raw reviews using a deterministic workflow
Analyzes sentiment using an LLM agent
Generates business insights using another LLM agent

Step 1: Define Review Schemas

First, we establish our data structures using Zod:

import { z } from 'zod';

const reviewSchema = z.object({
  product: z.string(),
  rating: z.number().min(1).max(5),
  text: z.string().min(1),
  date: z.string().optional(),
  author: z.string().optional(),
});

const processedDataSchema = z.object({
  metrics: z.object({
    averageRating: z.number(),
    ratingDistribution: z.object({
      1: z.number(),
      2: z.number(),
      3: z.number(),
      4: z.number(),
      5: z.number(),
    }),
    totalReviews: z.number(),
    validReviews: z.number(),
    invalidReviews: z.number(),
    averageTextLength: z.number(),
    commonKeywords: z.array(
      z.object({
        word: z.string(),
        count: z.number(),
      })
    ),
  }),
  reviews: z.array(reviewSchema),
  summary: z.string(),
});

Step 2: Create Workflow-Driven Review Processor

The WorkflowDrivenAgent handles deterministic data processing:

import { Agent, Task } from 'kaibanjs';
import { createStep, createWorkflow } from '@kaibanjs/workflow';

// Validation step
const validateReviewsStep = createStep({
  id: 'validate-reviews',
  inputSchema: z.object({
    reviews: z.array(reviewSchema),
  }),
  outputSchema: z.object({
    validReviews: z.array(reviewSchema),
    invalidReviews: z.array(
      z.object({
        review: z.any(),
        errors: z.array(z.string()),
      })
    ),
    totalCount: z.number(),
    validCount: z.number(),
  }),
  execute: async ({ inputData }) => {
    const { reviews } = inputData;
    const validReviews = [];
    const invalidReviews = [];

    reviews.forEach((review) => {
      const result = reviewSchema.safeParse(review);
      if (result.success) {
        validReviews.push(result.data);
      } else {
        invalidReviews.push({
          review,
          errors: result.error.errors.map(
            (e) => `${e.path.join('.')}: ${e.message}`
          ),
        });
      }
    });

    return {
      validReviews,
      invalidReviews,
      totalCount: reviews.length,
      validCount: validReviews.length,
    };
  },
});

// Metrics extraction step
const extractMetricsStep = createStep({
  id: 'extract-metrics',
  inputSchema: z.object({
    validReviews: z.array(reviewSchema),
    invalidReviews: z.array(z.any()),
    totalCount: z.number(),
    validCount: z.number(),
  }),
  outputSchema: z.object({
    metrics: z.object({
      averageRating: z.number(),
      ratingDistribution: z.object({
        1: z.number(),
        2: z.number(),
        3: z.number(),
        4: z.number(),
        5: z.number(),
      }),
      totalReviews: z.number(),
      validReviews: z.number(),
      invalidReviews: z.number(),
      averageTextLength: z.number(),
      commonKeywords: z.array(
        z.object({
          word: z.string(),
          count: z.number(),
        })
      ),
    }),
    validReviews: z.array(reviewSchema),
  }),
  execute: async ({ inputData }) => {
    const { validReviews, invalidReviews, totalCount, validCount } = inputData;

    // Calculate metrics
    const totalRating = validReviews.reduce(
      (sum, review) => sum + review.rating,
      0
    );
    const averageRating = validCount > 0 ? totalRating / validCount : 0;

    const ratingDistribution = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
    validReviews.forEach((review) => {
      ratingDistribution[review.rating.toString()]++;
    });

    const totalTextLength = validReviews.reduce(
      (sum, review) => sum + review.text.length,
      0
    );
    const averageTextLength = validCount > 0 ? totalTextLength / validCount : 0;

    // Extract keywords
    const wordCount = {};
    validReviews.forEach((review) => {
      const words = review.text
        .toLowerCase()
        .replace(/[^\w\s]/g, '')
        .split(/\s+/)
        .filter((word) => word.length > 3);
      words.forEach((word) => {
        wordCount[word] = (wordCount[word] || 0) + 1;
      });
    });

    const commonKeywords = Object.entries(wordCount)
      .map(([word, count]) => ({ word, count }))
      .sort((a, b) => b.count - a.count)
      .slice(0, 10);

    return {
      metrics: {
        averageRating: Math.round(averageRating * 100) / 100,
        ratingDistribution,
        totalReviews: totalCount,
        validReviews: validCount,
        invalidReviews: invalidReviews.length,
        averageTextLength: Math.round(averageTextLength),
        commonKeywords,
      },
      validReviews,
    };
  },
});

// Data aggregation step
const aggregateDataStep = createStep({
  id: 'aggregate-data',
  inputSchema: z.object({
    metrics: z.object({
      averageRating: z.number(),
      ratingDistribution: z.object({
        1: z.number(),
        2: z.number(),
        3: z.number(),
        4: z.number(),
        5: z.number(),
      }),
      totalReviews: z.number(),
      validReviews: z.number(),
      invalidReviews: z.number(),
      averageTextLength: z.number(),
      commonKeywords: z.array(
        z.object({
          word: z.string(),
          count: z.number(),
        })
      ),
    }),
    validReviews: z.array(reviewSchema),
  }),
  outputSchema: processedDataSchema,
  execute: async ({ inputData }) => {
    const { metrics, validReviews } = inputData;

    const summary = `Processed ${metrics.validReviews} valid reviews out of ${
      metrics.totalReviews
    } total. 
Average rating: ${metrics.averageRating}/5. 
Rating distribution: ${metrics.ratingDistribution['5']} five-star, ${
      metrics.ratingDistribution['4']
    } four-star, ${metrics.ratingDistribution['3']} three-star, ${
      metrics.ratingDistribution['2']
    } two-star, ${metrics.ratingDistribution['1']} one-star reviews.
Average review length: ${metrics.averageTextLength} characters.
Top keywords: ${metrics.commonKeywords
      .slice(0, 5)
      .map((k) => k.word)
      .join(', ')}.`;

    return {
      processedData: {
        metrics,
        reviews: validReviews,
        summary,
      },
    };
  },
});

// Create and configure the workflow
const reviewProcessingWorkflow = createWorkflow({
  id: 'review-processing-workflow',
  inputSchema: z.object({
    reviews: z.array(reviewSchema),
  }),
  outputSchema: processedDataSchema,
});

reviewProcessingWorkflow
  .then(validateReviewsStep)
  .then(extractMetricsStep)
  .then(aggregateDataStep);
reviewProcessingWorkflow.commit();

// Create the workflow-driven agent
const reviewProcessorAgent = new Agent({
  name: 'Review Processor',
  type: 'WorkflowDrivenAgent',
  workflow: reviewProcessingWorkflow,
});

Step 3: Create LLM Agents with Structured Outputs

Now we create LLM agents that receive the processed data and generate insights:

// Sentiment analyzer with structured output expectation
const sentimentAnalyzerAgent = new Agent({
  name: 'Sentiment Analyzer',
  role: 'Sentiment Analysis Expert',
  goal: 'Analyze sentiment, themes, and patterns in product reviews',
  background:
    'Expert in natural language processing, sentiment analysis, and identifying patterns in customer feedback.',
  type: 'ReactChampionAgent',
  tools: [],
});

// Insights generator
const insightsGeneratorAgent = new Agent({
  name: 'Insights Generator',
  role: 'Business Insights Expert',
  goal: 'Generate actionable insights and recommendations based on review analysis',
  background:
    'Expert in business analysis and strategic recommendations. Specialized in translating customer feedback into actionable business insights.',
  type: 'ReactChampionAgent',
  tools: [],
});

Step 4: Define Tasks with Schema Chaining

Here's where the magic happens - we define tasks that automatically chain:

// Task 1: Process reviews (WorkflowDrivenAgent)
const processReviewsTask = new Task({
  description:
    'Process and analyze the product reviews: {reviews}. Extract metrics, validate data, and calculate statistics.',
  expectedOutput:
    'Structured metrics including average rating, rating distribution, common keywords, and processed review data',
  agent: reviewProcessorAgent,
});

// Task 2: Analyze sentiment (ReactChampionAgent)
// This automatically receives processedData from Task 1
const analyzeSentimentTask = new Task({
  description: `Analyze the sentiment and themes in the processed reviews. 
    Focus on:
    - Overall sentiment trends (positive, negative, neutral)
    - Main themes and topics mentioned by customers
    - Common pain points and complaints
    - Positive aspects and strengths highlighted
    - Emotional patterns across different rating levels

    Use the processed metrics and review data to provide comprehensive sentiment analysis.`,
  expectedOutput:
    'Detailed sentiment analysis with themes, pain points, strengths, and emotional patterns identified in the reviews',
  agent: sentimentAnalyzerAgent,
});

// Task 3: Generate insights (ReactChampionAgent)
// This automatically receives outputs from both Task 1 and Task 2
const generateInsightsTask = new Task({
  description: `Generate actionable business insights and recommendations based on the review metrics and sentiment analysis.
    Provide:
    - Key findings and trends
    - Priority areas for improvement
    - Strengths to leverage
    - Specific actionable recommendations
    - Strategic suggestions for product development and customer satisfaction`,
  expectedOutput:
    'Comprehensive business insights with actionable recommendations and strategic suggestions for product improvement',
  agent: insightsGeneratorAgent,
});

Step 5: Assemble the Team

Put it all together:

import { Team } from 'kaibanjs';

const team = new Team({
  name: 'Product Reviews Analysis Team',
  agents: [
    reviewProcessorAgent,
    sentimentAnalyzerAgent,
    insightsGeneratorAgent,
  ],
  tasks: [processReviewsTask, analyzeSentimentTask, generateInsightsTask],
  inputs: {
    reviews: [
      {
        product: 'Smartphone XYZ Pro',
        rating: 5,
        text: 'Excellent product, very fast and great battery life. The camera is impressive and the screen looks incredible.',
        date: '2024-01-15',
        author: 'John P.',
      },
      // ... more reviews
    ],
  },
  env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
});

// Execute the team
const result = await team.start();

How Schema Chaining Works

The automatic chaining happens through KaibanJS's task result system:

Task 1 completes: The WorkflowDrivenAgent processes reviews and returns structured data matching processedDataSchema.
Automatic extraction: The system extracts the result from Task 1 and stores it in the task store.
Task 2 receives data: When Task 2 (sentiment analysis) executes, it automatically receives Task 1's output as part of its context.
Type-safe access: The LLM in Task 2 can access the structured data via task result interpolation in the description.
Task 3 receives multiple results: Task 3 automatically receives results from both previous tasks.

Visual Flow:

┌─────────────────────────────────────┐
│ Task 1: Process Reviews             │
│ Agent: WorkflowDrivenAgent          │
│ ─────────────────────────────────── │
│ Input: { reviews: [...] }           │
│ Output: { processedData: {...} }    │
└──────────────┬──────────────────────┘
               │
               │ ═══════════════════════
               │ AUTOMATIC SCHEMA CHAIN
               │ ═══════════════════════
               ▼
┌─────────────────────────────────────┐
│ Task 2: Analyze Sentiment           │
│ Agent: ReactChampionAgent           │
│ ─────────────────────────────────── │
│ Input: Task 1 result (auto-injected)│
│ Output: Sentiment analysis          │
└──────────────┬──────────────────────┘
               │
               │ ═══════════════════════
               │ MULTIPLE RESULTS CHAIN
               │ ═══════════════════════
               ▼
┌─────────────────────────────────────┐
│ Task 3: Generate Insights           │
│ Agent: ReactChampionAgent           │
│ ─────────────────────────────────── │
│ Input: Task 1 + Task 2 results      │
│ Output: Business insights           │
└─────────────────────────────────────┘

Advanced: Explicit Schema Matching

For even more control, you can use explicit outputSchema on LLM tasks:

const sentimentSchema = z.object({
  overallSentiment: z.enum(['positive', 'neutral', 'negative']),
  themes: z.array(z.string()),
  painPoints: z.array(z.string()),
  strengths: z.array(z.string()),
  emotionalPatterns: z.record(z.string(), z.string()),
});

const analyzeSentimentTask = new Task({
  description: 'Analyze sentiment in reviews...',
  outputSchema: sentimentSchema, // Explicit output schema
  agent: sentimentAnalyzerAgent,
});

// Now you can create a workflow that expects sentimentSchema
const insightsWorkflow = createWorkflow({
  id: 'insights-workflow',
  inputSchema: sentimentSchema, // Matches Task 2's outputSchema
  // ... workflow steps
});

When schemas match, KaibanJS automatically passes the data at the root level. If they don't match, the data is still available but nested under the task ID.

Best Practices

Use descriptive schemas: Make your Zod schemas clear and well-documented
Validate early: Let schema validation catch errors before they propagate
Keep schemas reusable: Define common schemas once and import them
Document dependencies: Make task dependencies clear in descriptions
Test workflows independently: Ensure workflows work in isolation before chaining

Conclusion

Structured output chaining in KaibanJS provides a powerful way to combine the flexibility of LLM agents with the reliability of deterministic workflows. By leveraging automatic schema-based data passing, you can build robust AI systems that are both powerful and maintainable.

The key advantages:

No manual data mapping - The system handles it automatically
Type safety - Zod schemas ensure data integrity
Better debugging - Clear data flow and validation points
Production ready - Deterministic workflows ensure consistency

Ready to build your own chained agent system? Check out the KaibanJS documentation and try the live example.

Resources:

Add Production-Ready Observability to Your AI Agent Workflows in 5 Minutes

Dariel Vila — Fri, 31 Oct 2025 12:12:55 +0000

Have you ever stared at your terminal wondering why your multi-agent workflow failed? You know a task errored, but you can't tell which agent was responsible, how much it cost, or what the LLM actually received as input. Sound familiar?

If you're building AI agent systems, you need observability. But adding it shouldn't require rewriting your code or instrumenting every LLM call manually. Let me show you how to add production-grade observability using OpenTelemetry in just a few lines of code.

The Problem: Debugging Multi-Agent Systems is Hard

When you're running a workflow with multiple agents, each making LLM calls, you're dealing with:

Long execution chains: Task A → Agent 1 → LLM → Task B → Agent 2 → LLM → Task C
Unclear failure points: Which agent failed? Was it the LLM call, the parsing, or the logic?
Hidden costs: No visibility into token usage per agent or task
Nested execution: Agents can spawn sub-tasks, making traces complex

Traditional logging doesn't cut it. You need structured traces that show the entire workflow execution with timing, costs, and context.

What is OpenTelemetry?

OpenTelemetry (often abbreviated as OTL or OTel) is an open standard for observability. Think of it as a universal language for describing what your application is doing. It's supported by virtually every monitoring tool, from open-source solutions like Jaeger to commercial platforms like Datadog, and specialized AI tools like Langfuse and Phoenix.

The key concept: Traces. A trace is a record of a request's journey through your system, broken down into spans (individual operations) that have parent-child relationships. This creates a timeline view of your entire workflow.

Introducing KaibanJS

For this tutorial, we'll use KaibanJS, a TypeScript framework for building multi-agent workflows. KaibanJS makes it easy to define agents with specific roles and orchestrate them through task dependencies.

Here's why it's great for production:

Task dependencies: Declare what needs to run before what
Agent specialization: Each agent has a clear role and responsibility
Automatic orchestration: The framework handles coordination and queuing
Event-driven: Built-in events make it observable by design
Type-safe: TypeScript everywhere for fewer runtime surprises

The best part? You can add observability without modifying your workflow code at all.

The Solution: @kaibanjs/opentelemetry

The @kaibanjs/opentelemetry package automatically instruments your KaibanJS workflows and exports traces to any OpenTelemetry-compatible service. It works by subscribing to workflow events, no code changes needed.

Let's see it in action:

Quick Start: Adding Observability to Your Workflow

First, install the package:

npm install @kaibanjs/opentelemetry

Now, let's build a practical example: a content processing workflow that extracts, analyzes, and synthesizes information.

Step 1: Define Your Agents and Tasks

import { Team, Agent, Task } from 'kaibanjs';

// Define specialized agents
const extractor = new Agent({
  name: 'ContentExtractor',
  role: 'Extract structured data',
  goal: 'Parse unstructured content into JSON',
  background: 'Expert in NLP and data extraction',
});

const analyzer = new Agent({
  name: 'ContentAnalyzer',
  role: 'Analyze content',
  goal: 'Identify patterns and insights',
  background: 'Expert in content analysis',
});

const synthesizer = new Agent({
  name: 'ContentSynthesizer',
  role: 'Synthesize findings',
  goal: 'Create coherent summaries',
  background: 'Expert in summarization',
});

// Define tasks with dependencies
const extractTask = new Task({
  title: 'Extract Content',
  description: 'Extract structured data from: {input}',
  expectedOutput: 'JSON with key information',
  agent: extractor,
});

const analyzeTask = new Task({
  title: 'Analyze Content',
  description: 'Analyze the extracted content',
  expectedOutput: 'Analysis report',
  agent: analyzer,
  dependencies: [extractTask], // Runs after extraction
});

const synthesizeTask = new Task({
  title: 'Synthesize Findings',
  description: 'Create a summary',
  expectedOutput: 'Executive summary',
  agent: synthesizer,
  dependencies: [analyzeTask], // Runs after analysis
});

const team = new Team({
  name: 'Content Processing Team',
  agents: [extractor, analyzer, synthesizer],
  tasks: [extractTask, analyzeTask, synthesizeTask],
});

Step 2: Add Observability

Now, here's where the magic happens. Add just a few lines:

import { enableOpenTelemetry } from '@kaibanjs/opentelemetry';

const config = {
  enabled: true,
  sampling: {
    rate: 1.0, // Sample all traces (use 0.1-0.3 in production)
    strategy: 'always',
  },
  attributes: {
    includeSensitiveData: false,
    customAttributes: {
      'service.name': 'content-processor',
      'service.version': '1.0.0',
    },
  },
  exporters: {
    console: true, // See traces in your terminal
  },
};

enableOpenTelemetry(team, config);

That's it! Your workflow is now fully observable. When you run:

await team.start({ input: 'Your content here...' });

You'll see structured traces in your console showing every task execution, agent thinking phase, LLM call, token usage, and cost.

Step 3: Send Traces to a Monitoring Service

For production, you'll want to send traces to a proper observability platform. Here's how to export to Langfuse (great for LLM observability):

import * as dotenv from 'dotenv';
dotenv.config();

const config = {
  enabled: true,
  sampling: { rate: 0.1, strategy: 'probabilistic' }, // Sample 10% in production
  attributes: {
    includeSensitiveData: false,
    customAttributes: {
      'service.name': 'content-processor',
      'service.environment': process.env.NODE_ENV || 'development',
    },
  },
  exporters: {
    console: process.env.NODE_ENV === 'development', // Only in dev
    otlp: {
      endpoint: 'https://cloud.langfuse.com/api/public/otel',
      protocol: 'http',
      headers: {
        Authorization: `Basic ${Buffer.from(
          `${process.env.LANGFUSE_PUBLIC_KEY}:${process.env.LANGFUSE_SECRET_KEY}`
        ).toString('base64')}`,
      },
      serviceName: 'content-processor',
    },
  },
};

enableOpenTelemetry(team, config);

Or send to multiple services simultaneously:

exporters: {
  otlp: [
    // Langfuse for LLM-specific insights
    {
      endpoint: 'https://cloud.langfuse.com/api/public/otel',
      protocol: 'http',
      headers: { /* ... */ },
      serviceName: 'content-processor-langfuse',
    },
    // SigNoz for infrastructure monitoring
    {
      endpoint: 'https://ingest.us.signoz.cloud:443',
      protocol: 'grpc',
      headers: { 'signoz-access-token': process.env.SIGNOZ_TOKEN },
      serviceName: 'content-processor-signoz',
    },
  ],
}

What You Get: Understanding Your Traces

When your workflow runs, you get hierarchical traces like this:

Task: Extract Content (2.5s)
├── Agent Thinking (1.2s)
│   ├── Model: gpt-4
│   ├── Input tokens: 245
│   ├── Output tokens: 312
│   └── Cost: $0.012
└── Status: DONE

Task: Analyze Content (3.1s)
├── Agent Thinking (2.8s)
│   └── Cost: $0.018
└── Status: DONE

Task: Synthesize Findings (1.9s)
└── Agent Thinking (1.7s)
    └── Cost: $0.008

This immediately tells you:

Which tasks took longest: Analyze Content is your bottleneck
Cost breakdown: You spent $0.038 total, mostly in analysis
Token usage: You can optimize the extraction step
Failure points: If something fails, you see exactly where

LLM-Specific Attributes

The package uses semantic conventions that LLM observability platforms automatically recognize:

{
  // Request info
  'kaiban.llm.request.model': 'gpt-4',
  'kaiban.llm.request.provider': 'openai',
  'kaiban.llm.request.input_length': 1524,

  // Usage metrics
  'kaiban.llm.usage.input_tokens': 245,
  'kaiban.llm.usage.output_tokens': 312,
  'kaiban.llm.usage.total_tokens': 557,
  'kaiban.llm.usage.cost': 0.012,

  // Response info
  'kaiban.llm.response.duration': 1200,
  'kaiban.llm.response.status': 'completed',
}

Platforms like Langfuse and Phoenix automatically display these in specialized LLM views, giving you token trends, cost analysis, and latency monitoring out of the box.

Production Best Practices

1. Use Sampling

Don't trace everything in production, it's expensive:

sampling: {
  rate: 0.1, // Sample 10% of workflows
  strategy: 'probabilistic',
}

2. Environment-Based Configuration

Use environment variables for secrets:

# .env
LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
SIGNOZ_TOKEN=your-token

exporters: {
  otlp: {
    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
    headers: {
      Authorization: `Basic ${Buffer.from(
        `${process.env.LANGFUSE_PUBLIC_KEY}:${process.env.LANGFUSE_SECRET_KEY}`
      ).toString('base64')}`,
    },
    serviceName: 'my-service',
  },
}

3. Disable Console in Production

exporters: {
  console: process.env.NODE_ENV === 'development',
  otlp: { /* ... */ },
}

4. Handle Shutdown Gracefully

If you're using the advanced API:

import { createOpenTelemetryIntegration } from '@kaibanjs/opentelemetry';

const integration = createOpenTelemetryIntegration(config);
integration.integrateWithTeam(team);

// Your workflow code
await team.start({ input: 'data' });

// Cleanup when done
await integration.shutdown();

Real-World Use Cases

With this setup, you can now:

Debug failures: See exactly which agent failed and what it received
Optimize costs: Identify expensive tasks and agents
Monitor performance: Track task durations and spot bottlenecks
Analyze patterns: Understand how agents iterate and refine outputs

Supported Services

The OTLP exporter works with any OpenTelemetry-compatible service:

Langfuse: LLM observability (HTTP)
Phoenix: AI observability by Arize (HTTP)
SigNoz: Full-stack observability (gRPC/HTTP)
Braintrust: AI experiment tracking (HTTP/gRPC)
Dash0: Observability platform (HTTP)
Any OTLP collector: Your own infrastructure

Try It Yourself

Want to see it in action? Check out the package examples:

npm install @kaibanjs/opentelemetry
npm run dev # Runs a basic example with console output

Or explore the full documentation for more advanced use cases.

Wrapping Up

Adding observability to AI agent workflows doesn't have to be painful. With @kaibanjs/opentelemetry, you get production-ready tracing in minutes, not hours. The best part? It's completely non-invasive, you can add it to existing workflows without modifying a single line of your business logic.

Once you have traces flowing to your observability platform, you'll wonder how you ever debugged these systems without them. Trust me.

Questions or feedback? Drop a comment below or check out the package repository for more examples and documentation.

Building a Smart Product Knowledge Base with RAG and AI Agents in JavaScript

Dariel Vila — Thu, 16 Oct 2025 15:57:05 +0000

TL;DR

Learn how to build an intelligent product knowledge base using KaibanJS and SimpleRAGRetrieve that can answer customer questions using Retrieval-Augmented Generation (RAG). We'll create AI agents that search, analyze, and recommend products based on semantic understanding, all in JavaScript!

🔗 Live Demo Code: See full example

Why This Matters

Ever struggled with building intelligent search systems that actually understand what users mean, not just keyword matching? RAG (Retrieval-Augmented Generation) is the game-changer, and now you can implement it in JavaScript with minimal code.

What We're Building

A product support system where AI agents can:

✅ Search through product catalogs using semantic understanding
✅ Answer specific questions about products
✅ Compare and recommend products based on customer needs
✅ Access real product specifications and availability

All powered by vector search and LLMs, no complex backend required!

Meet KaibanJS & SimpleRAGRetrieve

What is KaibanJS?

KaibanJS is a JavaScript framework for building AI agent teams. Think of it as a way to create collaborative AI agents that can use tools, work together, and solve complex tasks.

What is SimpleRAGRetrieve?

SimpleRAGRetrieve from @kaibanjs/tools is a specialized RAG tool designed specifically for scenarios where you have pre-indexed data in a vector store. This is different from tools that handle both indexing and retrieval - SimpleRAGRetrieve focuses purely on the retrieval side, assuming your vector store is already populated.

Key benefits:

🎯 Pre-configured RAG pipeline - Just plug in your pre-indexed vector store
🔧 Customizable retrieval - Control how many documents to fetch, search type, and scoring
🌐 LangChain.js compatibility - Use any embeddings or vector stores from the LangChain ecosystem
⚡ Production-ready - Works with Pinecone, Supabase, or in-memory stores

Note: In this tutorial, we're using mocked data and showing the full indexing process with RAGToolkit for demonstration purposes. This helps you understand the complete RAG pipeline from data to retrieval. In real-world scenarios, you'd typically have your vector store already indexed and simply connect SimpleRAGRetrieve to it.

The Architecture

Here's what we're building:

┌─────────────────────────────────────────────────────┐
│  Customer Query: "Need laptop for video editing"    │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│  Product Specialist Agent (with RAG tool)           │
│  ↓                                                   │
│  Task 1: Search Knowledge Base                      │
│  Task 2: Provide Recommendation                     │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│  Vector Store (8 Tech Products)                     │
│  • Embeddings with OpenAI                           │
│  • Semantic search with metadata                    │
└─────────────────────────────────────────────────────┘

Understanding the Two Phases

This example demonstrates both phases of a RAG system:

Phase 1: Indexing (Setup - Usually done once)

Transform raw data into documents
Split documents into chunks with RAGToolkit
Generate embeddings
Store in vector database

Phase 2: Retrieval (Runtime - Every query)

User asks a question
SimpleRAGRetrieve converts question to embedding
Searches vector store for similar chunks
LLM generates answer from retrieved context

Key Point: In production, Phase 1 might happen in a separate ETL pipeline or background job. Your application using SimpleRAGRetrieve only does Phase 2, connecting to an already-indexed vector store.

Step 1: Setup & Installation

First, install the necessary packages:

npm install kaibanjs @kaibanjs/tools @langchain/openai langchain

You'll need an OpenAI API key for embeddings and LLM capabilities.

Step 2: Prepare Your Data

Demo Note: For this tutorial, we're using mocked data to demonstrate the complete RAG pipeline from start to finish. This lets you see how data flows from raw information → indexing → retrieval. In real applications, you'd typically connect SimpleRAGRetrieve to an already-indexed vector store (Pinecone, Supabase, etc.) without needing the indexing code.

Let's create a product catalog. Each product has rich metadata for better retrieval:

const sampleData = [
  {
    id: 1,
    name: 'UltraBook Pro 15',
    category: 'Laptop',
    content:
      'The UltraBook Pro 15 is a premium laptop featuring a 15.6-inch 4K display, Intel i9 processor, 32GB RAM, and 1TB NVMe SSD. Perfect for professional work, video editing, and gaming. Battery life up to 12 hours.',
    price: 2499,
    specs: ['Intel i9', '32GB RAM', '1TB SSD', '4K Display'],
    inStock: true
  },
  {
    id: 2,
    name: 'SmartPhone X12',
    category: 'Smartphone',
    content:
      'The SmartPhone X12 features a 6.7-inch OLED display, triple camera system with 108MP main sensor, 5G connectivity, and 5000mAh battery.',
    price: 999,
    specs: ['6.7" OLED', '108MP Camera', '5G', '5000mAh'],
    inStock: true
  }
  // ... more products
];

Step 3: Initialize Vector Store with RAGToolkit

One of KaibanJS's superpowers is the RAGToolkit - a utility that simplifies the indexing process for documents and vector stores:

import { OpenAIEmbeddings } from '@langchain/openai';
import { MemoryVectorStore } from 'langchain/vectorstores/memory';
import { RAGToolkit } from '@kaibanjs/tools';

// Create shared embeddings (works with ANY LangChain embeddings!)
const sharedEmbeddings = new OpenAIEmbeddings({
  apiKey: process.env.OPENAI_API_KEY
});

// Create vector store
const sharedVectorStore = new MemoryVectorStore(sharedEmbeddings);

// RAGToolkit makes it easy to add and index documents
const ragToolkit = new RAGToolkit({
  embeddings: sharedEmbeddings,
  vectorStore: sharedVectorStore,
  chunkOptions: {
    chunkSize: 500, // Size of text chunks for indexing
    chunkOverlap: 100 // Overlap to maintain context during indexing
  },
  env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY }
});

Important: The chunkOptions here configure how documents are split during the indexing process. This is different from retrieval options - we're setting up how the data gets stored in the vector database.

Pro Tip: You can swap MemoryVectorStore with Pinecone, Supabase, Chroma, or any other LangChain-compatible vector store. That's the power of compatibility! 🚀

Step 4: Load Documents into Vector Store

const initializeVectorStore = async () => {
  // Transform products into documents with metadata
  const documents = sampleData.map(item => ({
    source: item.content,
    type: 'string',
    metadata: {
      id: item.id,
      name: item.name,
      category: item.category,
      price: item.price,
      specs: item.specs,
      inStock: item.inStock,
      // Combined text for better semantic search
      fullText: `${item.name} ${item.category} ${
        item.content
      } ${item.specs.join(' ')}`
    }
  }));

  await ragToolkit.addDocuments(documents);
  console.log('✅ Vector store initialized with product knowledge base');
};

// Call this when your app starts
await initializeVectorStore();

Step 5: Create the SimpleRAGRetrieve Tool

Now comes the magic - configure the RAG retrieval tool:

import { SimpleRAGRetrieve } from '@kaibanjs/tools';

const productKnowledgeBaseTool = new SimpleRAGRetrieve({
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  vectorStore: sharedVectorStore, // Our pre-indexed vector store
  embeddings: sharedEmbeddings, // Same embeddings used for indexing
  retrieverOptions: {
    k: 4, // Retrieve top 4 most relevant documents
    searchType: 'similarity' // Can also use 'mmr' for diversity
  }
});

🎛️ Understanding the Retrieval Configuration

retrieverOptions - How documents are retrieved from the vector store

k: Number of documents to retrieve (more = more context, but slower)
searchType:
- 'similarity': Find most similar documents (best for factual queries)
- 'mmr': Maximal Marginal Relevance (adds diversity, good for comparisons)
scoreThreshold: Minimum similarity score (0-1, filters low-quality matches)
filter: Metadata filters (e.g., { category: 'Laptop', inStock: true })

Step 6: Create the AI Agent

import { Agent, Task, Team } from 'kaibanjs';

const productSpecialist = new Agent({
  name: 'Product Specialist',
  role: 'Technology Product Expert',
  goal: 'Help customers find the right products by searching our knowledge base',
  background:
    'Expert in technology products with deep knowledge of specs and use cases',
  tools: [productKnowledgeBaseTool] // Give agent the RAG tool
});

Step 7: Define Tasks

Create a workflow with multiple tasks:

// Task 1: Search for relevant products
const searchProductTask = new Task({
  description: `Search our product knowledge base to answer: {customerQuery}

  Focus on finding accurate product information including specifications, features, prices, and availability.`,
  expectedOutput:
    'Detailed product information that directly addresses the customer query',
  agent: productSpecialist
});

// Task 2: Provide recommendations
const recommendationTask = new Task({
  description: `Based on the product information found, provide a helpful recommendation.

  Customer's question: {customerQuery}

  If comparing products, highlight key differences. If seeking recommendations, suggest the best option.`,
  expectedOutput:
    'A clear recommendation that helps the customer make an informed decision',
  agent: productSpecialist
});

Step 8: Assemble the Team

const team = new Team({
  name: 'Product Support Team',
  agents: [productSpecialist],
  tasks: [searchProductTask, recommendationTask],
  inputs: {
    customerQuery:
      'I need a laptop for video editing and gaming. What do you recommend?'
  },
  env: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY
  }
});

// Start the team!
await team.start();

🎯 Advanced Configurations

Using Pinecone for Production

For production systems, use a managed vector database like Pinecone:

import { PineconeStore } from '@langchain/pinecone';
import { Pinecone } from '@pinecone-database/pinecone';

const pinecone = new Pinecone({
  apiKey: process.env.PINECONE_API_KEY
});

const pineconeIndex = pinecone.Index('products-index');
const vectorStore = await PineconeStore.fromExistingIndex(sharedEmbeddings, {
  pineconeIndex
});

// Use this vector store with SimpleRAGRetrieve
const tool = new SimpleRAGRetrieve({
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  vectorStore: vectorStore,
  embeddings: embeddings,
  retrieverOptions: {
    k: 4,
    searchType: 'mmr', // More diverse results
    scoreThreshold: 0.7 // Only high-quality matches
  }
});

Real-World Scenario: In production, you'd typically have your Pinecone index already populated with data (maybe thousands or millions of documents). Your application would just connect to it and start retrieving - no indexing code needed in your retrieval service!

// In a real app, you just connect to existing index
const existingVectorStore = await PineconeStore.fromExistingIndex(embeddings, {
  pineconeIndex
});

// SimpleRAGRetrieve queries the pre-indexed data
const retriever = new SimpleRAGRetrieve({
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  vectorStore: existingVectorStore,
  embeddings: embeddings
});

Custom Embeddings

Swap OpenAI embeddings for other providers:

// Cohere embeddings
import { CohereEmbeddings } from '@langchain/cohere';
const embeddings = new CohereEmbeddings({
  apiKey: process.env.COHERE_API_KEY,
  model: 'embed-english-v3.0'
});

// HuggingFace embeddings
import { HuggingFaceInferenceEmbeddings } from '@langchain/community/embeddings/hf';
const embeddings = new HuggingFaceInferenceEmbeddings({
  apiKey: process.env.HUGGINGFACE_API_KEY,
  model: 'sentence-transformers/all-MiniLM-L6-v2'
});

🔍 Why This Approach Rocks

1. LangChain.js Compatibility

SimpleRAGRetrieve works with the entire LangChain.js ecosystem:

Embeddings: OpenAI, Cohere, HuggingFace, Anthropic
Vector Stores: Pinecone, Supabase, Chroma, Qdrant, Weaviate
LLMs: Any LangChain-compatible model

2. Flexible Chunking Strategies (via RAGToolkit)

Control how your documents are split during indexing with RAGToolkit:

// For technical documentation (more context per chunk)
const ragToolkit = new RAGToolkit({
  embeddings,
  vectorStore,
  chunkOptions: { chunkSize: 1000, chunkOverlap: 200 }
});

// For short product descriptions (smaller, precise chunks)
const ragToolkit = new RAGToolkit({
  embeddings,
  vectorStore,
  chunkOptions: { chunkSize: 300, chunkOverlap: 50 }
});

// For legal documents (maintain maximum context)
const ragToolkit = new RAGToolkit({
  embeddings,
  vectorStore,
  chunkOptions: { chunkSize: 1500, chunkOverlap: 300 }
});

3. Configurable Retrieval

Fine-tune how documents are retrieved:

retrieverOptions: {
  k: 10,                    // Get more options
  searchType: 'mmr',        // Diverse results
  scoreThreshold: 0.8,      // High quality only
  filter: {                 // Metadata filtering
    category: 'Laptop',
    inStock: true,
    price: { $lte: 2000 }
  }
}

4. Multi-Agent Workflows

Combine multiple agents with different RAG tools:

const searchAgent = new Agent({ tools: [productRAG] });
const pricingAgent = new Agent({ tools: [pricingRAG] });
const reviewAgent = new Agent({ tools: [reviewRAG] });

// Agents collaborate on tasks!

Real-World Use Cases

This pattern works for:

📚 Documentation Search - Help users find answers in docs
🛍️ E-commerce - Product recommendations and comparisons
🎓 Educational Platforms - Course recommendations based on learning goals
💼 Customer Support - Answer questions from knowledge bases
🏥 Healthcare - Search medical literature and guidelines
⚖️ Legal - Find relevant cases and regulations

Performance Tips

Start with MemoryVectorStore for development, migrate to Pinecone/Supabase for production
Adjust k based on your use case: 3-5 for specific answers, 10+ for comprehensive research
Use scoreThreshold to filter out irrelevant results
Metadata filtering is faster than semantic search - combine both!
Monitor token usage - larger chunks = more tokens sent to LLM
Separate indexing from retrieval: Index once (with RAGToolkit), retrieve many times (with SimpleRAGRetrieve)

The SimpleRAGRetrieve Philosophy

Separation of Concerns:

Indexing Tools (like RAGToolkit): Handle document processing, chunking, embedding generation, and storage
Retrieval Tools (like SimpleRAGRetrieve): Focus solely on searching and retrieving from pre-indexed data

This separation means:

✅ Your retrieval service stays lightweight and fast
✅ You can update the index independently without changing retrieval logic
✅ Multiple applications can share the same indexed knowledge base
✅ Easier to scale - indexing and retrieval can run on different infrastructure

When to use SimpleRAGRetrieve:

✅ You have an existing Pinecone/Supabase/Chroma index
✅ Your data is already embedded and stored
✅ You need to add RAG capabilities to AI agents
✅ You want a production-ready retrieval solution

When you might need a different tool:

❌ You need to handle both indexing and retrieval in one tool (use SimpleRAG instead)
❌ You're doing one-off queries with fresh content each time

What's Next?

Conclusion

Building intelligent RAG systems doesn't have to be complex. With KaibanJS and SimpleRAGRetrieve, you get:

✅ Pre-configured RAG pipeline

✅ LangChain.js compatibility for any provider

✅ Flexible configuration options

✅ Multi-agent collaboration capabilities

The full code example shows how to build a production-ready product knowledge base in less than 200 lines of code. That's the power of the right abstractions!

Try it out and let me know what you build! Drop a comment with your use case below 👇

Tags: #javascript #ai #rag #langchain #agents #kaibanjs #openai #vectorsearch #semanticsearch

Found this helpful? Follow me for more AI agent tutorials and JavaScript tips!

Building Interoperable AI Agents: A2A Protocol + KaibanJS Integration

Dariel Vila — Thu, 25 Sep 2025 14:31:14 +0000

The Problem with Current AI Agent Systems

If you've worked with AI agents, you know the pain: each framework has its own way of doing things. Want to connect a LangChain agent with a CrewAI agent? Good luck. Need to integrate agents from different vendors? Prepare for a lot of custom integration work.

The A2A (Agent-to-Agent) Protocol solves this by providing a standardized communication layer that lets any agent talk to any other agent, regardless of the underlying framework.

In this post, I'll show you how to integrate the A2A Protocol with KaibanJS to create truly interoperable multi-agent systems.

What is the A2A Protocol?

The A2A Protocol is an open standard that defines how AI agents should communicate. Think of it as HTTP for AI agents - it provides:

Standardized message formats - All agents speak the same language
Real-time streaming - Live updates and status notifications
Multi-modal support - Text, audio, video communication
Security - Built-in authentication and validation
Vendor agnostic - Works with any framework

What is KaibanJS?

KaibanJS is a multi-agent orchestration framework that makes it easy to create teams of specialized AI agents. Instead of building monolithic agents, you can create:

Specialized agents with specific roles and capabilities
Task workflows that coordinate multiple agents
Real-time monitoring of agent collaboration
Tool integration with external APIs

The Architecture

Here's how our integration works:

User Query → A2A Protocol → Express Server → KaibanJS Team → Results
     ↑                                                           ↓
     └─────────────── Real-time Streaming ←──────────────────────┘

The key insight is that we use the A2A Protocol as the communication layer, while KaibanJS handles the actual multi-agent orchestration.

Implementation Walkthrough

1. Setting Up the Agent Card

First, we define what our agent can do using an Agent Card:

// server/src/agent-card.ts
export const kaibanjsAgentCard: AgentCard = {
  name: 'Kaibanjs Research Agent',
  description:
    'Research topics using web search and generate comprehensive summaries',
  version: '1.0.0',
  protocolVersion: '1.0.0',
  url: process.env.BASE_URL || 'http://localhost:4000',
  preferredTransport: 'JSONRPC',
  capabilities: {
    streaming: true, // We support real-time updates
    pushNotifications: false,
    stateTransitionHistory: true
  },
  defaultInputModes: ['text/plain'],
  defaultOutputModes: ['text/plain'],
  skills: [
    {
      id: 'research',
      name: 'Research and Summarization',
      description:
        'Research topics using web search and generate comprehensive summaries',
      tags: ['research', 'summarization', 'web-search', 'ai'],
      examples: [
        'What are the latest developments in AI?',
        'Summarize the current state of renewable energy'
      ]
    }
  ]
};

2. Creating the KaibanJS Team

Next, we define our multi-agent team:

// server/src/kaibanjs-team.ts
import { Agent, Task, Team } from 'kaibanjs';
import { TavilySearchResults } from '@langchain/community/tools/tavily_search';

// Define tools
const searchTool = new TavilySearchResults({
  maxResults: 3,
  apiKey: process.env.TAVILY_API_KEY
});

// Create specialized agents
const searchAgent = new Agent({
  name: 'Scout',
  role: 'Information Gatherer',
  goal: 'Find up-to-date information about the given query.',
  background: 'Research',
  type: 'ReactChampionAgent',
  tools: [searchTool]
});

const contentCreator = new Agent({
  name: 'Writer',
  role: 'Content Creator',
  goal: 'Generate a comprehensive summary of the gathered information.',
  background: 'Journalism',
  type: 'ReactChampionAgent',
  tools: []
});

// Define tasks
const searchTask = new Task({
  description: `Search for detailed information about: {query}. Current date: {currentDate}.`,
  expectedOutput:
    'Detailed information about the topic with key facts and relevant details.',
  agent: searchAgent
});

const summarizeTask = new Task({
  description: `Using the gathered information, create a comprehensive summary.`,
  expectedOutput:
    'A well-structured summary with key points and main findings.',
  agent: contentCreator
});

// Team factory function
export function createKaibanjsTeam(query: string) {
  const currentDate = new Date().toLocaleDateString('en-US', {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  });

  return new Team({
    name: 'Research and Summary Team',
    agents: [searchAgent, contentCreator],
    tasks: [searchTask, summarizeTask],
    inputs: { query, currentDate },
    env: {
      OPENAI_API_KEY: process.env.OPENAI_API_KEY || '',
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY || ''
    }
  });
}

3. The A2A Protocol Bridge

This is where the magic happens - we bridge A2A Protocol messages with KaibanJS workflows:

// server/src/agent-executor.ts
export class KaibanjsAgentExecutor implements AgentExecutor {
  public async execute(
    requestContext: RequestContext,
    eventBus: ExecutionEventBus
  ): Promise<void> {
    const { taskId, contextId, userMessage } = requestContext;

    try {
      // Extract query from A2A message
      const query = userMessage.parts
        .filter((part: Part) => part.kind === 'text')
        .map((part: Part) => (part as any).text)
        .join(' ');

      if (!query.trim()) {
        throw new Error('No query provided in message');
      }

      // Start the task
      eventBus.publish({
        kind: 'status-update',
        taskId,
        contextId,
        status: { state: 'working', timestamp: new Date().toISOString() },
        final: false
      });

      // Create KaibanJS team
      const team = createKaibanjsTeam(query);
      const useTeamStore = team.useStore();

      // Subscribe to workflow logs for real-time streaming
      const unsubscribe = useTeamStore.subscribe(state => {
        const { workflowLogs } = state;

        workflowLogs.forEach(log => {
          if (log) {
            let logMessage = '';

            if (log.logType === 'TaskStatusUpdate') {
              logMessage = `Task Status: ${log.taskStatus}`;
            } else if (log.logType === 'AgentStatusUpdate') {
              logMessage = `Agent Status: ${log.agentStatus}`;
            } else if (log.logType === 'WorkflowStatusUpdate') {
              logMessage = `Workflow Status: ${log.workflowStatus}`;
            }

            if (logMessage) {
              // Stream workflow updates via A2A Protocol
              eventBus.publish({
                kind: 'artifact-update',
                taskId,
                contextId,
                artifact: {
                  artifactId: `log-${Date.now()}`,
                  parts: [{ kind: 'text', text: log.logDescription }],
                  metadata: {
                    timestamp: new Date().toISOString(),
                    logType: log.logType,
                    logMessage
                  }
                }
              });
            }
          }
        });
      });

      // Execute the team workflow
      await team.start();

      // Wait for final logs
      await new Promise(resolve => setTimeout(resolve, 1000));

      // Get final result
      const finalState = useTeamStore.getState();
      const finalResult = finalState.workflowResult;

      // Send final result
      if (finalResult) {
        eventBus.publish({
          kind: 'artifact-update',
          taskId,
          contextId,
          artifact: {
            artifactId: `result-${taskId}`,
            parts: [
              { kind: 'text', text: JSON.stringify(finalResult, null, 2) }
            ],
            metadata: {
              timestamp: new Date().toISOString(),
              type: 'final-result'
            }
          }
        });
      }

      // Complete the task
      eventBus.publish({
        kind: 'status-update',
        taskId,
        contextId,
        status: { state: 'completed', timestamp: new Date().toISOString() },
        final: true
      });

      unsubscribe();
    } catch (error) {
      // Handle errors gracefully
      eventBus.publish({
        kind: 'artifact-update',
        taskId,
        contextId,
        artifact: {
          artifactId: `error-${taskId}`,
          parts: [{ kind: 'text', text: `Error: ${error.message}` }],
          metadata: { timestamp: new Date().toISOString(), type: 'error' }
        }
      });

      eventBus.publish({
        kind: 'status-update',
        taskId,
        contextId,
        status: { state: 'failed', timestamp: new Date().toISOString() },
        final: true
      });
    } finally {
      eventBus.finished();
    }
  }
}

4. Client-Side Integration

The React client shows how to consume A2A Protocol streams:

// client/src/stores/a2a-store.ts
export const useA2AStore = create<A2AState>((set, get) => ({
  // ... other state

  sendQuery: async (query: string) => {
    const { client, isConnected } = get();

    if (!client || !isConnected) {
      set({ error: 'Not connected to A2A server' });
      return;
    }

    set({ query, isProcessing: true, error: null, result: null });

    try {
      const streamParams: MessageSendParams = {
        message: {
          messageId: uuidv4(),
          role: 'user',
          parts: [{ kind: 'text', text: query }],
          kind: 'message'
        }
      };

      get().addLog('status', `Sending query: "${query}"`);

      const stream = client.sendMessageStream(streamParams);
      let finalResult = '';

      for await (const event of stream) {
        if (event.kind === 'task') {
          get().addLog('status', `Task created: ${event.id}`);
        } else if (event.kind === 'status-update') {
          get().addLog('status', `Status: ${event.status.state}`);

          if (event.status.state === 'completed') {
            set({ isProcessing: false });
          } else if (event.status.state === 'failed') {
            set({ isProcessing: false, error: 'Task failed' });
          }
        } else if (event.kind === 'artifact-update') {
          // Handle real-time workflow logs
          const textParts = event.artifact.parts.filter(
            part => part.kind === 'text'
          );
          const content = textParts.map(part => (part as any).text).join('\n');

          get().addLog('artifact', content, event.artifact.metadata);

          // Check if this is a final result
          if (event.artifact.artifactId.startsWith('result-')) {
            finalResult = content;
          }
        }
      }

      set({ result: finalResult });
      get().addLog('status', 'Stream completed');
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : 'Query failed';
      set({ error: errorMessage, isProcessing: false });
      get().addLog('error', errorMessage);
    }
  }
}));

Key Integration Points

1. Message Flow

User Query → A2A Message → Agent Executor → KaibanJS Team → Workflow Logs → A2A Artifacts → Client

2. Real-time Streaming

The integration streams KaibanJS workflow logs as A2A Protocol artifacts:

// Stream workflow updates
workflowLogs.forEach(log => {
  eventBus.publish({
    kind: 'artifact-update',
    taskId,
    contextId,
    artifact: {
      artifactId: `log-${Date.now()}`,
      parts: [{ kind: 'text', text: log.logDescription }],
      metadata: {
        logType: log.logType,
        logMessage: `Agent Status: ${log.agentStatus}`
      }
    }
  });
});

3. Error Handling

Robust error handling ensures the A2A Protocol contract is maintained:

catch (error) {
  // Send error as artifact
  eventBus.publish({
    kind: 'artifact-update',
    taskId,
    contextId,
    artifact: {
      artifactId: `error-${taskId}`,
      parts: [{ kind: 'text', text: `Error: ${error.message}` }],
      metadata: { timestamp: new Date().toISOString(), type: 'error' }
    }
  });

  // Mark task as failed
  eventBus.publish({
    kind: 'status-update',
    taskId,
    contextId,
    status: { state: 'failed', timestamp: new Date().toISOString() },
    final: true
  });
}

Why This Matters

1. Universal Interoperability

Your KaibanJS agents can now communicate with any A2A-compliant agent. No more vendor lock-in or custom integration work.

2. Real-time Visibility

Users can see exactly what's happening inside your multi-agent system as it processes their requests.

3. Standardized Communication

All agents speak the same language, making it easier to build complex agent networks.

Getting Started

Prerequisites

Node.js 18+
API keys for OpenAI and Tavily
Basic TypeScript/React knowledge

Quick Setup

# Clone the repository
git clone https://github.com/kaiban-ai/a2a-protocol-kaibanjs-demo

# Install dependencies
npm run install:all

# Configure environment variables
cp server/env.example server/.env
# Add your API keys to server/.env

# Start the development servers
npm run dev

Try It Out

Open http://localhost:5173
Click "Connect to Server"
Enter a research query
Watch the real-time logs
See the final results

Live Demo

Check out the live demo: A2A Protocol Integration Demo

Demo Video

See the A2A Protocol integration with KaibanJS in action - Watch agents collaborate in real-time

What's Next?

This integration opens up exciting possibilities:

Cross-platform agent networks - Connect agents from different frameworks
Enterprise agent orchestration - Scale agent systems across organizations
Multi-modal communication - Add audio and video capabilities
Open ecosystem - Contribute to the evolution of agent standards

Resources

Repository: A2A Protocol KaibanJS Demo
Live Demo: A2A Protocol Integration Demo
Demo Video: Watch the Integration in Action
KaibanJS Docs: kaibanjs.com
A2A Protocol: A2A Project

Have you worked with multi-agent systems before? What challenges have you faced with agent interoperability? Let me know in the comments!

Building AI-Powered Airline Revenue Management Systems with KaibanJS: A Developer's Guide

Dariel Vila — Thu, 11 Sep 2025 22:38:10 +0000

🚀 TL;DR

Ever wondered how airlines optimize their pricing strategies across thousands of routes daily? In this deep-dive, we'll explore how to build a multi-agent AI system using KaibanJS that standardizes revenue management decisions. We'll walk through real code, tackle the challenges of inconsistent analyst decisions, and show you how to create intelligent agents that work together seamlessly.

🎯 The Problem: Why Airlines Need AI Agents

Picture this: You're a revenue management analyst at a major airline. Every day, you're making pricing decisions that can impact millions in revenue. But here's the catch - every analyst approaches these decisions differently.

// The inconsistent reality 😅
const analystDecisions = {
  juniorAnalyst: "Let's decrease fares by 15% to fill seats",
  seniorAnalyst: 'Hold steady, demand looks stable',
  veteranAnalyst: "Increase by 8% - I've seen this pattern before"
};

This inconsistency leads to:

Missed revenue opportunities 💸
Suboptimal pricing strategies 📉
Knowledge silos 🏝️
Training gaps 📚

💡 The Solution: Multi-Agent Architecture

Enter KaibanJS - a JavaScript framework that lets you build sophisticated multi-agent systems. Instead of relying on individual analyst intuition, we create specialized AI agents that work together to ensure consistent, data-driven decisions.

Our Agent Dream Team 🦸‍♂️

import { Agent, Task, Team } from 'kaibanjs';

// 🧠 The Brain - Best Practice Recommendations Agent
const bestPracticeRecommendationsAgent = new Agent({
  name: 'Best Practice Recommendations Agent',
  role: 'Pricing Strategy Specialist',
  goal: 'Suggest optimal pricing actions based on airline policy, market data and proven strategies, following the specific instructions for fare analysis.',
  background:
    'Expert pricing strategist with deep knowledge of airline revenue management best practices, competitive analysis, and fare optimization. Specializes in applying standardized decision-making frameworks to ensure consistent recommendations.',
  tools: [new PricingSystemIntegrationTool()]
});

// 🔍 The Quality Guardian - Automated Quality Checks Agent
const automatedQualityChecksAgent = new Agent({
  name: 'Automated Quality Checks Agent',
  role: 'Compliance and Risk Specialist',
  goal: 'Review proposed pricing actions for compliance and consistency, flagging deviations or risks before implementation.',
  background:
    'Compliance and risk management expert with expertise in airline pricing policies, regulatory requirements, and quality assurance processes. Specializes in automated validation and risk assessment.',
  tools: [new NotificationTool()]
});

🛠️ Building the Core Recommendation Engine

The heart of our system is the recommendation generation task. This is where the magic happens - we encode years of airline revenue management expertise into a structured, rule-based system.

const generateRecommendationsTask = new Task({
  title: 'Best Practice Recommendations',
  description: `Generate fare recommendations following the EXACT instructions from the analysis guidelines:

    INSTRUCTION 1: Demand Trend Analysis (PRIORITY RULE)
    - If Demand Trend = INCREASING: Limit fare changes to maximum 5% (conservative approach for growing demand)
    - If Demand Trend = DECREASING: Set fare equal to Competitor Median Price (competitive positioning)
    - If Demand Trend = STABLE: Apply standard rules below

    INSTRUCTION 2: Competitor Analysis
    - Compare Model Fare against competitor median pricing
    - If significantly below market (>$50 gap): Recommend fare increase to 95% of competitor median
    - If significantly above market (>$100 gap): Recommend fare decrease to 102% of competitor median

    INSTRUCTION 3: Load Factor Optimization
    - If Load Factor > 0.8 (HIGH): Recommend 5% fare increase
    - If Load Factor < 0.6 (LOW): Recommend 5% fare decrease

    INSTRUCTION 4: Special Events Consideration
    - If special event includes "festival" or "tournament": Recommend 8% fare increase
    - If special event includes "competitor": Recommend 8% fare decrease

    INSTRUCTION 5: Weekday Pricing Adjustment
    - If WeekDay = 5, 6, or 7 (Weekend): Premium pricing justified, can be above competitor median
    - If WeekDay = 1-4 (Weekday): Competitive pricing required, should align with or be below competitor median

    INSTRUCTION 6: Calculate and Flag Changes
    - Calculate percentage change: ((AI Suggested Fare - Model Fare) / Model Fare) * 100
    - If change > 10%: Flag as SIGNIFICANT_CHANGE requiring management approval
    - If change ≤ 10%: Mark as standard recommendation

    Apply these rules in order of priority, with Demand Trend taking precedence over other factors.`,
  expectedOutput: `Structured fare recommendation output in the following EXACT format:

    ## FARE RECOMMENDATION SUMMARY

    **Route:** [Origin-Destination]
    **Analysis Date:** [Date]
    **Current Model Fare:** $[Amount]

    ### RECOMMENDATION DETAILS

    **AI Suggested Fare:** $[Calculated Amount]
    **% change vs Model:** [Percentage]% [↑/↓]
    **AI Justification:** [Detailed justification following instruction format]

    ### SIGNIFICANCE FLAGS

    **Change Magnitude:** [STANDARD/SIGNIFICANT_CHANGE]
    **Approval Required:** [YES/NO]
    **Priority Level:** [HIGH/MEDIUM/LOW]
    **Risk Assessment:** [LOW/MEDIUM/HIGH]

    ### SUPPORTING DATA

    **Competitor Median:** $[Amount]
    **Load Factor:** [Value] ([HIGH/MEDIUM/LOW])
    **Demand Trend:** [INCREASING/DECREASING/STABLE]
    **WeekDay:** [Day Number] ([Weekend/Weekday])
    **Special Events:** [Event details or "None"]
    **Market Position:** [BELOW_MARKET/AT_MARKET/ABOVE_MARKET]

    Ensure all calculations are accurate and justifications follow the exact instruction format.`,
  agent: bestPracticeRecommendationsAgent
});

🏗️ Assembling the Team

Now let's bring everything together into a cohesive team that can handle complex revenue management workflows:

const team = new Team({
  name: 'Standardized Revenue Management Analysis Team',
  agents: [
    guidedDataAnalysisAgent,
    bestPracticeRecommendationsAgent,
    automatedQualityChecksAgent,
    continuousLearningAgent
  ],
  tasks: [
    collectRouteDataTask,
    performGuidedAnalysisTask,
    generateRecommendationsTask,
    performQualityChecksTask,
    captureKnowledgeTask,
    generateSummaryTask
  ],
  inputs: {
    origin: 'LHR',
    destination: 'SLC',
    analysisDate: '2026-06-03'
  },
  env: {
    OPENAI_API_KEY:
      import.meta.env.VITE_OPENAI_API_KEY || 'YOUR_OPENAI_API_KEY_HERE'
  }
});

export default team;

🎯 Why This Architecture Rocks

1. Consistency Across All Analysts ✅

// Before: Inconsistent decisions
const before = {
  analyst1: 'Increase fare by 5%',
  analyst2: 'Decrease fare by 10%',
  analyst3: 'Keep current fare'
};

// After: Standardized AI-driven decisions
const after = {
  aiAgent:
    'Increase fare by 3.2% based on competitor median ($642) and high load factor (0.71)'
};

2. Automated Quality Gates 🛡️

Every recommendation goes through automated compliance checks:

Fare validation (>$0 and <$10,000)
Business rule compliance (max 50% change)
Risk assessment (flags changes >20% as high risk)
Approval workflow automation

3. Continuous Learning Loop 🧠

The system captures outcomes and improves over time:

const learningCycle = {
  capture: 'Store analysis results and outcomes',
  analyze: 'Identify successful patterns and failures',
  update: 'Refine best practices and rules',
  share: 'Distribute learnings across the team'
};

🚀 Getting Your Hands Dirty

Prerequisites

npm install kaibanjs

Environment Setup

// .env file
VITE_OPENAI_API_KEY = your_openai_api_key_here;

Running the System

import team from './revenue-management-analysis.team.kban.js';

// Execute the team workflow
const results = await team.execute({
  origin: 'LHR',
  destination: 'SLC',
  analysisDate: '2026-06-03'
});

console.log('Revenue Management Analysis Complete:', results);

📊 Real-World Impact Metrics

When implemented, this system delivers:

Revenue Uplift: 3-8% increase in average fare optimization
Decision Speed: 75% faster pricing decisions
Consistency: 95% reduction in pricing variance across analysts
Risk Reduction: 60% fewer pricing errors requiring correction

🔧 Customization Opportunities

The beauty of KaibanJS is its flexibility. You can easily:

Add New Agents

const marketIntelligenceAgent = new Agent({
  name: 'Market Intelligence Agent',
  role: 'Market Research Specialist',
  goal: 'Analyze market trends and competitor behavior patterns'
  // ... configuration
});

Extend Business Rules

const customPricingRules = {
  seasonalAdjustment: 'Apply 12% premium during holiday seasons',
  routeSpecificRules: 'Premium routes get 5% higher margins',
  customerSegmentRules: 'Business travelers accept 15% premium'
};

Integrate External APIs

const weatherImpactTool = new Tool({
  name: 'weather_impact_analysis',
  description: 'Analyze weather impact on demand and pricing',
  schema: z.object({
    route: z.string(),
    weatherCondition: z.string(),
    impactLevel: z.enum(['LOW', 'MEDIUM', 'HIGH'])
  })
});

🎉 The Developer Experience

What makes KaibanJS special for developers:

Type Safety 🔒

import { z } from 'zod';

const pricingSchema = z.object({
  currentFare: z.number().positive(),
  recommendedFare: z.number().positive(),
  justification: z.string().min(10)
});

Hot Reloading ⚡

// Changes to agent configurations are reflected immediately
const agent = new Agent({
  // Update this and see changes instantly
  goal: 'Updated goal based on new business requirements'
});

Comprehensive Logging 📝

// Built-in logging for debugging and monitoring
console.log('Agent execution trace:', agent.getExecutionTrace());
console.log('Task performance metrics:', task.getMetrics());

🚨 Common Pitfalls & Solutions

Pitfall 1: Over-Complex Rules

// ❌ Too complex
const complexRule =
  'If demand > 0.8 AND competitor < model AND weekday = weekend AND weather = good AND season = peak THEN increase by 12.5%';

// ✅ Clear and maintainable
const simpleRule = 'If demand trend = INCREASING: Limit changes to 5%';

Pitfall 2: Ignoring Edge Cases

// Always handle edge cases
const safeCalculation = (currentFare, recommendedFare) => {
  if (currentFare <= 0) throw new Error('Invalid current fare');
  if (recommendedFare <= 0) throw new Error('Invalid recommended fare');

  return ((recommendedFare - currentFare) / currentFare) * 100;
};

🔮 What's Next?

The future of revenue management with KaibanJS:

Real-time Market Adaptation: Agents that adjust pricing every hour
Predictive Analytics: ML models that forecast demand 30 days ahead
Cross-Airline Intelligence: Shared learning across airline partnerships
Customer Personalization: Dynamic pricing based on individual traveler behavior

🎯 Key Takeaways

Multi-agent systems solve complex business problems by breaking them into specialized, manageable components
KaibanJS provides a clean, developer-friendly framework for building these systems
Consistency in decision-making can be achieved through well-designed AI agent workflows
Real-world impact is measurable and significant when properly implemented

📚 Resources & Next Steps

Ready to dive deeper? Check out the complete implementation:

🔗 KaibanJS Multi-Agent Revenue Management Example

Additional Resources:

Note: This example uses mock data for demonstration purposes. In production, integrate with your airline's data systems for real-time analysis.

Have you built similar multi-agent systems? Share your experiences in the comments below! Let's discuss the challenges and opportunities in AI-powered business automation. 🚀

JavaScript catches up: 4 modern frameworks for multi-agent LLM orchestration

Dariel Vila — Thu, 28 Aug 2025 12:57:39 +0000

The rapid rise of LLM-powered agents has brought new attention to how we orchestrate complex, multi-agent systems—especially in AI-heavy domains like task automation, assistant chaining, and tool-based reasoning.

For a while, Python had a clear head start in this space. Frameworks like LangChain, CrewAI, and LangGraph made it the go-to choice for prototyping multi-agent architectures. But while Python remains dominant in research and backend experimentation, JavaScript has been catching up—fast.

In the past year, several JavaScript-native frameworks have emerged with serious capabilities: modular agent design, message-passing, memory, RAG support, and even live orchestration UIs.

These tools now offer everything needed to build:

Autonomous LLM-driven agents
Workflow engines with shared state
Interactive agent-task boards
Dev-friendly experiences for browser, Node.js, and edge runtimes

This article compares four of the most promising frameworks shaping the JavaScript multi-agent ecosystem:

LangGraph.js – the JavaScript adaptation of LangGraph's powerful graph model
Mastra – TypeScript-native pipelines for AI-native apps
AutogenJS – a lightweight agent chat model for quick experimentation
KaibanJS – a Kanban-style, role-driven orchestration system with a visual playground

LangGraph.js

Type: Graph-based, stateful agent orchestration
Language: JavaScript / TypeScript
GitHub: langchain-ai/langgraphjs
Best for: Complex workflows with branching logic and long-term state tracking

LangGraph.js is the JavaScript/TypeScript counterpart of LangGraph (Python). It lets you define agent workflows as graphs, where each node can represent an agent, tool, or memory unit, and edges define execution flow.

It’s part of the broader LangChain ecosystem, offering full integration with streaming, checkpoints, subgraphs, and memory across runs.

Pros

✅ Great for graph-like logic and control

✅ LangChain-compatible

✅ Good for production-grade orchestration with logging and visibility

✅ Dev UI with LangGraph Studio

Cons

❌ Tied to LangChain philosophy and APIs

❌ Higher learning curve (state machines, graph modeling)

Example usage:

// npm install @langchain-anthropic
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatAnthropic } from "@langchain/anthropic";
import { tool } from "@langchain/core/tools";

import { z } from "zod";

const search = tool(
  async ({ query }) => {
    if (
      query.toLowerCase().includes("sf") ||
      query.toLowerCase().includes("san francisco")
    ) {
      return "It's 60 degrees and foggy.";
    }
    return "It's 90 degrees and sunny.";
  },
  {
    name: "search",
    description: "Call to surf the web.",
    schema: z.object({
      query: z.string().describe("The query to use in your search."),
    }),
  }
);

const model = new ChatAnthropic({
  model: "claude-3-7-sonnet-latest",
});

const agent = createReactAgent({
  llm: model,
  tools: [search],
});

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "what is the weather in sf",
    },
  ],
});

Mastra

Type: AI-native pipelines (RAG, toolchains, evaluations)
Language: TypeScript
GitHub: mastra-ai/mastra
Best for: Teams creating custom LLM workflows, retrieval pipelines, and fast evaluation loops

Mastra is a TypeScript-first framework built around the concept of AI-native workflow composition. It focuses on enabling fast development of things like:

Retrieval-Augmented Generation (RAG)
Prompt chains with memory and logging
Evaluation pipelines and testing loops

It’s developer-friendly and flexible, supporting serverless and local runs, and works well for product teams iterating quickly.

Pros

✅ Built-in support for RAG and tool orchestration

✅ Declarative syntax with fast iteration

✅ Excellent for evaluation/test loops

✅ TypeScript native

Cons

❌ Less visual

❌ Pipeline-focused, not agent-first

❌ Still maturing in the community

Example usage:

import { Mastra } from "@mastra/core";
import { summaryClusteringWorkflow } from "./workflows/summaryClusteringWorkflow";
import { topicClusteringAgent } from "./agents/topicClusteringAgent";

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { createGmailTool } from "./tools/gmailTool";

 const emailSummaryAgent = new Agent({
  name: "Email Summary Agent",
  instructions: `Process support emails for an AI video generation SaaS platform. IMPORTANT: Be thorough in identifying categories - if there's ANY indication of these issues, include the email:`,
  model: openai("gpt-4o"),
  tools: {
    gmailTool: createGmailTool({
      clientEmail: process.env.GMAIL_CLIENT_EMAIL || "",
      privateKey: process.env.GMAIL_PRIVATE_KEY || "",
      subject: process.env.GMAIL_SUBJECT || ""
    })
  },
});

// Create and export the Mastra instance
export const mastra = new Mastra({
  agents: {
    emailSummaryAgent,
    topicClusteringAgent
  },
  workflows: {
    summaryClusteringWorkflow
  },
});

OpenAI Agents JS

Type: Plugin-based multi-agent orchestration
Language: JavaScript / TypeScript
GitHub: openai/openai-agents-js
Best for: Agent handoffs, tool integrations, and traceable workflows

OpenAI Agents JS is a lightweight, provider-agnostic JavaScript SDK for orchestrating agents around OpenAI models. It includes abstractions for tool handoffs, conversational memory, safety guards, and built-in tracing.

Pros

Agent orchestration with tool integration and handoffs
Built-in logging, tracing, and error recovery
Extensible middleware and memory system

Cons

Requires OpenAI API access
Minimal visual tooling or UI

Example usage:

import { z } from 'zod';
import { Agent, run, tool } from '@openai/agents';

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({ city: z.string() }),
  execute: async (input) => {
    return `The weather in ${input.city} is sunny`;
  },
});

const agent = new Agent({
  name: 'Data agent',
  instructions: 'You are a data agent',
  tools: [getWeatherTool],
});

async function main() {
  const result = await run(agent, 'What is the weather in Tokyo?');
  console.log(result.finalOutput);
}

main().catch(console.error);

KaibanJS

Type: Kanban-style, modular, role-based orchestration
Language: JavaScript / TypeScript
GitHub: kaiban-ai/kaibanjs
Best for: Visual, role-driven orchestration with board-like task coordination

KaibanJS offers a completely different way to think about multi-agent systems.

Inspired by Kanban boards, it treats agents as roles and tasks as cards that flow through predefined stages. This model makes complex orchestrations easy to reason about, observe, and debug — especially when collaborating agents have different responsibilities.

KaibanJS provides:

A fully interactive Playground to visualize agent flow live
A clear separation of roles/stages/cards for readability
Integration-ready APIs for React, Next.js, and browser apps

Pros

✅ Intuitive, human-readable orchestration model

✅ Built-in observability and agent logs

✅ Playground with live board view

✅ Seamless integration with frontend stacks

✅ Great for LLM agents with tools or async behavior

Cons

❌ Different mental model vs pipelines or graphs

❌ Not designed for RAG pipelines (but can be extended)

🔗 Try the Playground → https://www.kaibanjs.com/playground

Example usage:


import { Agent, Task, Team } from 'kaibanjs';

// Define agents with specific roles and goals
const profileAnalyst = new Agent({
    name: 'Zoe', 
    role: 'Profile Analyst', 
    goal: 'Extract structured information from conversational user input.', 
    background: 'Data Processor',
    tools: []
});

const resumeWriter = new Agent({
    name: 'Alex Mercer', 
    role: 'Resume Writer', 
    goal: `Craft compelling, well-structured resumes 
    that effectively showcase job seekers qualifications and achievements.`,
    background: `Extensive experience in recruiting, 
    copywriting, and human resources, enabling 
    effective resume design that stands out to employers.`,
    tools: []
});

// Define the tasks for each agent
const processingTask = new Task({ 
    description: `Extract relevant details such as name, 
    experience, skills, and job history from the user's 'aboutMe' input. 
    aboutMe: {aboutMe}`,
    expectedOutput: 'Structured data ready to be used for a resume creation.', 
    agent: profileAnalyst
});

const resumeCreationTask = new Task({ 
    description: `Utilize the structured data to create 
    a detailed and attractive resume. 
    Enrich the resume content by inferring additional details from the provided information.
    Include sections such as a personal summary, detailed work experience, skills, and educational background. Please use markdown format for the output.`,
    expectedOutput: `A professionally formatted resume in markdown format, 
    ready for submission to potential employers.`, 
    agent: resumeWriter 
});

// Create and start the team
const team = new Team({
    name: 'Resume Creation Team',
    agents: [profileAnalyst, resumeWriter],
    tasks: [processingTask, resumeCreationTask],
    inputs: { aboutMe: `My name is David Llaca. 
    JavaScript Developer for 5 years. 
    I worked for three years at Disney, 
    where I developed user interfaces for their primary landing pages
    using React, NextJS, and Redux. Before Disney, 
    I was a Junior Front-End Developer at American Airlines, 
    where I worked with Vue and Tailwind. 
    I earned a Bachelor of Science in Computer Science from FIU in 2018, 
    and I completed a JavaScript bootcamp that same year.` },
    env: {OPENAI_API_KEY: 'ENV_OPENAI_API_KEY'}
});

team.start();

🧠 Final Thoughts

Each of these frameworks has a distinct approach to multi-agent orchestration:

LangGraph.js → Precise graph-based orchestration, ideal for LangChain users
Mastra → Rapid iteration on AI pipelines, RAG-native and TypeScript friendly
OpenAI Agents JS: Traceable, tool-integrated agent workflows
KaibanJS → Role-first orchestration with Kanban clarity and dev tooling built-in

Whether you're building an LLM assistant network, a multi-agent research tool, or just exploring autonomous workflows — the JavaScript ecosystem now has serious tools to match Python’s early lead.

💬 What’s your preferred orchestration style?

Do you prefer graph edges, pipeline chains, or task boards? Are you already working with one of these tools—or rolling your own? I’d love to hear your approach 👇

Building a Multi-Agent Airline Seat Reassignment System with KaibanJS

Dariel Vila — Thu, 28 Aug 2025 02:47:54 +0000

Introduction: The Business Challenge

Airlines frequently face last-minute seat availability changes due to cancellations or no-shows—especially in premium cabins. These situations pose both a revenue opportunity and a customer experience challenge. Automating the seat reassignment process with a coordinated multi-agent AI system can unlock real-time upselling potential and smoother operations while respecting regulations like ADA compliance.

Why Multi‑Agent AI Matters

Complex workflows—such as seat monitoring, passenger matching, messaging, staff alerts, and decision tracking—are better handled by specialized AI agents rather than a monolithic model. A multi-agent approach enables each component to focus on a defined role, mirroring how human operational teams effectively manage complex tasks.

KaibanJS: The React‑Powered Agentic Kanban Framework

KaibanJS is an open-source JavaScript framework designed for building and managing multi-agent systems in real time. Key features include:

Kaiban Board: It functions like Trello or Jira, but for AI agents, showing tasks moving through stages in real time. You define Agents, Tasks, and Teams, and KaibanJS manages the state and orchestration behind the scenes.
Reactive, Redux-inspired state management: Ensures transparent and synchronized UI and logic for agent/task workflows.
Seamless integration with React and other JS frameworks, enabling developers to embed AI agents into existing frontends or backends (React, Vue, NextJS, NodeJS).
Built-in React Agentic Loop: Under the hood, KaibanJS uses a React Agentic Loop with robust state management (inspired by Redux), enabling reactive workflows and dynamic UI updates. This architecture ensures UI + logic remain synchronized and developers have full visibility into agent behavior.

Code Example: Agents, Tasks, and Team Orchestration

Passenger Matching Agent

Responsible for matching available premium seats with eligible passengers:

const passengerMatchingAgent = new Agent({
  name: 'Passenger Matching Agent',
  role: 'Customer Segmentation Specialist',
  goal: 'Match eligible passengers based on loyalty tier, profile preferences, fare class or upsell potential while ensuring UNIQUE seat assignments.',
  background:
    'Senior customer analytics specialist with deep expertise ... CRITICAL: Each seat can only be assigned to ONE passenger ...',
  tools: [new PassengerMatchingTool()]
});

Matching Task (`matchEligiblePassengersTask`)

Defines constraints and expected outcomes:

const matchEligiblePassengersTask = new Task({
  title: 'Passenger Matching',
  description: `Match eligible passengers for the available premium seats based on:
    - Loyalty tier (PLATINUM > GOLD > SILVER)
    - Fare class and upgrade eligibility
    - Seat preferences (WINDOW/AISLE)
    - Upsell potential and revenue optimization
    - Special assistance requirements
    - Historical upgrade acceptance patterns

    CRITICAL ASSIGNMENT RULES:
    - Each seat can ONLY be assigned to ONE passenger
    - Never assign the same seat number to multiple passengers
    - Process passengers in priority order: PLATINUM first, then GOLD, then SILVER
    - Ensure all seat assignments are unique across all passengers

    Include passenger names and email addresses in all outputs for identification.
    Before finalizing, verify that no seat number appears more than once in the assignments.`,
  expectedOutput:
    'Ranked list of eligible passengers matchingResults with UNIQUE seat assignments...',
  agent: passengerMatchingAgent
});

Multi‑Agent Team Definition

Orchestrates the workflow across agents and tasks:

const team = new Team({
  name: 'Airline Seat Reassignment Team',
  agents: [
    seatMonitoringAgent,
    passengerMatchingAgent,
    messageGenerationAgent,
    staffAlertAgent,
    decisionTrackingAgent
  ],
  tasks: [
    monitorSeatChangesTask,
    matchEligiblePassengersTask,
    generateMessagesTask,
    alertStaffTask,
    trackDecisionsTask
  ],
  env: {
    /* environment variables like API keys */
  }
});

team.start();

Visual Workflow with the Kaiban Board

Once launched, the Kaiban Board presents a dynamic Kanban-style view of your AI workflow:

Tasks appear as cards that move through columns like To Do, Doing, and Done.
Inspect task specifics—agent roles, progress, logs, outputs—in real time.
Human validation checkpoints (HITL) can pause workflows for review, feedback, or ethical oversight before proceeding.
Ideal for troubleshooting, collaboration, and ensuring transparency across technical and non-technical stakeholders.

From Airlines to Broader Applications

The multi-agent orchestration pattern is widely applicable:

Hotel dynamic upgrades and room management
Healthcare patient scheduling and triage workflows
Logistics and delivery reallocation optimization

KaibanJS enables complex AI coordination with visibility and control—wherever dynamic decision-making is required.

Conclusion

KaibanJS delivers:

Specialized AI agents tailored to distinct tasks
Task-driven orchestration with built-in constraints
A reactive UI with Kanban-style visualization via the Kaiban Board
Native Human‑in‑the‑Loop support for oversight and compliance

It's a JavaScript-first framework empowering developers to build transparent, scalable, and manageable multi-agent AI systems.

Ready to explore?

Dive into the full working example here: Multi‑Agent Seat Reassignment

Build a Real-World IROPS Re-accommodation Workflow with KaibanJS

Dariel Vila — Thu, 14 Aug 2025 00:48:04 +0000

What Are IROPS and Why Automate Them?

IROPS, short for “irregular operations,” are disruptions like flight delays, cancellations, diversions, or missed connections. These events can cascade through an airline’s network, leading to massive costs and frustrated passengers.

By automating re-accommodation workflows, airlines can reduce operational strain, improve passenger experience, and respond in real time while saving millions.

What We’re Building

Here’s the workflow model we’ll implement using KaibanJS:

Detect Disruption — Identify delays or missed connections, especially in tight turn scenarios.
Generate Options — Create ranked re-accommodation options based on fare class, loyalty status, seat preference, and availability.
Orchestrate Workflow — Use KaibanJS to wire agents and tasks into a single cohesive flow.
Scale With Ease — Seamlessly add communication, booking updates, and staff coordination without refactoring the core.

This structure enables a functional, extendable, and production-ready response to real-world IROP scenarios, all within JavaScript.

Step-by-Step Implementation in KaibanJS

1. Define Domain-Specific Agents

    const realtimeDisruptionDetectionAgent = new Agent({
      name: 'Realtime Disruption Detection Agent',
      role: 'Flight Monitoring Specialist',
      goal: 'Detect operational disruptions impacting connections.',
      tools: [ new FlightMonitorTool() ]
    });

    const intelligentOptionGenerationAgent = new Agent({
      name: 'Intelligent Option Generation Agent',
      role: 'Network Optimization Specialist',
      goal: 'Identify viable re-accommodation options considering constraints.',
      tools: [ new InventorySearchTool() ]
    });

Agents encode purpose: both what they do and why making workflows understandable and maintainable.

2. Define Tasks Grounded in Domain Needs

const detectDisruptionTask = new Task({
  title: 'Realtime Disruption Detection',
  description: `Monitor flight status for flight {flightNumber} from {origin} to {destination} scheduled for {scheduledDeparture}. 
    Detect any disruptions and assess impact on passengers. The agent should identify IROPS before passengers become aware of issues.
    Focus on connection scenarios where passengers miss their connecting flights due to delays.`,
  expectedOutput:
    'Detailed disruption report with affected passenger list, connection details, and estimated delay duration.',
  agent: realtimeDisruptionDetectionAgent
});

const generateOptimalOptionsTask = new Task({
  title: 'Intelligent Option Generation',
  description: `Based on the connection disruption detected, search for optimal re-accommodation options for {affectedPassengers} passengers. 
    Consider factors such as:
    - Available seats across the network from connection airport to final destination
    - Passenger loyalty status and fare class
    - Connection preferences and timing
    - Operational constraints and aircraft availability
    - Individual passenger preferences and special assistance needs
    - Alternative routes and airports if direct flights are not available`,
  expectedOutput:
    'Ranked list of optimal re-accommodation alternatives with detailed flight information and seat availability.',
  agent: intelligentOptionGenerationAgent
});

const reaccommodatePassengersTask = new Task({
  title: 'Re-accommodate Passengers',
  description: `Using the available flights and passenger preferences, apply re-accommodation logic for missed connections:
    - Sort passengers by loyalty status (PLATINUM > GOLD > SILVER)
    - Match fare class availability (F for First Class, Y for Economy)
    - Assign seats based on preferences (WINDOW/AISLE)
    - Handle special assistance requirements
    - Distribute passengers optimally across available flights
    - Ensure network utilization is maximized
    - Consider alternative airports if necessary (e.g., FLL instead of MIA)`,
  expectedOutput:
    'Complete re-accommodation results for each passenger with new flight and seat assignments, including connection details.',
  agent: intelligentOptionGenerationAgent
});

Tasks clarify expectations, keeping code verifiable and business focused.

3. Use a Team to Wire Agents, Tasks, and Inputs

    const team = new Team({
      name: 'IROPS Re-accommodation Team',
      agents: [ realtimeDisruptionDetectionAgent, intelligentOptionGenerationAgent ],
      tasks: [ detectDisruptionTask, generateOptionsTask, reaccommodatePassengersTask ],
      inputs: {
        flightNumber: 'AA930',
        origin: 'GRU',
        destination: 'MIA',
        scheduledDeparture: '2024-01-15T08:00:00Z',
        affectedPassengers: mockPassengers.length
      },
      env: { OPENAI_API_KEY: 'YOUR_OPENAI_API_KEY' }
    });

    team.start().then(result => {
      console.log('Workflow completed:', result);
    });

This arrangement ensures both clarity and flexibility, additional agents for booking updates, notifications, and staff alerts can be added without disrupting the original flow.

Try It Live & Explore Further

See real-world examples, including the airline case, and learn how others are leveraging KaibanJS in production: https://www.kaibanjs.com/examples/multi-agent-airline-reaccommodation
Learn about the core abstractions Agents, Tasks, Teams via KaibanJS documentation: https://docs.kaibanjs.com/get-started/Core-Concepts-Overview
View & run the full example in: KaibanJS Playground

Summary

Key Aspect	Benefit
JS-native implementation	No context-switching—streamline your tech stack
Role-based agents	Better traceability, maintainability, and clarity
Task separation	Easier to test and extend business logic
Visual orchestration	Debug and explain agent workflows with ease

Ditch the Python APIs: Build AI-Powered Workflows Directly in JavaScript with KaibanJS

Dariel Vila — Thu, 06 Mar 2025 23:11:27 +0000

Introduction

If you’ve worked with AI, you’ve probably used Python. From machine learning to automation, Python has been the go-to language for artificial intelligence. But when it comes to deploying AI in real-world applications, the picture gets more complicated.

Most AI-powered apps don’t run in Python. They run in JavaScript environments, whether on the web, in serverless functions, or in full-stack applications. And yet, developers often find themselves wrapping AI models in Python APIs, calling them from JavaScript, and dealing with latency, infrastructure overhead, and integration pain.

But what if we could ditch the Python API layer entirely? What if we could run AI-powered multi-agent workflows natively in JavaScript, directly inside Node.js and web apps?

That’s exactly what KaibanJS does. It’s an open-source JavaScript framework for orchestrating multi-agent AI workflows, allowing developers to integrate AI-driven automation into their applications without needing Python-based APIs.

Let’s break down why JavaScript is becoming an essential tool for AI automation, where Python falls short, and how KaibanJS enables real-world AI-driven workflows.

Why Should AI Agents Run in JavaScript?

1. AI Needs to Run Where the Apps Are—And That’s JavaScript

If you’re building an AI-powered application, chances are it’s not just a standalone Python script—it’s part of a full-stack web app, an automation system, or a backend service.

Traditionally, integrating AI into JavaScript applications required:

A Python-based model running in a separate service.
An API layer (Flask, FastAPI, or Hugging Face Inference API).
Calls from the JavaScript frontend/backend to query AI responses.

This adds unnecessary complexity, increases latency, and forces developers to maintain separate Python infrastructure.

With KaibanJS, AI agents can be built directly inside Node.js and JavaScript-based applications. No separate API layer. No Python dependencies. Just AI-driven automation where it’s needed most.

Example:

Imagine building an AI-powered chatbot for customer support.

With Python:

Host a chatbot model using Python.
Deploy it as a REST API.
Call the API from JavaScript.

With KaibanJS:

The chatbot agent runs natively inside the Node.js backend, reducing response time and eliminating API calls.

Faster, leaner, and way easier to scale.

2. Python Struggles with Scalability—Node.js Doesn’t

Python is single-threaded by default. While it’s great for prototyping AI models, it struggles with high-concurrency workloads.

Node.js, on the other hand, is:

Event-driven, meaning it can handle multiple AI agents simultaneously.
Optimized for real-time automation, making it perfect for AI-driven workflows.
Lightweight and scalable, without requiring multiprocessing hacks.

For AI-powered applications that need to:

✅ Process thousands of events in real-time (e.g., fraud detection, real-time analytics).

✅ Automate high-throughput workflows (e.g., AI-driven customer support).

✅ Scale without running multiple Python worker instances.

KaibanJS makes multi-agent AI systems scalable from day one.

3. JavaScript Runs in the Browser—Python Doesn’t

Another major limitation of Python-based AI is that it doesn’t run in browsers. AI models usually need to be deployed as remote services, requiring API calls for every interaction.

With WebAssembly (WASM) and WebGPU, JavaScript can now execute AI models directly in the browser, eliminating:

❌ Latency from API calls.

❌ The need for cloud-hosted AI services.

❌ Privacy concerns related to sending user data to external APIs.

For example, a real-time AI-powered document assistant built with KaibanJS could:

Run text analysis directly in the browser without external API requests.
Provide AI-powered suggestions instantly, improving user experience.
Keep sensitive data on-device, enhancing privacy.

This is AI where it belongs—inside the app, not on a remote server.

Building AI Workflows with KaibanJS

Let’s take a real-world example:

Use Case: AI-Powered Content Moderation

Imagine you’re building a content moderation system for a social media platform. The goal? Detect and remove harmful content in real-time.

A traditional Python-based system would work like this:

User posts a comment.
Frontend sends the comment to a Python-based AI model via an API.
Python model analyzes the comment and returns a decision.
JavaScript frontend handles moderation actions.

Problems?

API calls introduce latency.
Python backend needs additional infrastructure.
Harder to scale in real-time environments.

How KaibanJS Fixes This

With KaibanJS, the AI-powered moderation agent runs inside the JavaScript backend. The workflow looks like this:

User posts a comment.
A KaibanJS moderation agent immediately analyzes the text.
The agent flags or removes harmful content in real-time—without calling an external API.

✅ Zero latency.

✅ No separate Python service required.

✅ Easy scaling inside a JavaScript application.

This isn’t just faster—it’s how AI should be integrated into modern web applications.

Connecting KaibanJS to Hugging Face Models

KaibanJS also integrates seamlessly with Hugging Face’s Model Hub, allowing developers to:

Use pre-trained NLP models directly in JavaScript workflows.
Run AI-powered text analysis in real-time without external Python services.
Combine AI automation with powerful transformer models in Node.js applications.

For example, a KaibanJS-powered AI assistant could:

Analyze customer sentiment before generating responses.
Summarize support tickets before escalating to human agents.
Filter toxic language in chats in real time.

🚀 This brings AI-driven automation to JavaScript, without the Python dependency.

The Future: AI Workflows Without Python APIs

Python will always be useful for AI research and training, but it doesn’t need to power every AI-driven workflow.

With KaibanJS, developers can:

✅ Eliminate Python API bottlenecks.

✅ Run AI-driven automation inside JavaScript applications.

✅ Build scalable, real-time multi-agent AI systems—without Python dependencies.

🚀 The future of AI-powered applications is happening in JavaScript. Are you ready?

DEV Community: KaibanJS

Put Your Multi-Agent Pipeline on WhatsApp, Telegram, and Discord — With One HTTP Endpoint

The problem every agent builder hits

What is KaibanJS?

OpenResponses: one contract, any backend

How the KaibanJS ↔ OpenClaw integration is built

1. Express server (src/index.ts)

2. From HTTP request to Team.start()

3. Mapping KaibanJS results to OpenResponses

4. Streaming path

5. Swappable team (src/team/index.ts)

What the playground repo layout looks like

Architecture in one glance

Run the playground locally

If you reimplement the adapter elsewhere

Wire it into OpenClaw

Register the provider

Point an agent at the model

Swapping the “model” for your own system

Security and ops (the boring stuff that matters)

Summary

Building a Multi-Agent Baggage Compensation Bot with KaibanJS,A2A, MCP, and Tavily

What we’re building

Tech stack

High-level flow

Why MCP instead of the Kaiban SDK?

Code highlights

1. MCP client: Streamable HTTP + Zod

2. Tavily as a tool (real-time prices)

3. Executor: A2A → validate → team → or block

4. Team definition (async because of MCP tools)

Get it running

Tests

Takeaways

Links

Integrating KaibanJS Teams with Kaiban.io: Enterprise Workflow Automation via A2A Protocol

Introduction

What is KaibanJS?

Example: A Simple KaibanJS Team

What is Kaiban.io?

Core Management Modules

A2A Protocol Integration

The A2A Protocol

A2A Protocol Components

Architecture Overview

Key Components

Implementation: Airline Revenue Management Agent

Step 1: Agent Card Configuration

Step 2: A2A Executor

Step 3: Kaiban Controller

Step 4: KaibanJS Team with Workflow

Step 5: Request Handler Setup

Workflow Lifecycle

1. Card Created (TODO)

2. Processing Started (DOING)

3. Analysis Complete (DONE)

4. Error Handling (BLOCKED)

Setup Instructions

1. Clone the Starter Repository

2. Install Dependencies

3. Configure Environment Variables

4. Start the Server

5. Register Agent in Kaiban.io

6. Test the Integration

Benefits of This Integration

1. SDK Agnostic

2. Standardized Communication

3. Automatic Workflow Management

4. Enterprise Visibility

5. Real-time Collaboration

Conclusion

Additional Resources

Structured Output Chaining in KaibanJS: Bridging LLM and Workflow Agents

The Challenge: Combining LLM and Deterministic Processing

What is Structured Output Chaining?

Key Benefits:

Real-World Example: Product Review Analysis

Step 1: Define Review Schemas

Step 2: Create Workflow-Driven Review Processor

Step 3: Create LLM Agents with Structured Outputs

1. Express server (`src/index.ts`)

2. From HTTP request to `Team.start()`

5. Swappable team (`src/team/index.ts`)