Cursor

CursorACPAdapter starts the Cursor CLI’s ACP server, agent acp, and connects it to Band rooms over the Agent Client Protocol (ACP). Use it for a Cursor agent that runs headless in your own process and reads, edits, and runs code in a workspace. Cursor’s permission requests, questions, and plans go to the room for a participant to answer. To work alongside Cursor on your machine, use Band Desktop. 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.

• The Cursor CLI on your PATH, signed in on the machine that runs the agent (Cursor CLI installation):

  curl https://cursor.com/install -fsS | bash
  agent login

  Instead of agent login, you can pass a Cursor API key or auth token to the adapter, see Authenticate Cursor. Cursor uses that account for model access and billing.

• 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[acp]==6.0.1"
uv run python -c "import band; print(band.__version__)"

The last command prints 6.0.1. The acp extra installs the ACP Python SDK and the MCP server that gives Cursor Band’s tools.

Create the Agent

Create agent.py:

import asyncio
from band import Agent, configure_logging
from band.adapters import CursorACPAdapter, CursorACPAdapterConfig
async def main() -> None:
    configure_logging()
    adapter = CursorACPAdapter(
        CursorACPAdapterConfig(
            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 context the adapter sends Cursor.

Run the Agent

uv run python agent.py

The agent is connected when the log shows:

2026-09-30 10:15:02 [INFO] band.agent: Agent started: <agent name> (band-sdk 6.0.1)

The adapter starts a Cursor process when a room sends its first message, not at startup. The log then shows the process starting:

2026-09-30 10:16:40 [INFO] band.integrations.acp.client_runtime: Spawning ACP agent subprocess
2026-09-30 10:16:42 [INFO] band.integrations.acp.client_runtime: Connected to ACP agent: /home/dev/.local/bin/agent acp
2026-09-30 10:16:42 [INFO] band.integrations.mcp.local_server: Started local MCP server band on 127.0.0.1:55482 with 13 tools
2026-09-30 10:16:44 [INFO] band.integrations.acp.client_adapter: Created ACP session <session-id> for room <room_id> (mcp_servers=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 reply done.

Cursor needs permission to run `<tool>`. Reply `/cursor select <token> <option-id>` or `/cursor deny <token>`. Available options: allow-always, allow-once, reject-once

@<agent-handle> /cursor select <token> allow-once

How the Adapter Works

• One process per room: each room gets its own agent acp subprocess over stdio, started on the room’s first message.
• One workspace per room: by default each room works in .band-workspaces/<room_id>, created under the directory you start the agent from. Pass cwd to use another root, which becomes <cwd>/<room_id>, or workspace_for_room, a function that takes a room ID and returns an absolute path. Set one, not both.
• One turn at a time per room: the adapter runs one Cursor turn at a time in each room, and rooms run their turns concurrently. A message that arrives during a room’s turn waits for it to finish. Replies to a pending decision are handled at once.
• Band tools: with inject_band_tools=True, the default, the adapter serves Band’s room and contact tools from an MCP server on the local loopback and passes it to Cursor. As of band-sdk 5.0.0, only those tools reply: a turn that ends with Cursor text but no band_send_message or band_no_reply call posts the text as a thought event when Emit.THOUGHTS is on, then the runtime reports an error event, The agent ended its turn without replying or calling band_no_reply, so nothing reached the room., and marks the turn failed.
• Sessions: the adapter records each room’s Cursor session in a task event and loads that session after a restart. When Cursor cannot restore it, the adapter replays the room’s transcript into the new session’s first prompt.

Answer Cursor’s Decisions

Cursor sends three kinds of decisions: permission requests, multiple-choice questions, and plans to approve. approval_mode, question_mode, and plan_mode each default to "manual", which posts the decision in the room with a token and waits for a /cursor reply. approval_mode covers Cursor’s own tools only: Band’s tools, including additional_tools, are approved once per call in every mode while the turn is active, using Cursor’s allow-once option. Replies, automatic modes, and who can answer are described in Approval Mode, Answer Requests in the Room, and Approval Timeouts.

@<agent-handle> /cursor decisions lists the room’s pending decisions. A decision nobody answers within decision_timeout_s (default 300.0 seconds) is cancelled, and the room shows Cursor <kind> decision `<token>` timed out and was cancelled.

Allow Cursor’s Tools

Cursor decides which of its own tools need permission from the permissions rules in its CLI config (Cursor CLI permissions), either in ~/.cursor/cli-config.json for every workspace or in .cursor/cli.json inside one workspace. A workspace .cursor/cli.json must include deny, even empty. Without it, agent acp exits with Invalid project config at <path>: schema validation failed, and the turn fails.

Authenticate Cursor

By default the adapter sends no ACP authenticate call: Cursor uses the CLI’s stored agent login session, or a key from its environment. To use a key instead, pass it in the config:

import os
adapter = CursorACPAdapter(
    CursorACPAdapterConfig(api_key=os.environ["CURSOR_API_KEY"]),
)

api_key sets CURSOR_API_KEY and auth_token sets CURSOR_AUTH_TOKEN for the Cursor process, unless env already sets that variable. Setting both fails config validation with set either api_key or auth_token, not both. auth_method="cursor_login" makes the adapter call ACP authenticate with that method after each process starts; Cursor does not answer it when no login is stored.

Choose the Model

Cursor advertises its models and reasoning levels for each session. To select one, set model and reasoning_effort in CursorACPAdapterConfig, or pass resolve_session_config to the adapter, a function that receives the advertised options and returns the values to apply, as Select a Model per Session describes. Set one approach, not both. The SDK’s examples/acp/clients/cursor.py selects a model and reasoning effort from CURSOR_MODEL and CURSOR_REASONING_EFFORT only when Cursor offers them.

Adapter Options

CursorACPAdapterConfig is immutable and rejects unknown fields. The adapter reads none of its settings from environment variables.

CursorACPAdapter also accepts additional_tools, workspace_for_room, and resolve_session_config, and capabilities, where Capability.MEMORY adds the memory tools. Contact tools are always included. emit supports Emit.TOOL_CALLS, Emit.THOUGHTS, and Emit.TASK_EVENTS (Cursor’s plans), all on by default. Emit.USAGE raises BandConfigError: CursorACPAdapter does not support emit kind(s): usage; supported: task_events, thoughts, tool_calls. For the other ACP presets, see ACP Presets in the SDK reference.

Connect from TypeScript

@band-ai/sdk 0.6.0 also ships CursorACPAdapter. @agentclientprotocol/sdk talks to Cursor over ACP, and @modelcontextprotocol/sdk serves Band’s tools to it. Create the agent credentials as above, then set up the project:

mkdir cursor-agent && cd cursor-agent
npm init -y && npm pkg set type=module
npm install @band-ai/sdk@0.6.0 @agentclientprotocol/sdk@^1.4.0 @modelcontextprotocol/sdk
npm install -D tsx

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

Run it with npx tsx agent.ts. 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:

• Like the Python adapter, it starts one agent acp process per room, on the room’s first message. cwd, which defaults to the directory you start the agent in, is the root of the room workspaces: each room works in <cwd>/.band-workspaces/<roomId>. To choose the directories yourself, pass workspaceForRoom, which cannot be combined with cwd.
• If cwd contains agent_config.yaml, Cursor can read the agent’s API key, and its tool results post the key to the room. cwd defaults to the directory you start the agent in, so set cwd or workspaceForRoom to a separate directory.
• The mode values are camelCase: approvalMode and planMode take "manual", "autoAccept", or "autoDecline", and questionMode takes "manual", "autoFirst", or "autoCancel". The timeout is decisionTimeoutMs, default 300000. Credentials go in apiKey or authToken.
• The permission prompt does not list the options. Cursor offers allow-once, allow-always, and reject-once, so reply /cursor select <token> allow-once. Each request also posts a tool_call event, Permission requested: <tool>.
• A message in a room whose turn is still running gets Cursor is still processing the previous request in this room.

Troubleshoot the Agent

Next Steps