SDK Reference

Reference for the Band Python SDK.

Installation

Base package

$
uv add band-sdk

Adapter extras

Extra names are written in their normalised form, which PEP 685 makes canonical: tools collapse every run of -, _ and . to a single - and record only that form in package metadata. The SDK declares several extras with underscores and its README uses them, so band-sdk[claude_sdk] installs the same extra, because the comparison is normalised either way. Prefer the hyphens: they are what pip and uv print back, and PEP 685 warns that unnormalised names may stop working.

Core Agent API

The Agent class is the main entry point for creating and running Band-connected agents.

Agent.create()

Factory method that creates an Agent with platform connectivity.

1
from band import Agent
2
3
@classmethod
4
def create(
5
    cls,
6
    adapter: FrameworkAdapter | SimpleAdapter,
7
    agent_id: str,
8
    api_key: str,
9
    ws_url: str | None = None,
10
    rest_url: str | None = None,
11
    config: AgentConfig | None = None,
12
    session_config: SessionConfig | None = None,
13
    contact_config: ContactEventConfig | None = None,
14
    on_participant_added: ParticipantAddedCallback | None = None,
15
    on_participant_removed: ParticipantRemovedCallback | None = None,
16
    preprocessor: Preprocessor | None = None,
17
) -> Agent

Agent.from_config()

Convenience factory that loads agent_id and api_key from agent_config.yaml instead of taking them as arguments. The adapter is still constructed in Python, so adapter-specific typing is unaffected.

1
from band import Agent
2
3
@classmethod
4
def from_config(
5
    cls,
6
    name: str,
7
    *,
8
    adapter: FrameworkAdapter | SimpleAdapter,
9
    config_path: str | Path | None = None,
10
    **kwargs: Any,
11
) -> Agent

1
import asyncio
2
from band import Agent
3
from band.adapters import AnthropicAdapter
4
5
async def main():
6
    adapter = AnthropicAdapter(model="claude-sonnet-4-5")
7
8
    agent = Agent.from_config("my_agent", adapter=adapter)
9
    await agent.run()
10
11
asyncio.run(main())

Agent lifecycle methods

Agent properties

Example

1
import asyncio
2
from dotenv import load_dotenv
3
from band import Agent
4
from band.adapters import LangGraphAdapter
5
from langchain_openai import ChatOpenAI
6
from langgraph.checkpoint.memory import InMemorySaver
7
8
async def main():
9
    load_dotenv()
10
11
    adapter = LangGraphAdapter(
12
        llm=ChatOpenAI(model="gpt-4o"),
13
        checkpointer=InMemorySaver(),
14
    )
15
16
    agent = Agent.create(
17
        adapter=adapter,
18
        agent_id="your-agent-uuid",
19
        api_key="your-api-key",
20
    )
21
22
    await agent.run()
23
24
asyncio.run(main())

Configuration

Logging

Logging is opt-in. Call configure_logging() once at startup.

For an embedded SDK, configure Band logs only:

1
from band import configure_logging
2
3
configure_logging()

For an agent, runner, or CLI that owns the process, also raise the level of every other logger:

1
from band import configure_logging
2
3
configure_logging(root_level="INFO")

level applies to the band logger, root_level to every other logger, so an embedded SDK leaves the host’s logging untouched. configure_logging() applies the configuration and returns it; build_logging_config() builds the same dictConfig mapping without applying it. Both take the same parameters, documented in Environment Variables.

To drive the same configuration from the environment instead of arguments, use LogSettings, a pydantic-settings model over the BAND_LOG_* variables: LogSettings().configure() in an embedded SDK, or LogSettings().for_application().configure() in a process that owns its logs. configure_logging_from_env() is shorthand for the first. The variables and their defaults are in Environment Variables.

The public logging types are LogLevel (an int or a level name), LogStream (stderr, stdout), LoggingStyle (standard, rich, json), FileStyle (standard, json), FormatStyle (%, {, $), and LoggingConfig (the dictConfig mapping). The rich and json styles require band-sdk[logging].

AgentConfig

1
from dataclasses import dataclass
2
3
4
@dataclass
5
class AgentConfig:
6
    auto_subscribe_existing_rooms: bool = True
7
    single_instance: bool = True

SessionConfig

1
from dataclasses import dataclass
2
3
4
@dataclass
5
class SessionConfig:
6
    enable_context_cache: bool = True
7
    context_cache_ttl_seconds: int = 300
8
    max_context_messages: int = 100
9
    max_message_retries: int = 1
10
    enable_context_hydration: bool = True
11
    idle_resync_seconds: float = 60.0
12
    enable_working_state: bool = True
13
    working_keep_alive_seconds: float = 3.0
14
    working_request_timeout_seconds: int = 2
15
    max_working_state_seconds: float | None = None

ContactEventConfig

Controls how contact requests and updates are processed.

1
from dataclasses import dataclass
2
3
from band.runtime.types import ContactEventCallback, ContactEventStrategy
4
5
6
@dataclass
7
class ContactEventConfig:
8
    strategy: ContactEventStrategy = ContactEventStrategy.DISABLED
9
    hub_task_id: str | None = None
10
    on_event: ContactEventCallback | None = None
11
    broadcast_changes: bool = False

See Contact Management for contact tool behavior, real-time contact events, and full examples of all three strategies.

Configuration files

load_agent_config() reads agent credentials from agent_config.yaml.

1
my_agent:
2
  agent_id: "<your-agent-uuid>"
3
  api_key: "<your-api-key>"
4
5
another_agent:
6
  agent_id: "<another-uuid>"
7
  api_key: "<another-key>"

Runtime URLs and model provider keys can be set in .env:

BAND_REST_URL=https://app.band.ai
BAND_WS_URL=wss://app.band.ai/api/v1/socket/websocket
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

load_agent_config()

1
from band.config import load_agent_config
2
3
agent_id, api_key = load_agent_config("my_agent")

Adapter Reference

Common adapter options

Several adapters expose the same Band integration options. Individual adapter sections below list only their adapter-specific parameters.

The prompt options, custom_section and system_prompt, are fields on the configuration dataclass for the adapters that take one: Codex (CodexAdapterConfig), CopilotACP, CopilotSDK, Letta (LettaAdapterConfig), and Opencode. history_converter, additional_tools, and the **features keywords stay constructor arguments on those adapters.

The **features keywords are accepted by A2A, A2A gateway, ACPClient, Agno, Anthropic, ClaudeSDK, Codex, CopilotACP, CopilotSDK, CrewAI, CrewAI Flow, Gemini, GoogleADK, LangGraph, Letta, Opencode, Parlant, PydanticAI, Slack, and Strands. BandACPServerAdapter takes none of them.

Adapter features

Adapters take their Band feature settings as direct keyword arguments, typed as **features: Unpack[FeatureKwargs]. There are five keys, all optional:

1
from band import Capability, Emit
2
from band.adapters import AnthropicAdapter
3
4
# Report only token usage, and add the enterprise memory tools
5
adapter = AnthropicAdapter(
6
    model="claude-sonnet-4-6",
7
    emit={Emit.USAGE},
8
    capabilities={Capability.MEMORY},
9
)
10
11
# Emit is flag-capable, so a union, a set, or a list all work
12
adapter = AnthropicAdapter(
13
    model="claude-sonnet-4-6",
14
    emit=Emit.TOOL_CALLS | Emit.USAGE,
15
)
16
17
# Silence the adapter completely
18
adapter = AnthropicAdapter(model="claude-sonnet-4-6", emit=())

Emit and Capability members:

The three tool filters narrow the platform tool schemas, in strict precedence: include_categories, then include_tools, then exclude_tools. Each stage narrows the result of the previous one, so include_categories=["chat"] together with include_tools=["band_store_memory"] yields nothing, because band_store_memory is in the memory category. Unknown names in include_tools or exclude_tools are logged as a warning and otherwise ignored.

What each adapter supports

SUPPORTED_EMIT is also the default emit, so this table doubles as what the adapter reports when you pass no emit at all. An adapter with an empty emit set emits nothing and rejects every emit value, including Emit.TOOL_CALLS; there is no flag that turns events on for those.

ClaudeSDKAdapter is the only adapter that declares Capability.FILES.

BandACPServerAdapter is in the table for completeness. It takes no **features keywords at all, so there is nothing to narrow. SlackAdapter declares neither set of its own, but it is not inert: it adopts and validates against the inner adapter’s resolved features, so read its row off the brain you wrap. Every other adapter with an empty SUPPORTED_EMIT rejects any emit value outright.

Adapter summary

LangGraphAdapter

Adapter for LangGraph-based agents with ReAct pattern.

1
from band.adapters import LangGraphAdapter
2
3
adapter = LangGraphAdapter(
4
    llm: BaseChatModel | None = None,
5
    checkpointer: BaseCheckpointSaver | None = None,
6
    graph_factory: Callable[[list[Any]], Pregel] | None = None,
7
    graph: Pregel | None = None,
8
    prompt_template: str = "default",
9
    custom_section: str = "",
10
    additional_tools: list[Any] | None = None,
11
    history_converter: LangChainHistoryConverter | None = None,
12
    recursion_limit: int = 50,
13
    inject_system_prompt: bool | None = None,
14
    **features: Unpack[FeatureKwargs],
15
)

Supports Emit.TOOL_CALLS and Emit.USAGE, plus Capability.MEMORY and Capability.CONTACTS.

See Common adapter options for custom_section, additional_tools, history_converter, and Adapter features for emit and capabilities.

AnthropicAdapter

Adapter for direct Anthropic SDK usage with a manual tool loop.

1
from band.adapters import AnthropicAdapter
2
3
adapter = AnthropicAdapter(
4
    model: str = "claude-sonnet-4-5-20250929",
5
    provider_key: str | None = None,
6
    system_prompt: str | None = None,
7
    prompt: str | None = None,
8
    max_tokens: int = 4096,
9
    history_converter: AnthropicHistoryConverter | None = None,
10
    additional_tools: list[CustomToolDef] | None = None,
11
    include_base_instructions: bool = True,
12
    **features: Unpack[FeatureKwargs],
13
)

See Common adapter options for system_prompt, history_converter, and additional_tools, and Adapter features for emit and capabilities. This adapter supports Emit.TOOL_CALLS and Emit.USAGE, and both Capability.MEMORY and Capability.CONTACTS. Passing Emit.THOUGHTS or Emit.TASK_EVENTS raises BandConfigError.

PydanticAIAdapter

Adapter for Pydantic AI agents with type-safe tools.

1
from band.adapters import PydanticAIAdapter
2
3
adapter = PydanticAIAdapter(
4
    model: str,
5
    system_prompt: str | None = None,
6
    custom_section: str | None = None,
7
    history_converter: PydanticAIHistoryConverter | None = None,
8
    additional_tools: list[Callable | CustomToolDef] | None = None,
9
    instrument: bool | InstrumentationSettings | None = None,
10
    **features: Unpack[FeatureKwargs],
11
)

Supports Emit.TOOL_CALLS and Emit.USAGE, plus Capability.MEMORY and Capability.CONTACTS.

See Common adapter options for system_prompt, custom_section, history_converter, and additional_tools, and Adapter features for emit and capabilities.

ClaudeSDKAdapter

Adapter for Claude Agent SDK with MCP server support.

1
from band.adapters import ClaudeSDKAdapter
2
3
adapter = ClaudeSDKAdapter(
4
    model: str | None = None,
5
    fallback_model: str | None = None,
6
    custom_section: str | None = None,
7
    max_thinking_tokens: int | None = None,
8
    permission_mode: PermissionMode = "acceptEdits",
9
    history_converter: ClaudeSDKHistoryConverter | None = None,
10
    additional_tools: list[CustomToolDef] | None = None,
11
    cwd: str | None = None,
12
    setting_sources: list[str] | None = None,
13
    approval_mode: ApprovalMode | None = None,
14
    approval_text_notifications: bool = True,
15
    approval_wait_timeout_s: float = 300.0,
16
    approval_timeout_decision: ApprovalDecision = "decline",
17
    max_pending_approvals_per_room: int = 50,
18
    approval_authorized_senders: set[str] | None = None,
19
    send_message_dedup_ttl_seconds: float = 30.0,
20
    **features: Unpack[FeatureKwargs],
21
)

Supports Emit.TOOL_CALLS, Emit.THOUGHTS and Emit.USAGE, so Emit.TASK_EVENTS raises BandConfigError. Supports Capability.MEMORY, Capability.CONTACTS, and Capability.FILES.

This is the only adapter wired to the room file tools, band_list_room_files, band_read_room_file, and band_send_room_file. They reach the model through capabilities={Capability.FILES}, and naming that capability on any other adapter raises BandConfigError at construction. See Room Files for the opt-in and the tool arguments.

See Common adapter options for custom_section, history_converter, and additional_tools, and Adapter features for emit and capabilities.

A2AAdapter

Adapter for connecting to remote A2A-compliant agents.

1
from band.adapters import A2AAdapter
2
from band.adapters.a2a import A2AAuth
3
4
adapter = A2AAdapter(
5
    remote_url: str,
6
    auth: A2AAuth | None = None,
7
    streaming: bool = True,
8
    **features: Unpack[FeatureKwargs],
9
)

This adapter declares no supported event kinds and no capabilities, so it accepts only the tool filters; see Adapter features for emit and capabilities.

A2AGatewayAdapter

Adapter that exposes Band peers as A2A HTTP endpoints.

1
from band.adapters import A2AGatewayAdapter, A2AGatewayAdapterConfig
2
3
adapter = A2AGatewayAdapter(
4
    gateway_url: str | None = None,
5
    port: int = 10000,
6
    config: A2AGatewayAdapterConfig | None = None,
7
    rest_client: AsyncRestClient | None = None,
8
    **features: Unpack[FeatureKwargs],
9
)

This adapter declares no supported event kinds and no capabilities, so it accepts only the tool filters; see Adapter features for emit and capabilities. See A2AGatewayAdapterConfig for key configuration fields.

CrewAIAdapter

Adapter for CrewAI-based agents with role, goal, and backstory definitions.

1
from band.adapters import CrewAIAdapter
2
3
adapter = CrewAIAdapter(
4
    model: str = "gpt-5.4",
5
    role: str | None = None,
6
    goal: str | None = None,
7
    backstory: str | None = None,
8
    custom_section: str | None = None,
9
    verbose: bool = False,
10
    max_iter: int = 20,
11
    max_rpm: int | None = None,
12
    allow_delegation: bool = False,
13
    history_converter: CrewAIHistoryConverter | None = None,
14
    additional_tools: list[CustomToolDef] | None = None,
15
    system_prompt: str | None = None,  # Deprecated
16
    **features: Unpack[FeatureKwargs],
17
)

Supports Emit.TOOL_CALLS only, so Emit.THOUGHTS, Emit.TASK_EVENTS and Emit.USAGE raise BandConfigError. Supports Capability.MEMORY and Capability.CONTACTS.

See Common adapter options for custom_section, history_converter, and additional_tools, and Adapter features for emit and capabilities.

CodexAdapter

Adapter for OpenAI Codex CLI integration via JSON-RPC.

1
from band.adapters import CodexAdapter, CodexAdapterConfig
2
3
adapter = CodexAdapter(
4
    config: CodexAdapterConfig | None = None,
5
    *,
6
    additional_tools: list[CustomToolDef] | None = None,
7
    history_converter: CodexHistoryConverter | None = None,
8
    client_factory: Callable[[CodexAdapterConfig], CodexClientProtocol] | None = None,
9
    **features: Unpack[FeatureKwargs],
10
)

client_factory replaces the default transport client, which is what the SDK’s own tests substitute; leave it unset for the stdio or WebSocket client the config selects.

Supports all four Emit kinds, plus Capability.MEMORY and Capability.CONTACTS.

See Common adapter options for additional_tools and history_converter, and Adapter features for emit and capabilities. See CodexAdapterConfig for key configuration fields.

LettaAdapter

Adapter for Letta agents with persistent memory.

1
from band.adapters import LettaAdapter
2
from band.adapters.letta import LettaAdapterConfig
3
4
adapter = LettaAdapter(
5
    config: LettaAdapterConfig | None = None,
6
    history_converter: LettaHistoryConverter | None = None,
7
    **features: Unpack[FeatureKwargs],
8
)

Operating modes:

• per_room (default): Each room gets its own Letta agent with isolated memory.
• shared: One Letta agent shared across all rooms, with per-room isolation via the Conversations API.

See Common adapter options for the custom_section option inside LettaAdapterConfig, and Adapter features for emit and capabilities. This adapter supports Emit.TOOL_CALLS, Emit.TASK_EVENTS, and Emit.USAGE, plus Capability.MEMORY and Capability.CONTACTS. See LettaAdapterConfig for key configuration fields.

ParlantAdapter

Adapter for Parlant behavioral engine integration. Unlike the other adapters, ParlantAdapter owns the Parlant server lifecycle by default: it reserves ports and boots p.Server when the Band agent starts, and tears it down when the agent stops.

1
from band.adapters import ParlantAdapter
2
3
adapter = ParlantAdapter(
4
    *,
5
    name: str | None = None,
6
    description: str | None = None,
7
    nlp_service: Any | None = None,
8
    server_options: dict[str, Any] | None = None,
9
    server: parlant.sdk.Server | None = None,
10
    parlant_agent: parlant.sdk.Agent | None = None,
11
    configure: Callable[[Server, Agent], Awaitable[None]] | None = None,
12
    system_prompt: str | None = None,
13
    custom_section: str | None = None,
14
    history_converter: ParlantHistoryConverter | None = None,
15
    response_timeout: float = 300.0,
16
    response_poll: float = 30.0,
17
    **features: Unpack[FeatureKwargs],
18
)

Declare guidelines before startup with adapter.add_guideline(condition=..., action=..., tools=...), which mirrors parlant.sdk.Agent.create_guideline and attaches Band’s platform tools by default. Calling it after the agent starts raises RuntimeError; use configure= for a running agent. Four argument combinations raise ValueError: parlant_agent without server, nlp_service or server_options with server, system_prompt or custom_section with parlant_agent, and a non-positive response_timeout or response_poll.

See Common adapter options for system_prompt, custom_section, and history_converter, and Adapter features for emit and capabilities. This adapter declares no supported event kinds, so passing emit raises BandConfigError. It declares Capability.MEMORY and Capability.CONTACTS, but only CONTACTS changes the Parlant tool surface: there are no memory tools on it, and the three tool filters are accepted and ignored. It takes no additional_tools.

SlackAdapter

Wraps an inner framework adapter (the brain) and bridges it into Slack. See the Slack Adapter tutorial for setup.

1
from band.integrations.slack import SlackAdapter, SlackApp
2
3
adapter = SlackAdapter(
4
    *,
5
    inner: SimpleAdapter,
6
    apps: list[SlackApp],
7
    port: int = 3000,
8
    transport: Literal["http", "socket"] = "http",
9
    web_client_factory: WebClientFactory | None = None,
10
    rest_client: AsyncRestClient | None = None,
11
    write_tool_names: frozenset[str] | set[str] | None = None,
12
    show_tool_progress: bool = True,
13
    mirror_slack_context: bool = True,
14
    **features: Unpack[FeatureKwargs],
15
)

Feature keywords work differently on this bridge. It declares no emitted events or capabilities of its own, so omit them all and it adopts the inner adapter’s resolved features verbatim, letting the brain’s events and capabilities flow through unchanged. Pass one and it merges over the inner adapter’s features field by field, writing the result onto the inner adapter, and validates against the brain’s supported sets rather than the bridge’s own empty ones. See Adapter features for what each brain accepts.

Adapter configuration objects

A2AGatewayAdapterConfig

CodexAdapterConfig

CodexAdapterConfig has 30+ fields for fine-grained control. Every field can be set explicitly (highest priority) or via a CODEX_-prefixed environment variable (e.g. CODEX_MODEL, CODEX_TRANSPORT, CODEX_APPROVAL_MODE); an explicit constructor kwarg always wins. The table below lists the most commonly used parameters.

See the SDK source for the full list, including approval modes, task event options, and timeout settings.

LettaAdapterConfig

Every field can be set explicitly (highest priority) or via a LETTA_-prefixed environment variable (e.g. LETTA_BASE_URL, LETTA_MODEL); provider_key additionally reads LETTA_API_KEY. Unknown field names are rejected at construction. The table below lists the most commonly used fields; the tutorial has the full set.

api_key, mcp_server_url, and mcp_server_name are deprecated aliases that emit DeprecationWarning. Use provider_key and mcp=LettaMCPConfig(...).

SlackApp

Configuration for one Slack app served by SlackAdapter. Required token combination depends on the adapter’s transport; passing the wrong combination raises ValueError at construction.

ACP integration

BandACPServerAdapter

Platform bridge for editor-facing ACP integrations.

1
from band.adapters import BandACPServerAdapter
2
3
adapter = BandACPServerAdapter(
4
    rest_client: AsyncRestClient | None = None,
5
)

ACPServer

ACP protocol handler used with BandACPServerAdapter.

1
from band import Agent
2
from band.adapters import ACPServer, BandACPServerAdapter
3
4
adapter = BandACPServerAdapter()
5
server = ACPServer(adapter)
6
agent = Agent.create(adapter=adapter, agent_id="...", api_key="...")

ACPServer implements twelve ACP request methods: initialize, authenticate, new_session, load_session, resume_session, fork_session, list_sessions, close_session, prompt, cancel, set_session_mode, and set_config_option. It also exposes ext_method and ext_notification for ACP extension traffic. It does not subclass acp.Agent: the ACP router resolves handlers by name, so every handler is keyword-only.

ACPClientAdapter

Adapter for bridging Band rooms to an external ACP agent process.

1
from band.adapters import ACPClientAdapter
2
3
adapter = ACPClientAdapter(
4
    command: str | list[str] | None = None,
5
    env: dict[str, str] | None = None,
6
    cwd: str | None = None,
7
    mcp_servers: list[dict[str, Any]] | None = None,
8
    additional_tools: list[CustomToolDef] | None = None,
9
    inject_band_tools: bool = True,
10
    auth_method: str | None = None,
11
    profile: ACPClientProfile | None = None,
12
    *,
13
    host: str | None = None,
14
    port: int | None = None,
15
    custom_section: str = "",
16
    spawn_process: SpawnProcess | None = None,
17
    **features: Unpack[FeatureKwargs],
18
)

command (stdio) and host plus port (TCP) are mutually exclusive, and exactly one of them is required. Passing both, neither, or only one half of the TCP pair raises ValueError at construction.

See Adapter features for emit and capabilities. This adapter declares no supported event kinds, so passing emit raises BandConfigError; it supports Capability.MEMORY and Capability.CONTACTS. Its room narration of text, thoughts, tool calls and plans follows the ACP session-update stream and is not gated by emit.

Platform Tools

AgentToolsProtocol

Platform tools available to adapters, typed as AgentToolsProtocol and implemented by band.runtime.tools.AgentTools. These tools are pre-bound to the current room unless noted otherwise.

Contact tool return shapes and contact event workflows are covered in Contact Management.

The three schema accessors take one keyword-only argument:

1
from band.runtime.tools import AgentTools
2
3
class AgentTools:
4
    def get_tool_schemas(self, format: str, *, capabilities: frozenset[Capability] | None = None) -> list[dict[str, Any]] | list[ToolParam]
5
    def get_anthropic_tool_schemas(self, *, capabilities: frozenset[Capability] | None = None) -> list[ToolParam]
6
    def get_openai_tool_schemas(self, *, capabilities: frozenset[Capability] | None = None) -> list[dict[str, Any]]

capabilities selects which optional tool groups join the base chat tools. None, the default, means contacts only, so a bare get_anthropic_tool_schemas() returns the base tools plus the contact tools. An explicit set replaces that default rather than adding to it: capabilities={Capability.MEMORY} returns the base tools plus the memory tools and drops the contact tools, and capabilities=frozenset() returns the base tools alone. Pass {Capability.MEMORY, Capability.CONTACTS} to keep both. Tools bound to the hub room always include the contact tools, whatever you pass. This contacts-only default belongs to the accessors alone: the adapter-level capabilities keyword in Adapter features defaults to empty instead.

ContactTools

ContactTools exposes the contact-management subset of AgentToolsProtocol for ContactEventStrategy.CALLBACK. It is agent-scoped, not room-bound, and uses method names without the band_ prefix.

1
from band.runtime.contact_tools import ContactTools
2
3
class ContactTools:
4
    async def list_contacts(self, page: int = 1, page_size: int = 50) -> dict[str, Any]
5
    async def add_contact(self, handle: str, message: str | None = None) -> dict[str, Any]
6
    async def remove_contact(self, handle: str | None = None, contact_id: str | None = None) -> dict[str, Any]
7
    async def list_contact_requests(self, page: int = 1, page_size: int = 50, sent_status: str = "pending") -> dict[str, Any]
8
    async def respond_contact_request(self, action: str, handle: str | None = None, request_id: str | None = None) -> dict[str, Any]

See the CALLBACK strategy example for ContactTools usage.

Types

PlatformMessage

Immutable message from the platform.

1
from dataclasses import dataclass
2
from datetime import datetime
3
from typing import Any
4
5
6
@dataclass(frozen=True)
7
class PlatformMessage:
8
    id: str
9
    room_id: str
10
    content: str
11
    sender_id: str
12
    sender_type: str  # "User", "Agent", "System"
13
    sender_name: str | None
14
    message_type: str
15
    metadata: Any
16
    created_at: datetime
17
18
    def format_for_llm(self) -> str:
19
        """Format as '[SENDER_NAME]: content'"""

AgentInput

Bundle of everything an adapter needs to process a message.

1
from dataclasses import dataclass
2
3
from band.core import AgentToolsProtocol
4
from band.core.types import HistoryProvider, PlatformMessage
5
6
7
@dataclass(frozen=True)
8
class AgentInput:
9
    msg: PlatformMessage
10
    tools: AgentToolsProtocol
11
    history: HistoryProvider
12
    participants_msg: str | None
13
    contacts_msg: str | None
14
    is_session_bootstrap: bool
15
    room_id: str

HistoryProvider

Lazy history conversion wrapper.

1
from dataclasses import dataclass
2
from typing import Any, TypeVar
3
4
from band.core import HistoryConverter
5
6
T = TypeVar("T")
7
8
9
@dataclass(frozen=True)
10
class HistoryProvider:
11
    raw: list[dict[str, Any]]
12
13
    def convert(self, converter: HistoryConverter[T]) -> T:
14
        """Convert to framework-specific format."""

PlatformConnection

Band platform coordinates, injected into adapter.platform before on_started() fires. Import it from band.core.types; it is not re-exported at the band top level.

1
from dataclasses import dataclass
2
3
4
@dataclass(frozen=True)
5
class PlatformConnection:
6
    agent_id: str
7
    api_key: str
8
    rest_url: str
9
    ws_url: str

The bridge adapters, A2AGatewayAdapter, SlackAdapter, and BandACPServerAdapter, read their credentials from here instead of taking api_key and rest_url constructor parameters for values already given to Agent.create().

A SimpleAdapter subclass that needs its own platform access uses two helpers. require_platform() returns the injected PlatformConnection, and raises RuntimeError when the agent has not started yet. build_rest_client() returns an AsyncRestClient built from that connection’s rest_url and api_key. Call them from on_started() or on first use, and cache the client.

1
from band.core import SimpleAdapter
2
from band.core.types import PlatformConnection
3
4
5
class MyBridgeAdapter(SimpleAdapter[list]):
6
    """Excerpt; `on_message` omitted."""
7
8
    async def on_started(self, agent_name: str, agent_description: str) -> None:
9
        connection: PlatformConnection = self.require_platform()
10
        self._rest = self.build_rest_client()
11
        print(f"{agent_name} bridging {connection.rest_url}")

Troubleshooting