Skip to main content

Migration Overview

Baleybots v2 introduces several breaking changes aimed at simplifying the API and reducing complexity. This section covers the key changes and how to update your code.

Breaking changes​

Configuration changes​

The processor configuration API has been simplified. Key renames include finalResponseSchema → output: Output.object({ schema }), parameters → inputSchema for tools, and Baleybots.create() → Baleybot.create() (singular). The transport layer has been removed entirely.

See v1 to v2 Config Changes for full before/after examples.

useChat DX cleanup​

useGroupChat and server-mode useChat options (apiUrl, chatId, multiAgent, etc.) were removed. @baleybots/react useChat is now an adapter over AI SDK's useChat: render its messages (AI SDK UIMessages) with ChatTurns / ChatTurn, and point it at a createChatRoute server with api + sessionId. Hosted crew chat uses the product /api/chat endpoint.

See useChat DX cleanup for migration details.

Collapsed segment types​

SpawnAgentSegment, SequentialThinkingSegment, and DSLPipelineSegment have been collapsed into ToolCallSegment. Use segment.display?.kind (subagent, thinking, bal) to identify the tool type.

See Collapsed Segment Types for rendering migration examples.

Alpha 171 cleanup (PRs #276 / #278)​

If you are upgrading from alpha.170 or earlier to the current AI SDK v7 stack, see Alpha 171 Cleanup. Key breaks:

  • registerProvider removed — pass an AI SDK LanguageModel as model: instead
  • @baleybots/core/ensemble moved — import from @baleybots/orchestration/ensemble
  • agentMode / maxToolIterations → stopWhen — default is stepCountIs(50); use combineConditions() to compose
  • @baleybots/tools is BAL-only — filesystem/bash moved to @baleybots/agent-tools; import tool() from core
  • Adapters archived — @baleybots/handler, @baleybots/visualizer, and adapter-* packages removed