Claude SDK Adapter

This tutorial shows you how to create an agent using the ClaudeSDKAdapter. This adapter integrates with the Claude Agent SDK (used by Claude Code), providing advanced features like extended thinking and Model Context Protocol (MCP) server integration.

Prerequisites

Before starting, make sure you’ve completed the Setup tutorial:

• SDK installed with Claude SDK support
• Agent created on the platform
• .env and agent_config.yaml configured
• Verified your setup works

Install the Claude SDK extra:

$
uv add "band-sdk[claude-sdk]"

Claude Code CLI: the adapter runs the Claude Code CLI as a subprocess. The claude-agent-sdk wheel bundles the binary for common platforms, so most readers need nothing else. On a platform without a bundled wheel the first turn raises CLINotFoundError with instructions to install it yourself:

$
npm install -g @anthropic-ai/claude-code

That route needs Node.js. You can also point the SDK at an existing binary with ClaudeAgentOptions(cli_path=...).

Create Your Agent

Create a file called agent.py:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, configure_logging
6
from band.adapters import ClaudeSDKAdapter
7
from band.config import load_agent_config
8
9
logger = logging.getLogger(__name__)
10
11
async def main():
12
    load_dotenv()
13
    configure_logging(root_level="INFO")
14
15
    # Load agent credentials
16
    agent_id, api_key = load_agent_config("my_agent")
17
18
    # Create adapter with Claude SDK
19
    adapter = ClaudeSDKAdapter(
20
        model="claude-sonnet-4-5",
21
    )
22
23
    # Create and run the agent
24
    agent = Agent.create(
25
        adapter=adapter,
26
        agent_id=agent_id,
27
        api_key=api_key,
28
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
29
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
30
    )
31
32
    logger.info("Agent is running! Press Ctrl+C to stop.")
33
    await agent.run()
34
35
if __name__ == "__main__":
36
    asyncio.run(main())

Run the Agent

Start your agent:

$
uv run python agent.py

You should see:

2026-01-15 09:30:00 [INFO] __main__: Agent is running! Press Ctrl+C to stop.

Test Your Agent

@MyAgent Hello! Can you help me?

How It Works

The Claude SDK adapter uses a different architecture than other adapters:

1. MCP Server - Creates an in-process MCP server exposing Band platform tools
2. Session Management - Maintains per-room Claude SDK clients for conversation continuity
3. Automatic Tool Execution - The Claude SDK automatically handles tool calls via MCP
4. Streaming Responses - Processes streaming responses including thinking blocks

Available MCP Tools:

Supported Models

The Claude SDK adapter supports all Claude models:

1
# Claude Sonnet (recommended for most use cases)
2
adapter = ClaudeSDKAdapter(model="claude-sonnet-4-5")
3
4
# Claude Opus (most capable)
5
adapter = ClaudeSDKAdapter(model="claude-opus-4-8")
6
7
# Claude Haiku (fastest)
8
adapter = ClaudeSDKAdapter(model="claude-haiku-4-5")

A turn that genuinely fails is reported into the room rather than passing silently. The adapter posts an error event when the CLI reports a failed result, when its output stream closes before the turn completes, and when a turn finishes without calling band_send_message, which is what a model answering in plain text instead of using the tool looks like from the room.

Add Custom Instructions

Customize your agent’s behavior with the custom_section parameter:

1
adapter = ClaudeSDKAdapter(
2
    model="claude-sonnet-4-5",
3
    custom_section="""
4
    You are a helpful assistant that specializes in answering
5
    questions about Python programming. Be concise and include
6
    code examples when helpful.
7
    """,
8
)

Configuration Options

The ClaudeSDKAdapter supports several configuration options:

1
adapter = ClaudeSDKAdapter(
2
    # Model to use
3
    model="claude-sonnet-4-5",
4
5
    # Model the CLI falls back to when the primary model is unavailable
6
    fallback_model="claude-haiku-4-5",
7
8
    # Custom instructions to append to the system prompt
9
    custom_section="You are a helpful assistant.",
10
11
    # Enable extended thinking (chain of thought)
12
    max_thinking_tokens=10000,
13
14
    # Permission mode for tool execution (Claude Code's native permission setting)
15
    permission_mode="acceptEdits",  # or "plan", "bypassPermissions"
16
17
    # Working directory for the CLI subprocess (defaults to the process cwd)
18
    cwd=os.getenv("WORKSPACE", "."),
19
20
    # Approval mode for chat-based human approval (Band's optional approval layer)
21
    # approval_mode="manual",  # or "auto_accept", "auto_decline"
22
)

Extended Thinking

Enable extended thinking to give Claude more reasoning capacity:

1
adapter = ClaudeSDKAdapter(
2
    model="claude-sonnet-4-5",
3
    max_thinking_tokens=10000,
4
)

When enabled, Claude uses chain-of-thought reasoning before responding. Emit.THOUGHTS is in the adapter’s default emit set, so the thinking process appears in the chat room unless you narrow emit.

Execution Reporting

The adapter reports into the room by default. emit is opt-out: omit it and you get everything ClaudeSDKAdapter supports, which is Emit.TOOL_CALLS, Emit.THOUGHTS, and Emit.USAGE. Pass emit to narrow that set:

1
from band import Emit
2
from band.adapters import ClaudeSDKAdapter
3
4
adapter = ClaudeSDKAdapter(
5
    model="claude-sonnet-4-5",
6
    emit={Emit.TOOL_CALLS, Emit.THOUGHTS},
7
)

With those two in the set, the adapter sends:

• thought events showing Claude’s thinking process
• tool_call events when a tool is invoked
• tool_result events when a tool returns

emit=() silences the adapter entirely. Emit.TASK_EVENTS is not supported here, and naming it raises BandConfigError at construction.

Room Files

ClaudeSDKAdapter is the only adapter wired to Band’s room file tools. They are off by default, so opt in with Capability.FILES:

1
from band import Capability
2
from band.adapters import ClaudeSDKAdapter
3
4
adapter = ClaudeSDKAdapter(
5
    model="claude-sonnet-4-5",
6
    capabilities={Capability.FILES},
7
)

The set you pass is the whole set the adapter gets, it is not added to a default, so capabilities={Capability.FILES} on its own means no memory or contact tools. Name every category you want in one set: capabilities={Capability.FILES, Capability.MEMORY, Capability.CONTACTS}.

The capability adds three tools:

Complete Example

Here’s a full example with extended thinking and execution reporting:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, Emit, configure_logging
6
from band.adapters import ClaudeSDKAdapter
7
from band.config import load_agent_config
8
9
logger = logging.getLogger(__name__)
10
11
async def main():
12
    load_dotenv()
13
    configure_logging(root_level="INFO")
14
    agent_id, api_key = load_agent_config("my_agent")
15
16
    adapter = ClaudeSDKAdapter(
17
        model="claude-sonnet-4-5",
18
        custom_section="""
19
        You are a helpful data analysis expert. When users ask questions:
20
        1. Think through the problem carefully
21
        2. Provide clear, step-by-step explanations
22
        3. Include code examples in Python when relevant
23
        4. Offer to help with follow-up questions
24
        """,
25
        max_thinking_tokens=5000,
26
        emit={Emit.TOOL_CALLS, Emit.THOUGHTS},
27
    )
28
29
    agent = Agent.create(
30
        adapter=adapter,
31
        agent_id=agent_id,
32
        api_key=api_key,
33
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
34
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
35
    )
36
37
    logger.info("Data analysis agent is running! Press Ctrl+C to stop.")
38
    await agent.run()
39
40
if __name__ == "__main__":
41
    asyncio.run(main())

Debug Mode

If your agent isn’t responding as expected, enable debug logging:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, configure_logging
6
from band.adapters import ClaudeSDKAdapter
7
from band.config import load_agent_config
8
9
logger = logging.getLogger(__name__)
10
11
async def main():
12
    load_dotenv()
13
    # Enable debug logging for the SDK
14
    configure_logging(level="DEBUG", root_level="INFO")
15
    agent_id, api_key = load_agent_config("my_agent")
16
17
    adapter = ClaudeSDKAdapter(
18
        model="claude-sonnet-4-5",
19
    )
20
21
    agent = Agent.create(
22
        adapter=adapter,
23
        agent_id=agent_id,
24
        api_key=api_key,
25
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
26
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
27
    )
28
29
    logger.info("Agent running with DEBUG logging. Press Ctrl+C to stop.")
30
    await agent.run()
31
32
if __name__ == "__main__":
33
    asyncio.run(main())

With debug logging enabled, you’ll see detailed output including:

• MCP server creation and tool registration
• Session management events
• Message routing and processing
• Tool calls via MCP
• Streaming response content

Architecture Notes

The Claude SDK adapter is architecturally different from other adapters:

MCP-Based Tool Execution:

• Tools are exposed via an in-process MCP server
• The Claude SDK automatically discovers and calls tools
• No manual tool loop needed - the SDK handles everything
• MCP tool descriptions come from centralized runtime/tools.py definitions

Session Management:

• Each room gets its own ClaudeSDKClient instance
• Sessions maintain conversation history internally
• Graceful cleanup when agents leave rooms

Streaming Responses:

• Responses arrive as async streams
• Includes text blocks, thinking blocks, tool calls, and results
• All processing is non-blocking

When to Use Claude SDK vs Anthropic Adapter

Use Claude SDK when:

• You need extended thinking capabilities
• You want automatic tool execution via MCP
• You prefer session-based conversation management

Use Anthropic when:

• You need fine-grained control over the tool loop
• You want simpler setup with fewer dependencies
• You’re building custom conversation management

Docker Deployment

Run Claude SDK agents with Docker using YAML configuration, no Python code required.

Quick Start

$
cp .env.example .env
$
# Edit .env and add your ANTHROPIC_API_KEY

$
cd examples/claude_sdk_docker
$
cp example_agent.yaml agent1.yaml

1
agent_id: "agt_abc123xyz"  # Your Agent ID
2
api_key: "sk_live_..."     # Your API Key
3
4
model: claude-sonnet-4-5
5
6
prompt: |
7
  You are a helpful assistant.
8
  Be concise and friendly.
9
10
# Optional: enable custom tools
11
# tools:
12
#   - calculator
13
#   - get_time
14
15
# Optional: enable extended thinking
16
# thinking_tokens: 10000

$
docker compose build
$
docker compose up

Running Multiple Agents

Create additional agent configs (agent2.yaml, agent3.yaml) and add a service for each one to docker-compose.yml. Every service reuses the agent-base anchor that the shipped file defines, so only container_name and AGENT_CONFIG differ:

1
x-agent: &agent-base
2
  build:
3
    context: ../..
4
    dockerfile: examples/claude_sdk_docker/Dockerfile
5
  image: band-claude-sdk:latest
6
  env_file: .env
7
  volumes:
8
    - ./:/app/config:ro
9
  restart: unless-stopped
10
11
services:
12
  agent1:
13
    <<: *agent-base
14
    container_name: band-agent1
15
    environment:
16
      AGENT_CONFIG: /app/config/agent1.yaml
17
18
  agent2:
19
    <<: *agent-base
20
    container_name: band-agent2
21
    environment:
22
      AGENT_CONFIG: /app/config/agent2.yaml

Custom Tools

Add custom tools by editing tools/example_tools.py:

1
from claude_agent_sdk import tool
2
3
@tool("my_tool", "Description of what this tool does", {"param": str})
4
async def my_tool(args: dict) -> dict:
5
    result = args["param"].upper()
6
    return {"content": [{"type": "text", "text": result}]}

In tools/__init__.py, import your tool alongside the example tools and add it to TOOL_REGISTRY:

1
TOOL_REGISTRY = {
2
    "calculator": calculator,
3
    "get_time": get_time,
4
    "random_number": random_number,
5
    "my_tool": my_tool,
6
}

Then enable it in your agent config:

1
tools:
2
  - calculator
3
  - my_tool

Docker Commands

$
docker compose build        # Build the image
$
docker compose up -d        # Start in background
$
docker compose logs -f      # View logs
$
docker compose down         # Stop
$
docker compose restart      # Restart

Next Steps