Composition & Pipelines

Baleybots provides several ways to compose agents together. Every composition implements the Processable interface, so composed agents are interchangeable with single agents.

Single agent

When you only need one agent, use Baleybot directly:

import { Baleybot } from '@baleybots/core';

const bot = Baleybot.create({
  name: 'summarizer',
  goal: 'Summarize the given text concisely',
});

const summary = await bot.process('Long article text here...');

Pipeline (sequential chain)

Use pipeline() when agents should run one after another, with the output of each feeding into the next:

import { Baleybot, pipeline } from '@baleybots/core';

const researcher = Baleybot.create({
  name: 'researcher',
  goal: 'Research a topic and gather key facts',
});

const writer = Baleybot.create({
  name: 'writer',
  goal: 'Write an engaging article from research notes',
});

const editor = Baleybot.create({
  name: 'editor',
  goal: 'Polish and improve the article',
});

const workflow = pipeline()
  .step(researcher)
  .step(writer)
  .step(editor)
  .build();

const article = await workflow.process('AI trends in 2025');

The pipeline flows: input -> researcher -> writer -> editor -> output.

Parallel execution

Use parallel() when agents should run simultaneously on the same input:

import { Baleybot, parallel } from '@baleybots/core';

const sentimentBot = Baleybot.create({
  name: 'sentiment',
  goal: 'Analyze sentiment of the text',
});

const topicsBot = Baleybot.create({
  name: 'topics',
  goal: 'Extract main topics from the text',
});

const summaryBot = Baleybot.create({
  name: 'summary',
  goal: 'Write a one-sentence summary',
});

const analyzer = parallel({
  sentiment: sentimentBot,
  topics: topicsBot,
  summary: summaryBot,
});

const results = await analyzer.process('Your text here...');
// { sentiment: '...', topics: '...', summary: '...' }

You can also pass an array instead of an object:

const results = await parallel([sentimentBot, topicsBot]).process('Text');
// ['sentiment result', 'topics result']

ParallelMerge (fan-out / fan-in)

Use ParallelMerge for a three-stage pattern: a fan-out agent splits the work, workers process in parallel, and a merge agent combines the results.

import { ParallelMerge, Baleybot } from '@baleybots/core';

const splitter = Baleybot.create({
  name: 'splitter',
  goal: 'Break the task into sub-tasks and return an inputs array',
});

const worker1 = Baleybot.create({ name: 'worker-1', goal: 'Handle sub-task' });
const worker2 = Baleybot.create({ name: 'worker-2', goal: 'Handle sub-task' });

const merger = Baleybot.create({
  name: 'merger',
  goal: 'Combine all worker results into a final answer',
});

const fanOutFanIn = new ParallelMerge(splitter, [worker1, worker2], merger);

const result = await fanOutFanIn.process('Analyze this dataset');

Combining pipeline and parallel

Since everything is Processable, you can nest compositions:

import { Baleybot, pipeline, parallel } from '@baleybots/core';

const analyzer = parallel({
  sentiment: Baleybot.create({ name: 'sentiment', goal: 'Analyze sentiment' }),
  topics: Baleybot.create({ name: 'topics', goal: 'Extract topics' }),
});

const writer = Baleybot.create({
  name: 'writer',
  goal: 'Write a report from the analysis results',
});

const workflow = pipeline()
  .step(analyzer)
  .step(writer)
  .build();

const report = await workflow.process('Your text here...');

Pipeline helpers

The pipeline builder supports additional step types:

• when(config) -- conditional branching based on AI classification
• loop(config) -- repeat a step until a condition is met
• parallel(config) -- run processors in parallel within a pipeline step
• route(config) -- multi-way routing based on AI classification

import { pipeline, when, loop, Baleybot } from '@baleybots/core';

const drafter = Baleybot.create({ name: 'drafter', goal: 'Draft a response' });
const reviewer = Baleybot.create({ name: 'reviewer', goal: 'Review and improve' });

const workflow = pipeline()
  .step(drafter)
  .step(loop({
    processor: reviewer,
    condition: (output) => output.includes('APPROVED'),
    maxIterations: 3,
  }))
  .build();

When to use what

Pattern	Use when
Single Baleybot	One agent is enough for the task
pipeline()	Steps must run sequentially, each building on the previous
parallel()	Multiple independent analyses on the same input
ParallelMerge	Need to split work, process in parallel, then combine
Nested compositions	Complex workflows combining sequential and parallel steps