GitHub Copilot

The GitHub Copilot harness adapter connects HarnessAgent to GitHub Copilot CLI through the Agent Client Protocol (ACP). The adapter delegates ACP installation, sessions, streaming, tools, approvals, and lifecycle management to @ai-sdk/harness-acp.

Harness packages are experimental. Expect breaking changes between releases as this early API gets further refined.

Setup

$ pnpm add @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel

$ npm install @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel

$ yarn add @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel

$ bun add @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel

The ACP harness installs the pinned GitHub Copilot CLI inside the sandbox when the first session starts. It never uses a host or globally installed Copilot CLI. The launch command disables GitHub Copilot's automatic updates so the installed version remains fixed for that bootstrap.

Import

import {
  createGitHubCopilot,
  githubCopilot,
} from '@ai-sdk/harness-github-copilot';

githubCopilot is equivalent to createGitHubCopilot() with its default configuration.

Basic Usage

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { githubCopilot } from '@ai-sdk/harness-github-copilot';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: githubCopilot,
  model: 'gpt-5.5',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Check the test failures and fix the production code.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
  process.exit(exitCode);
}

To use this agent with Vercel Sandbox, provide VERCEL_OIDC_TOKEN and one of the variables listed under authentication in the host environment.

Sessions support multiple turns, attach and detach, cold stop and resume, turn suspension and continuation, and stopWhen slicing through the shared ACP bridge lifecycle.

Adapter Settings

Use createGitHubCopilot() to configure the runtime:

const harness = createGitHubCopilot({
  auth: 'ai-gateway',
  reasoningEffort: 'high',
  port: 4001,
  startupTimeoutMs: 180_000,
});

Settings:

auth: selects auto, direct, or ai-gateway authentication, or accepts an isolated authentication environment. The default is auto, which selects AI Gateway when Gateway credentials are present and direct GitHub Copilot authentication otherwise.
credentialForwarding: optional synchronous or asynchronous callback that customizes each credential immediately before the harness adapter forwards it into a sandbox process. It receives the credential value that would otherwise be forwarded (either the real credential or a masked value) and the environment variable name used to expose it. This callback only controls the value forwarded into the sandbox process. It does not restrict which credentials the harness adapter can discover, read, or otherwise access in the host process.
reasoningEffort: reasoning effort for reasoning-capable models. Supported values are none, minimal, low, medium, high, xhigh, and max. When omitted, GitHub Copilot uses its configured default.
mcpServers: ACP-native stdio, HTTP, or SSE MCP server definitions keyed by server name.
port: ACP bridge port override.
portEndpoint: host endpoint for the ACP bridge when the sandbox session cannot expose ports directly.
startupTimeoutMs: maximum time to wait for the ACP bridge to start.
reconnect: reconnect timing after an established bridge WebSocket connection drops. maxElapsedMs controls the total retry window, including connection establishment and backoff delays, and defaults to 30 seconds. initialDelayMs defaults to 50 milliseconds, and maxDelayMs defaults to 2 seconds. These retries use exponential backoff and are separate from startupTimeoutMs. They cannot recover when the sandbox, bridge process, or bridge endpoint is permanently unavailable.
mintBridgeToken: synchronous function that receives the sandbox id and returns the ACP bridge authentication token. By default, the adapter generates a random 32-byte token. Custom implementations must return a suitably secret token.

reasoningEffort is fixed for the launched GitHub Copilot server and applies to every session it creates.

The adapter pins the GitHub Copilot CLI, executable, launch command, and ACP version. These implementation details cannot be overridden through createGitHubCopilot().

Authentication

GitHub Copilot supports direct GitHub authentication and AI Gateway authentication. Set one or more of these environment variables:

COPILOT_GITHUB_TOKEN
GH_TOKEN
GITHUB_TOKEN
VERCEL_OIDC_TOKEN
AI_GATEWAY_API_KEY
AI_GATEWAY_BASE_URL

If no applicable credential environment variable is set, the adapter attempts to resolve a native subscription from the host system unless AI Gateway authentication is selected.

For direct authentication, GitHub Copilot checks the three GitHub token variables in the listed order. Fine-grained personal access tokens require the Copilot Requests permission; classic personal access tokens are unsupported. For AI Gateway, the adapter uses VERCEL_OIDC_TOKEN or AI_GATEWAY_API_KEY and honors AI_GATEWAY_BASE_URL.

When the sandbox supports request transformations, the adapter brokers each credential only to matching outbound requests. Other sandboxes retain direct credential forwarding after applying credentialForwarding.

Pass an authentication environment when the host resolves credentials at runtime:

const gatewayHarness = createGitHubCopilot({
  auth: {
    AI_GATEWAY_API_KEY: await resolveGatewayToken(),
    AI_GATEWAY_BASE_URL: 'https://ai-gateway.vercel.sh',
  },
});

The supplied record replaces the host environment for authentication discovery. The adapter does not add its credentials to process.env or include their values in persisted ACP lifecycle identity.

Force a specific authentication route when both kinds of credentials are available:

const directHarness = createGitHubCopilot({ auth: 'direct' });
const gatewayHarness = createGitHubCopilot({ auth: 'ai-gateway' });

AI Gateway model requests do not require GitHub authentication, but built-in GitHub MCP capabilities do.

Sandbox

GitHub Copilot runs inside the sandbox through @ai-sdk/harness-acp. It requires a network sandbox with at least one exposed port:

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});

The first session requires network egress to install GitHub Copilot CLI. Subsequent model, GitHub, web, and MCP requests also require network access.

Built-in Tools

The adapter maps bash, grep, and glob to the corresponding common harness tools.

Other tools remain available under their native GitHub Copilot names, including read_bash, stop_bash, list_bash, view, create, edit, web_fetch, skill, sql, agent tools, and task. GitHub and user-configured MCP tools remain dynamic.

The shared ACP harness applies the configured Harness permissionMode when GitHub Copilot sends a permission request. allow-reads approves read operations, allow-edits also approves file mutations, and allow-all approves every request. Shell execution still requires approval under allow-edits.

Known Limitations

ACP v1 does not expose a stable programmatic name for every native tool event. The adapter uses standard title, kind, and schema matching and leaves unmatched tools dynamic.
ACP v1 does not expose model-step boundaries or per-step usage. The adapter infers boundaries and reports unknown per-step usage when GitHub Copilot does not provide totals.
ACP v1 has no portable manual compaction or mid-turn steering API.
ACP v1 has no portable built-in tool filtering API. Filtering host tools is supported, but filtering GitHub Copilot built-ins throws an unsupported-capability error.
GitHub Copilot does not currently support built-in tool approval requests. Use permissionMode: 'allow-all' with this adapter. Host-executed AI SDK tool approvals still work.
GitHub Copilot ACP does not expose a structured-output metadata mapping, so schema-backed structured output is unsupported.
GitHub Copilot ACP does not expose any question tool, so askUserQuestions is unsupported.
GitHub Copilot CLI does not surface reasoning content over ACP for any model. reasoningEffort controls reasoning depth, not visibility: emitting a reasoning summary requires a parameter that ACP's session/new and session/set_config_option (limited to mode, model, reasoning_effort, allow_all, and agent) never expose to a client. The only code path that sets it lives in GitHub Copilot's interactive terminal UI, which does not run in headless --acp --stdio mode.
Custom headers are not natively supported and only applied via sandbox-external request transformations. When a sandbox without that capability is provided, custom headers therefore cannot be passed and are ignored.