BAL Tools

@baleybots/tools is BAL only — Baleybots Assembly Language, the DSL for composing AI pipelines declaratively.

It is not host coding tools. Filesystem, bash, and scoped workspace access live in @baleybots/agent-tools. The tool() helper for defining your own tools comes from @baleybots/core.

Install

bun add @baleybots/tools @baleybots/core zod ai

Attach BAL to a processor

Give a Baleybot the ability to compose pipelines at runtime:

import { Baleybot } from '@baleybots/core';
import { createBalTools, createBALTool } from '@baleybots/tools';

// Full BAL tool set (execute_baleybots + bal_docs)
const bot = Baleybot.create({
  name: 'composer',
  goal: 'Compose multi-step agent pipelines',
  tools: createBalTools({ model: 'gpt-4.1-mini' }),
});

// Or just the execute tool
const executeOnly = createBALTool({ model: 'gpt-4.1-mini' });

Run BAL directly (no tool loop)

Execute a pipeline without an LLM orchestrating it:

import { Pipeline } from '@baleybots/tools';

const pipeline = Pipeline.from(`
  analyzer { "goal": "Summarize the input" }
  chain { analyzer }
`);
const result = await pipeline.process('Hello world');

Key exports

Export	Purpose
createBALTool	Single execute_baleybots tool
createBalTools	execute_baleybots + bal_docs
executeBAL / compileBAL	Direct BAL execution
Pipeline / runDSL	Pipeline API
validateBAL / createValidateBalTool	BAL validation

Three-way split (alpha.171)

Need	Package
Define a tool with Zod schema	@baleybots/core — tool()
Declarative multi-bot pipelines (BAL)	@baleybots/tools
Filesystem / bash for coding agents	@baleybots/agent-tools

Removed from @baleybots/tools: spawnBaleybotTool, webSearchTool, readFileTool, bashTool, and core re-exports (tool, defineTool). Demo copies of spawn/web-search live under typescript/examples/tools/.

Related

• Composition — TypeScript pipeline() and graph() in core
• Agent tools — host coding tools (different package)
• Alpha 171 migration — import path changes