> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-dev.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server. # GitHub Copilot Adapter > Run a Band agent on the GitHub Copilot SDK, with per-room Copilot sessions, Band platform tools, and optional BYOK inference. > **Note** > > The `CopilotSDKAdapter` shipped in Band Python SDK **v1.3.0** under the `copilot_sdk` extra and is exported from `band.adapters`. It is Python only, there is no TypeScript equivalent. Two limits are worth knowing before you start: Copilot-hosted inference requires a GitHub account with a Copilot entitlement, and cache token counts in `Emit.USAGE` events may report `0` because the Copilot CLI runtime does not populate them yet. The `CopilotSDKAdapter` bridges Band rooms to the [GitHub Copilot SDK](https://github.com/github/copilot-sdk) (`github-copilot-sdk`), which manages the Copilot CLI runtime subprocess for you. One adapter owns one Copilot client, and each Band room gets its own Copilot session, so history and context stay isolated per room and resume across restarts on the same host. Copilot's built-in shell and file tools are disabled by the adapter. The model sees only Band platform tools plus any custom tools you register, which is what makes blanket permission approval safe inside the session. > **Tip** > > There are two ways to reach GitHub Copilot from Band. This page covers the **Copilot SDK** path, an in-process adapter that drives the Copilot runtime directly. If you instead want to attach an already-running `copilot --acp` server, over stdio or TCP into a container, use the [GitHub Copilot CLI](/integrations/sdks/tutorials/github-copilot-cli) adapter (`CopilotACPAdapter`). --- ## Prerequisites Complete the [Setup](/integrations/sdks/tutorials/setup) tutorial first. You need Python 3.11+, an agent created on the platform, and `.env` plus `agent_config.yaml` configured. **Install the Copilot SDK extra:** ```bash uv add "band-sdk[copilot-sdk]" ``` **Pre-fetch the Copilot CLI runtime.** The runtime downloads automatically on first use. Fetching it up front keeps agent startup instant: ```bash uv run python -m copilot download-runtime ``` ### Credentials Which credentials you need depends on where inference runs. | Inference | Required credentials | Notes | | ------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Copilot-hosted (default) | `gh auth login`, or `GITHUB_TOKEN` | Needs an account **with a Copilot subscription**. An authenticated account without an entitlement fails at model-call time, not at login. | | BYOK (`provider=...`) | Your provider key, for example `ANTHROPIC_API_KEY` | GitHub authentication is not required. See [Bring Your Own Key](#bring-your-own-key). | Auth for the Copilot-hosted path resolves automatically: `github_token` wins when set, otherwise the locally logged-in GitHub user is used. ```bash # Either authenticate the GitHub CLI locally... gh auth login # ...or provide a token via the environment export GITHUB_TOKEN=ghp_... ``` The adapter checks GitHub auth at startup and raises `BandConfigError` when neither a token nor a logged-in user is available. That check is skipped when `provider` configures BYOK. --- ## Create Your Agent Create a file called `agent.py`: **`agent.py`** ```python title="agent.py" import asyncio import logging import os from dotenv import load_dotenv from band import Agent, Emit from band.adapters import CopilotSDKAdapter, CopilotSDKAdapterConfig from band.config import load_agent_config logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) async def main(): load_dotenv() agent_id, api_key = load_agent_config("my_agent") # Omitting `model` uses the Copilot CLI's default model. # With no GITHUB_TOKEN the locally logged-in GitHub user is used. adapter = CopilotSDKAdapter( CopilotSDKAdapterConfig( custom_section="You are a helpful assistant. Be concise and friendly.", github_token=os.getenv("GITHUB_TOKEN"), ), emit={Emit.TOOL_CALLS, Emit.THOUGHTS}, ) agent = Agent.create( adapter=adapter, agent_id=agent_id, api_key=api_key, ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"), rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"), ) logger.info("Agent is running! Press Ctrl+C to stop.") await agent.run() if __name__ == "__main__": asyncio.run(main()) ``` > **Note** > > `emit` is opt-out: omit it and the adapter reports everything it supports, which is `Emit.TOOL_CALLS`, `Emit.THOUGHTS`, and `Emit.USAGE`. Pass `emit` to narrow that, or `emit=()` for silence. The memory and contact tool groups are the other way round, off until you ask for them through `capabilities`; the adapter supports `Capability.MEMORY` and `Capability.CONTACTS`. `Emit.TASK_EVENTS` is not supported and raises `BandConfigError` at construction. --- ## Run the Agent Start your agent: ```bash uv run python agent.py ``` You should see: ``` INFO:__main__:Agent is running! Press Ctrl+C to stop. ``` The Copilot client starts eagerly at boot, so the runtime download and spawn cost shows up in the startup logs instead of inside your first message's turn. > **Warning** > > The runtime refuses to start a second process for the same agent id on one host, since duplicates steal in-flight room messages and resume the same on-disk Copilot sessions. That surfaces as `BandConfigError: ... already running on this host`. Stop the other process, or pass `config=AgentConfig(single_instance=False)` to `Agent.create`. --- ## Test Your Agent ### Add Agent to a Chat Room Go to [Band](https://app.band.ai) and either create a new chat room or open an existing one. Add your agent as a participant, under the **Remote** section. ### Send a Message In the chat room, mention your agent: ``` @MyAgent Hello! Can you help me? ``` ### See the Response Your agent runs one Copilot turn and replies in the room. With `Emit.TOOL_CALLS` in `emit`, which is the default, you also see `tool_call` and `tool_result` events for each tool the model invokes. --- ## How It Works 1. **Startup** - The adapter renders the system prompt once, creates a `CopilotClient` with your `base_directory`, `github_token`, and `use_logged_in_user` settings, starts the Copilot runtime, and verifies GitHub auth. 2. **Per-room sessions** - The first message in a room creates a Copilot session with a deterministic id, `band-{agent-id}-{room_id}` by default. Later messages resume it by id, so context survives restarts on the same host. 3. **Tool bridging** - Band platform tools and your `additional_tools` are converted to native Copilot `Tool` objects whose handlers execute in-process against the platform API. The session's `available_tools` list is restricted to exactly those names, plus `ask_user` when `ask_user` is configured, which keeps Copilot's shell and file tools out. 4. **Turn execution** - Each message becomes one prompt sent with `send_and_wait`, bounded by `turn_timeout_s`. Turns are serialized per room, and different rooms run concurrently. 5. **Reply** - If the turn already posted to the room through a Band messaging tool, the final assistant text is not sent again. Otherwise the final text is sent as a reply mentioning whoever triggered the turn. 6. **Recovery** - A failed turn evicts the room's session and reports the error into the room. The next message resumes fresh by the same id. If a persisted session cannot be resumed, the adapter creates a fresh session and injects the converted text history into it so context is not lost. Control that with `inject_history_on_resume_failure`. --- ## Configuration Options All value settings live on `CopilotSDKAdapterConfig`. | Parameter | Type | Default | What it does | | ---------------------------------- | ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | `str \| None` | `None` | Copilot model to use. `None` uses the Copilot CLI default. Under BYOK this names the **provider's** model. | | `custom_section` | `str` | `""` | Extra system-prompt section appended to the Band base prompt. | | `reasoning_effort` | `str \| None` | `None` | Reasoning effort for reasoning-capable models. | | `provider` | `ProviderConfig \| None` | `None` | BYOK provider config. Runs inference against your own key instead of the Copilot subscription. | | `inject_history_on_resume_failure` | `bool` | `True` | Inject text history into a fresh session when resuming a persisted session fails. | | `session_id_prefix` | `str \| None` | `None` | Prefix for per-room session ids. `None` derives `band-{agent-id}-`. Set it explicitly only to override that scheme, and keep it unique per agent. | | `base_directory` | `str \| None` | `None` | Copilot state directory (`COPILOT_HOME`). Use a per-agent directory to fully isolate on-disk state between agents sharing a host. | | `github_token` | `str \| None` | `None` | GitHub token for Copilot auth. Wins over the logged-in user when set. Not required under BYOK. | | `use_logged_in_user` | `bool \| None` | `None` | `True` forces the logged-in GitHub user. `False` opts out of GitHub identity entirely (the CLI runs with `--no-auto-login`), which is the BYOK path. `None` lets the SDK resolve it from `github_token`. | | `turn_timeout_s` | `float` | `120.0` | Max seconds to wait for a turn to complete. | | `ask_user` | `UserInputHandler \| "room" \| None` | `None` | Routing for Copilot's built-in `ask_user` human-in-the-loop tool. `None` keeps the tool disabled. | Constructor arguments on `CopilotSDKAdapter` itself: ```python adapter = CopilotSDKAdapter( config: CopilotSDKAdapterConfig | None = None, *, history_converter: HistoryConverter[CopilotSDKSessionState] | None = None, additional_tools: list[CustomToolDef] | None = None, client: CopilotClient | None = None, client_factory: Callable[[], CopilotClient] | None = None, **features: Unpack[FeatureKwargs], ) ``` `history_converter` overrides the default room-history converter, and `additional_tools` registers developer custom tools alongside the Band platform tools. `**features` carries `emit` and `capabilities`, see the note under [Create Your Agent](#create-your-agent). Pass either `client` or `client_factory`, never both. A borrowed `client` is never stopped by the adapter, its owner keeps the lifecycle. When several agents share one client, give each a distinct `session_id_prefix` so per-room session ids cannot collide. ### Human-in-the-loop `ask_user` is off by default. Two routings: ```python from band.integrations.copilot_sdk import OperatorConsole config = CopilotSDKAdapterConfig(ask_user="room") # ask the people in the room config = CopilotSDKAdapterConfig(ask_user=OperatorConsole().ask) # ask someone outside it ``` With `ask_user="room"`, the question posts into the room mentioning whoever triggered the turn, the tool call resolves immediately so the turn ends, and the answer arrives as the next room message on the same persisted session. This is the routing that fits both runtimes: Band delivers a room's messages one at a time, so a turn blocked on a room reply could never receive it, and Copilot keeps an unanswered `ask_user` pending forever. A callable handler answers on behalf of someone outside the room. It is awaited mid-turn with `(UserInputRequest, {"session_id"})` and returns `{"answer", "wasFreeform"}`. The turn keeps counting against `turn_timeout_s` while it waits, so raise `turn_timeout_s` above the handler's own answer window. ```python from band.adapters import CopilotSDKAdapterConfig from band.integrations.copilot_sdk import OperatorConsole config = CopilotSDKAdapterConfig( custom_section=( "A human operator supervises you. When a request needs a decision " "you cannot make alone, consult them with the ask_user tool." ), ask_user=OperatorConsole(answer_timeout_s=300.0).ask, turn_timeout_s=600.0, # must stay above answer_timeout_s ) ``` > **Warning** > > Prefer `OperatorConsole` over a bare `input()` handler. The Copilot SDK leaves the edge cases to the host, and the console covers them: per-question deadline, answer validation against `choices` and `allowFreeform`, one prompt owning the terminal across concurrent rooms, and a graceful "operator unavailable" answer on stdin EOF. Handler mode injects no prompt guidance, so tell the model the operator exists through `custom_section`. --- ## Bring Your Own Key BYOK moves inference billing and authentication to your own provider key. GitHub authentication is not required, and `model` then names the provider's model rather than a Copilot model id. ```python import os from copilot import ProviderConfig from band import Emit from band.adapters import CopilotSDKAdapter, CopilotSDKAdapterConfig anthropic_api_key = os.getenv("ANTHROPIC_API_KEY") adapter = CopilotSDKAdapter( CopilotSDKAdapterConfig( model="claude-haiku-4-5", provider=ProviderConfig( type="anthropic", # base_url is required by the runtime, even for known providers. base_url="https://api.anthropic.com", api_key=anthropic_api_key, ), custom_section="You are a helpful assistant. Be concise and friendly.", use_logged_in_user=False, session_id_prefix="band-copilot-byok-", ), emit={Emit.TOOL_CALLS}, ) ``` Three details matter: * `base_url` is required by the runtime, even for a provider the runtime already knows. * `use_logged_in_user=False` opts out of GitHub identity entirely. Pair it with a `provider` or the runtime has no credentials at all. * Quota errors from your provider surface as `Session error: Failed to get response from the AI model`. Fund or replace the key, or drop `provider` to fall back to the Copilot subscription. > **Tip** > > On the Copilot-hosted path, list the models your account can use with `await client.list_models()`. --- ## Contacts and Memory Memory and contact tools are gated behind capabilities. Turning them on injects the full memory and contact tool instructions into the system prompt, so `custom_section` only needs to add what the base prompt does not cover. ```python from band import Capability, Emit from band.adapters import CopilotSDKAdapter, CopilotSDKAdapterConfig from band.runtime.types import ContactEventConfig, ContactEventStrategy adapter = CopilotSDKAdapter( CopilotSDKAdapterConfig( custom_section=( "When a [Contacts] system message reports that a contact was added " "or removed, treat it as fresh room context." ), session_id_prefix="band-copilot-contact-memory-", ), capabilities={Capability.MEMORY, Capability.CONTACTS}, emit={Emit.TOOL_CALLS}, ) # DISABLED: never react to contact events automatically, no auto-approve and no # hub room. broadcast_changes still injects a "[Contacts]: ..." system message # into active rooms on a real contact change. contact_config = ContactEventConfig( strategy=ContactEventStrategy.DISABLED, broadcast_changes=True, ) ``` Pass `contact_config` to `Agent.create` alongside the adapter. Prompts the agent can then handle: * "List my contacts and check whether @alice is already connected." * "Send a contact request to @alice with a short intro." * "Remember that I want concise status updates." * "What do you remember about my preferred update style?" `ContactEventStrategy` also offers `CALLBACK` for programmatic handling and `HUB_ROOM` for LLM decisions in a dedicated room. See [Contact Management](/integrations/sdks/contacts) for the full model. --- ## Complete Example A BYOK agent with contacts, memory, and execution and thought events: **`agent.py`** ```python title="agent.py" import asyncio import logging import os from copilot import ProviderConfig from dotenv import load_dotenv from band import Agent, Capability, Emit from band.adapters import CopilotSDKAdapter, CopilotSDKAdapterConfig from band.config import load_agent_config from band.runtime.types import ContactEventConfig, ContactEventStrategy logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) async def main(): load_dotenv() agent_id, api_key = load_agent_config("my_agent") anthropic_api_key = os.getenv("ANTHROPIC_API_KEY") if not anthropic_api_key: raise ValueError("ANTHROPIC_API_KEY environment variable is required for BYOK") adapter = CopilotSDKAdapter( CopilotSDKAdapterConfig( model="claude-haiku-4-5", provider=ProviderConfig( type="anthropic", base_url="https://api.anthropic.com", api_key=anthropic_api_key, ), custom_section=( "When a [Contacts] system message reports that a contact was added " "or removed, treat it as fresh room context." ), use_logged_in_user=False, turn_timeout_s=180.0, ), capabilities={Capability.MEMORY, Capability.CONTACTS}, emit={Emit.TOOL_CALLS, Emit.THOUGHTS, Emit.USAGE}, ) agent = Agent.create( adapter=adapter, agent_id=agent_id, api_key=api_key, ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"), rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"), contact_config=ContactEventConfig( strategy=ContactEventStrategy.DISABLED, broadcast_changes=True, ), ) logger.info("Copilot agent is running! Press Ctrl+C to stop.") await agent.run() if __name__ == "__main__": asyncio.run(main()) ``` --- ## Troubleshooting | Symptom | Cause | Fix | | ------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------- | | `BandConfigError: Not authenticated with GitHub Copilot: ...` at startup | No `gh auth login` and no `GITHUB_TOKEN` | Log in with the GitHub CLI, set `github_token`, or configure `provider` for BYOK | | Turns fail with model-call errors despite a valid login | The account has no Copilot entitlement | Use an account with a Copilot subscription, or switch to BYOK | | Agent startup is slow | Runtime downloading or spawning at boot | Pre-fetch with `uv run python -m copilot download-runtime` | | Turn raises after 120s | Long-running turn | Raise `CopilotSDKAdapterConfig(turn_timeout_s=...)` | | Agent replies but no tool or thought events appear | `emit` narrowed past them | Drop the `emit` argument, or pass `emit={Emit.TOOL_CALLS, Emit.THOUGHTS}` | | `BandConfigError: ... already running on this host` | Another process runs the same agent id | Stop it, or set `AgentConfig(single_instance=False)` | | BYOK turn fails with `429 You exceeded your current quota` | Provider key out of quota or invalid | Fund or replace the provider key, or drop `provider` | | Room reply says the operator did not answer | An `ask_user` question expired unanswered | Answer within `answer_timeout_s`, or raise it while keeping it below `turn_timeout_s` | | Every question answers "No operator is attached to this agent" | stdin is closed, for example a headless run | Run in a real terminal, or use `ask_user="room"` | --- ## Next Steps #### [GitHub Copilot CLI](/integrations/sdks/tutorials/github-copilot-cli) Drive the Copilot CLI over ACP, stdio or TCP #### [Contact Management](/integrations/sdks/contacts) Contact strategies and discovery #### [Framework Adapters](/integrations/adapters) Every adapter and its install extra #### [Reference](/integrations/sdks/reference) Complete API reference and configuration