GitHub Copilot SDK: Building Your Own Agent on Copilot

The GitHub Copilot SDK is a library that lets your own program drive the same agent that runs the Copilot CLI. You create a client, open a session with a model, the tools and the MCP servers it may use, send a prompt, and get back the agent’s answer or a stream of events as it plans, calls tools and edits files. It comes in TypeScript, Python, Go, .NET, Java and Rust, and the project README↗ (opens in a new tab) describes it as generally available and following semantic versioning. It needs a Copilot plan unless you bring your own model key, and each prompt counts towards your usage in the same way as the CLI. If you want Copilot’s agent inside a script, a service or your own app, rather than in an editor or a terminal you sit at, this is the piece GitHub offers for it.

What the SDK actually is

The SDK is a thin client over the Copilot CLI’s runtime. GitHub’s page on the default setup↗ (opens in a new tab) says the Node.js and .NET packages include the CLI as a dependency, so nothing else needs installing, and that the SDK starts it as a child process and talks to it over stdio. Python fetches the runtime with a download command after install, and tries to download it automatically if you skip that; Go, Java and Rust need the CLI set up separately or bundled by hand. The same runtime is not only for outsiders: VS Code’s documentation says its Copilot harness, one of the ways it runs agent sessions, is powered by the Copilot SDK.

• TypeScript and Node.js: @github/copilot-sdk on npm.
• Python: github-copilot-sdk. Go: github.com/github/copilot-sdk/go. .NET: GitHub.Copilot.SDK. Rust: github-copilot-sdk. Java: com.github:copilot-sdk-java.
• Sign-in: by default the SDK uses whoever is signed in to the Copilot CLI. It can also take a token from COPILOT_GITHUB_TOKEN, GH_TOKEN or GITHUB_TOKEN, use an OAuth GitHub App for apps with many users, or skip GitHub sign-in entirely with a bring-your-own-key provider such as OpenAI, Microsoft Foundry or Anthropic.
• Cost: usage is counted against your Copilot plan the same way as the CLI, and a session can be given a budget in AI credits. With your own key, the model provider bills you instead.

What it exposes

The feature guides read like a list of what the CLI does, turned into function calls. The ones that matter for building an agent:

• The agent loop. One call takes a prompt through planning, tool calls and file edits until the session is idle. sendAndWait returns the final message; subscribing to events gives you each step as it happens.
• Tools. The CLI’s own tools are there, and defineTool adds a function of yours with a name, a description and a JSON Schema for its arguments. The agent decides when to call it.
• MCP servers. A session takes a map of servers, local ones started with a command or remote ones by URL, each with a tools list that narrows what the agent is offered.
• Permissions. An onPermissionRequest callback sees every shell command, file write, MCP call and URL fetch the agent asks for, and approves or rejects it.
• Custom agents and skills. A session can define specialist agents with their own prompts and tools, and load skills from directories.
• Sessions. They can be resumed, steered with extra messages while they run, and, according to the feature list, run on GitHub-hosted compute and appear in the agents panel.

A minimal example: an agent that reads your board

GitHub’s getting started guide↗ (opens in a new tab) asks for Node.js 20 or later and a signed-in Copilot CLI, then npm install @github/copilot-sdk tsx. The example below goes one step past “what is 2 + 2”: it connects a remote MCP server, allows three read tools from it, and rejects everything else the agent asks to do. It type-checks against version 1.0.14 of the package with TypeScript in strict mode. Run it with npx tsx index.ts.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({
  model: "auto",
  mcpServers: {
    fenbs: {
      type: "http",
      url: "https://fenbs.ai/api/mcp",
      headers: { Authorization: `Bearer ${process.env.FENBS_TOKEN}` },
      tools: ["fenbs_get_context", "fenbs_list_items", "fenbs_get_item"],
    },
  },
  onPermissionRequest: (request) =>
    request.kind === "mcp" && request.serverName === "fenbs"
      ? { kind: "approve-once" }
      : { kind: "reject", feedback: "This agent only reads the board." },
});

const reply = await session.sendAndWait({
  prompt: "List the tasks in Next Up and say which to start first, and why.",
});
console.log(reply?.data.content);

await client.stop();

Three things in it do the real work. model: "auto" lets Copilot pick the model, as GitHub’s own examples do. The tools list on the server is the first limit: the agent is never offered anything else from it. The permission callback is the second: a shell command or a file edit is rejected with a reason the agent can read, so it stops trying rather than failing silently. Leave the callback out and requests are raised as events and left pending until your code answers them.

The MCP guide in the SDK docs gives both server shapes: type: "local" or "stdio" with a command and args, or type: "http" or "sse" with a url and headers. The guide shows a cwd field for local servers; in the 1.0.14 type definitions the field is called workingDirectory, so check the types if the compiler complains.

Custom agents inside the SDK

A session can carry its own specialists. GitHub’s guide to custom agents in the SDK↗ (opens in a new tab) passes a customAgents array, each with a name, a description, a tools list and a prompt, and optionally its own MCP servers. The runtime matches the user’s prompt against each agent’s name and description and hands the work to the one that fits, unless you mark it as not to be chosen automatically. It is the same idea as an .agent.md file in a repository, defined in code instead; the file form is covered in GitHub Copilot custom agent examples.

How it differs from Copilot Extensions

Copilot Extensions went the other way round: Copilot Chat called your service. GitHub’s sunset notice↗ (opens in a new tab) disabled GitHub App-based Copilot Extensions on 10 November 2025 in favour of MCP servers. Client-side extensions that add to Copilot inside VS Code were not affected. So there are now three different jobs, with three different tools:

• Give Copilot, and other assistants, access to your system: write an MCP server. The same server works in Copilot, Claude Code, Cursor and anything else that speaks MCP.
• Put Copilot’s agent inside your own program: use the SDK.
• Change how Copilot behaves in a repository: custom instructions, custom agents and skills, which need no code at all. GitHub Copilot agents vs skills sorts those out.

How it differs from the Claude Agent SDK

The two are the same shape: each packages a vendor’s coding agent, the loop that plans, calls tools, edits files and asks permission, as a library, instead of making you build that loop yourself from a model API. The differences are practical rather than conceptual.

• Which agent. The Copilot SDK drives the Copilot CLI’s runtime; the Claude Agent SDK is the loop that runs Claude Code.
• Languages. Copilot’s comes in six; Claude’s in TypeScript and Python.
• Models and billing. Copilot’s runs on the models in your Copilot plan and counts against it, or on your own key. Claude’s runs on Claude models, signed in with an Anthropic API key or Amazon Bedrock, Google Cloud or Microsoft Foundry credentials.
• Instructions it reads. Each follows its own CLI’s conventions for instruction files, agents and skills, so a repository set up for one is not automatically set up for the other.

If your team already pays for Copilot and works on GitHub, the Copilot SDK is the shorter path. If you want Claude’s agent specifically, the options and examples are in the Claude Agent SDK. For a framework that is not tied to either vendor’s coding agent, see the OpenAI Agents SDK.

Pointing it at a task board

An agent you run from code has no chat window where someone watches it, so the record of what it did has to live somewhere else. On fenbs that is the board: tasks in To Do, Next Up, In Progress and Completed, each with a note, a plan and a test status, and every change recorded under the name of whoever made it. A program has no browser for the OAuth sign-in, so issue a token by hand under Settings, “Connect an AI assistant”: give it a name, tick only the scopes the agent needs, set an expiry if you want one, and put it in an environment variable, never in the code. The token’s scopes and your own role on the board sit underneath the SDK’s tools list and permission callback, so there are four limits between the agent and your data, and revoking the token stops it at once.

Start read-only, as in the example. Once the output is useful, add fenbs_comment so it can report back on a task, and let a person move the task to Completed. fenbs has no due dates, sprints or assignee field for the agent to fill in; the task’s lane and comments carry the state.