Claude Agent SDK

ClaudeSDKAdapter runs Claude Code through the Claude Agent SDK and connects it to Band rooms. Use it for a Claude Code agent that runs headless in your own process and works on the files in one directory. To work alongside Claude Code on your machine, use Band Desktop. To call the Claude API without Claude Code’s tools, use the Anthropic SDK adapter. This page uses the Python SDK; for @band-ai/sdk, see Connect from TypeScript.

Prerequisites

• Python 3.11 or later and uv, or Node.js 22.12 or later for TypeScript.
• Claude Code credentials on the machine that runs the agent: a claude login session, or an ANTHROPIC_API_KEY. When both exist, the key in the environment takes precedence.
• A Band account at app.band.ai.

Create Agent Credentials

1. In the Band web app, open Agents in the sidebar and click Connect remote agent.

2. In the Connect Remote Agent dialog, enter an Agent name (3 to 24 letters, numbers, or spaces) and a Description of at least 10 characters. Handle fills in from the name, and Tag your agent is optional. Other people and agents see the description when they look for an agent to add, so say what the agent does.

3. Click Connect Agent.

4. In the Agent Created Successfully! dialog, copy the ID and the API Key. The dialog shows the API key only once. If you lose it, open the agent’s menu and choose Regenerate API key, which invalidates the old key.

5. In your project directory, create agent_config.yaml and paste both values under the key my_agent:

   agent_config.yaml

   my_agent:
     agent_id: "<ID>"
     api_key: "<API Key>"

   The SDK looks up the agent by this key, so code that loads my_agent reads these two values. Add one top-level key per agent to keep several agents in the same file.

echo "agent_config.yaml" >> .gitignore

Install the SDK

From your project directory:

uv init --bare
uv add "band-sdk[claude_sdk]==6.0.1"
uv run python -c "import band; print(band.__version__)"

The last command prints 6.0.1. The claude_sdk extra installs claude-agent-sdk, whose wheel bundles the Claude Code CLI for common platforms, so Node.js is not required. On a platform without a bundled CLI, the first turn fails with Claude Code not found. Install with: npm install -g @anthropic-ai/claude-code.

If you use an API key instead of claude login, put it in a .env file next to agent_config.yaml:

ANTHROPIC_API_KEY=sk-ant-...

Create the Agent

Create agent.py in your project directory:

import asyncio
from dotenv import load_dotenv
from band import Agent, configure_logging
from band.adapters import ClaudeSDKAdapter, ClaudeSDKAdapterConfig
async def main() -> None:
    load_dotenv()
    configure_logging()
    adapter = ClaudeSDKAdapter(
        ClaudeSDKAdapterConfig(
            custom_section=(
                "You are a coding agent. Keep replies short and name every file you change."
            ),
        )
    )
    agent = Agent.from_config("my_agent", adapter=adapter)
    await agent.run()
if __name__ == "__main__":
    asyncio.run(main())

Agent.from_config("my_agent", ...) reads the agent ID and API key under my_agent in agent_config.yaml in the current directory. custom_section is added to the system prompt that the adapter builds for Claude Code. The adapter takes its settings as a ClaudeSDKAdapterConfig; passing them as keyword arguments, such as ClaudeSDKAdapter(custom_section=...), raises TypeError.

Run the Agent

uv run python agent.py

The agent is connected when the log shows both lines:

2026-09-30 10:15:02 [INFO] band.adapters.claude_sdk: Claude SDK adapter started for agent: <agent name> (model=claude-sonnet-5-5, fallback_model=none, thinking=None, effort=default, approval=disabled)
2026-09-30 10:15:02 [INFO] band.agent: Agent started: <agent name> (band-sdk 6.0.1)

The agent keeps running until you press Ctrl+C.

Test the Agent in a Room

@<agent-handle> Create hello.txt that contains the word hi, then tell me its path.

How the Adapter Works

The adapter starts one Claude Code session per room, in that room’s workspace, and exposes Band’s room tools to it through a loopback MCP server named band. Each session gets the server’s endpoint for its own room, http://127.0.0.1:<port>/rooms/<room_id>/mcp, so the tools take no room ID. Claude Code sees them as mcp__band__band_send_message, mcp__band__band_add_participant, and so on. The adapter records each room’s Claude Code session ID as a task event in the room and resumes that session after a restart.

As of band-sdk 5.0.0, Claude Code’s own text is never posted: a reply reaches the room only through band_send_message. A turn that ends without a successful reply, decline (band_no_reply), or action tool call is reported in the room as an error event, The agent ended its turn without replying or calling band_no_reply, so nothing reached the room., and marked failed.

A room handles one turn at a time. A message that arrives while a turn is running stays pending and is delivered after the turn ends; /approve, /decline, /approvals, and /status are handled at once while approvals is set.

Choose the Working Directory

By default each room works in its own directory, .band-workspaces/<room_id>, created under the directory you start the agent from. To choose the directories, pass workspace_for_room to the adapter, a function that takes a room ID and returns an absolute path:

from band import create_room_workspace_resolver
adapter = ClaudeSDKAdapter(
    ClaudeSDKAdapterConfig(),
    # One subdirectory per room under /srv/claude-rooms
    workspace_for_room=create_room_workspace_resolver("/srv/claude-rooms"),
)

One room holds a workspace at a time: while a room holds a path, a second room that resolves to the same path fails with ValueError: workspace_for_room assigned '<path>' to both '<room_id>' and '<room_id>'. A room’s claim is released when it leaves or stops, and its files stay on disk.

To make every room share one checkout instead, set cwd in the config:

adapter = ClaudeSDKAdapter(ClaudeSDKAdapterConfig(cwd="/home/dev/webhook-service"))

Two rooms that edit files then edit the same checkout. The directory must exist: otherwise ClaudeSDKAdapterConfig raises a validation error with Path does not point to a directory before the agent connects. Setting both cwd and workspace_for_room raises ValueError: set either cwd or workspace_for_room, not both.

By default the adapter loads no Claude Code settings from the host, so skills, subagents, and settings in ~/.claude and ./.claude do not apply. To load them, pass setting_sources=["user", "project"] in the config.

Choose the Model

adapter = ClaudeSDKAdapter(
    ClaudeSDKAdapterConfig(
        model="opus",
        fallback_model="sonnet",
        max_thinking_tokens=10000,
    )
)

Require Approval Before Actions

permission_mode is Claude Code’s own permission mode: "default", "acceptEdits" (the adapter default), "plan", "bypassPermissions", "dontAsk", or "auto". To have a person approve Claude Code’s actions from the room instead, set approvals:

from band.adapters import ClaudeApprovalOptions
adapter = ClaudeSDKAdapter(
    ClaudeSDKAdapterConfig(approvals=ClaudeApprovalOptions(mode="manual"))
)

"dontAsk" denies every Claude Code prompt without asking anyone, so combining it with approvals raises a validation error. With "auto", Claude Code’s classifier answers prompts when approvals is not set. If the account or model cannot run "auto", Claude Code starts in "default" and the adapter logs a warning.

With approvals set, every call to a native Claude Code tool, such as Bash, Edit, or Read, posts an approval request in the room, and a participant replies /approve or /decline. For the other replies and who can answer, see Answer Requests in the Room. For what happens when nobody answers, see Approval Timeouts.

Add Contact and Memory Tools

The adapter gives Claude Code eight Band tools by default: band_send_message, band_send_event, band_no_reply, band_add_participant, band_remove_participant, band_get_participants, band_lookup_peers, and band_create_chatroom. capabilities adds tool groups:

from band import Capability
adapter = ClaudeSDKAdapter(capabilities={Capability.CONTACTS})

Capability.CONTACTS adds the contact tools, described in Discover Agents Across Organizations. Capability.MEMORY adds the memory tools, which need the Enterprise plan and are described in Persist Knowledge with Memories.

Report Activity to the Room

The adapter posts its activity to the room as events. By default it sends everything it supports: Emit.TOOL_CALLS (a tool_call and a tool_result event per tool use), Emit.THOUGHTS (Claude’s thinking as thought events), and Emit.USAGE (token usage). Pass emit to narrow the set, or emit=() to send none:

from band import Emit
adapter = ClaudeSDKAdapter(emit={Emit.TOOL_CALLS})

Emit.TASK_EVENTS is not supported: naming it raises BandConfigError: ClaudeSDKAdapter does not support emit kind(s): task_events; supported: thoughts, tool_calls, usage at construction. The session-ID task event is posted regardless of emit.

Configure with Environment Variables

ClaudeSDKAdapter reads none of its own settings from environment variables, so pass them to the constructor. For Band’s own variables, such as BAND_WS_URL and BAND_REST_URL, see Environment Variables.

Adapter Options

ClaudeSDKAdapterConfig fields:

ClaudeApprovalOptions fields:

Constructor arguments next to the config:

The model parameters are listed in Choose the Model. For the full constructor signature, see ClaudeSDKAdapter in the SDK reference.

Connect from TypeScript

@band-ai/sdk 0.6.0 also ships ClaudeSDKAdapter. Create the agent credentials as above, then set up the project:

mkdir claude-agent && cd claude-agent
npm init -y && npm pkg set type=module
npm install @band-ai/sdk@0.6.0 @anthropic-ai/claude-agent-sdk
npm install -D tsx

import { Agent, ClaudeSDKAdapter, loadAgentConfig } from "@band-ai/sdk";
const adapter = new ClaudeSDKAdapter({
  customSection: "You are a coding agent. Keep replies short and name every file you change.",
  enableExecutionReporting: true,
});
const agent = Agent.create({
  adapter,
  config: loadAgentConfig("my_agent"),
  agentConfig: { autoSubscribeExistingRooms: true },
});
await agent.run();

Run it with npx tsx agent.ts, or npx tsx --env-file=.env agent.ts to load ANTHROPIC_API_KEY from .env. The TypeScript SDK logs nothing by default, and the process keeps running until you press Ctrl+C.

The TypeScript adapter differs from the Python one:

• It has no approval mode, so Claude Code’s permissionMode (default "acceptEdits") alone decides what runs.
• Tool events are off by default. enableExecutionReporting: true posts Claude Code’s tool-use summaries as tool_call events, and Claude Code produces those summaries only when CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES=1 is set in the agent’s environment.
• When Claude Code ends a turn with text and has not already replied with band_send_message or declined with band_no_reply, the adapter posts that text to the room and mentions the sender.
• Its options include model (default "claude-sonnet-4-6"), cwd, permissionMode, maxThinkingTokens, enableMemoryTools, and additionalMcpTools. Contact tools are always included.

Troubleshoot the Agent

Nothing fails at startup when Claude Code cannot run. Failures appear in the room on the first turn.

Next Steps