Skip to navigation
Reference

Versioning

Supported Band SDK releases and the 5.0 and 6.0 migrations

These docs describe the current supported SDK baseline. Upgrade your application before relying on a behavior documented here.

PackageSupported releasePackage registry
Python SDKband-sdk 6.0.1PyPI
Band MCPband-mcp 2.2.7PyPI

What Supported Means

A supported release is the version whose public API, defaults, errors, and examples this site describes. The current documentation does not promise compatibility with earlier releases. Pin the version you deploy, test upgrades in a non-production environment, and read the release notes for each version you cross.

The SDK changelog feed lists user-facing releases at SDK Changelog. For complete upstream history, see the Python SDK changelog and Band MCP changelog.

Migrate band-sdk 5.1.0 to 6.0.0

band-sdk 6.0.0 contains the breaking changes below. The current baseline, 6.0.1, retains them. band-sdk 6.0.1 adds two fixes on top: the WebSocket reconnects after a close with code 1000 or 1001, and WebSocket authentication and diagnostic output follow tighter boundaries. It has no migration steps. band-mcp 2.2.7 only raises its band-sdk floor to 5.1.0.

Before 6.0.0After 6.0.0Migration
Runtime types were imported from band.runtime.types.The module is removed. AgentConfig is in band.runtime.agentconfig, SessionConfig in band.runtime.sessionconfig, ContactEventConfig and ContactEventStrategy in band.runtime.contacts, the callback aliases (MessageHandler, ContactEventCallback, ParticipantAddedCallback, ParticipantRemovedCallback) in band.runtime.callbacks, normalize_handle in band.runtime.handles, PlatformMessage in band.runtime.messages, and ConversationContext in band.runtime.context. band still exports AgentConfig, SessionConfig, and PlatformMessage.Change every from band.runtime.types import ... to the new module, or to from band import ... where band exports the name.
SessionConfig was a dataclass that rejected unknown arguments and raised ValueError for invalid timings.SessionConfig is a pydantic BaseSettings model that also reads unprefixed, case-insensitive environment variables, ignores empty values and unknown arguments, and raises ValidationError. It adds stopped_resync_seconds. See SessionConfig.Catch ValidationError where you caught ValueError for config errors. Check that no environment variable named like a SessionConfig field, such as MAX_CYCLE_SECONDS, is set unintentionally. Set stopped_resync_seconds to poll a stopped room on its own interval.
The pydantic-ai extra required pydantic-ai-slim[anthropic]>=2.18.0 and openai>=2.0.0. The strands and nooa extras accepted any openai>=2.0.0. langgraph accepted langchain-openai>=0.3.0.pydantic-ai requires pydantic-ai-slim[anthropic,openai]>=2.55.0 and openai>=3.26.0,<4. crewai, strands, and nooa require openai>=2.0.0,<3, so pydantic-ai cannot be installed in the same environment as any of them. langgraph requires langchain-openai>=1.5.0.Install pydantic-ai in its own environment or service, separate from crewai, strands, and nooa, and rebuild lockfiles. See Install the SDK.
NooaAdapter re-keyed custom tool calls from field names to aliases, and rendered custom tools with keyword arguments.A custom tool is called as await self.room.<name>(arguments={...}) with the original Pydantic validation payload, using each field’s validation alias. Platform tools keep keyword arguments.Update NOOA agent code and prompts that call custom tools with keyword arguments. See NOOA.

The 6.0.0 upstream release notes are the source for this migration list. 6.0.0 also adds adapter.add_cleanup() for caller-supplied resources; see Agent Lifecycle Methods. Other 6.0.0 behavior changes are documented on the pages that own them: the Anthropic adapter ends a turn after a successful band_no_reply, and Strands calls OpenAI through the Responses provider. The current implementation was verified against the 6.0.1 release source.

Migrate band-sdk 4.0.0 to 5.0.0

band-sdk 5.0.0 contains the breaking changes below. The current baseline, 6.0.1, retains these changes.

Before 5.0.0After 5.0.0Migration
CodexAdapterConfig(fallback_send_agent_text=True) could post native Codex text as a room reply. ACP and Codex integrations could complete a room turn without a Band reply tool.ACP and Codex room replies require Band tools. fallback_send_agent_text and ACP’s retired assistant_text_mode are rejected. Native text is telemetry, not a reply.Remove retired fields. Configure the coding agent to call band_send_message to reply or band_no_reply when it intentionally does not reply. See Coding Agent Adapters.
A custom Band MCP backend could use kind="sdk", read backend.server, pass get_participant_handles or tool_result_hook to create_band_mcp_backend(), or build Claude SDK tools from band.integrations.claude_sdk.tools.The SDK transport and Claude SDK tool builders are removed. The 5.0 backend uses HTTP or SSE served by local_server; its settings select room_bound=True for one endpoint per room. In the current 6.0.1 API, create_band_mcp_backend() takes BandMCPBackendSettings and the backend exposes local_server.Replace SDK transport with a room-bound HTTP endpoint. Replace server with local_server, remove the retired factory arguments, and remove custom Claude SDK tool-builder calls.
Some SimpleAdapter turns could end silently, and custom adapters could use settles_turn_reply, is_terminal_success, or missing_reply_error from band.runtime.tools.Every SimpleAdapter turn is judged by the turn-outcome rule. AgentToolsProtocol exposes turn and send_notice; a reply post settles the turn.For a custom adapter, use tools.send_notice() for status output. Call tools.turn.settle() only when the adapter intentionally completes without a reply. Otherwise send a room reply or call the no-reply tool. See Turn Outcome.

The 5.0.0 upstream release notes are the source for this migration list.