copilot-sdk

# Microsoft Copilot SDK Embed Copilot's agentic workflows in any application using Python, TypeScript, Go, or .NET. ## Overview The Microsoft Copilot SDK is transitioning from the GitHub Copilot SDK. It is becoming the programmable interface for the Microsoft Copilot harness, the shared agent foundation used across Microsoft and GitHub products. This transition is happening in phases, and no immediate changes are required for existing users. Package names, namespaces, and some documentation may continue to use GitHub branding during the transition. This guide keeps the currently published package names and imports in its examples. Follow the [official transition announcement](https://github.blog/changelog/2026-10-28-github-copilot-sdk-is-becoming-microsoft-copilot-sdk/) for migration updates. The SDK provides a production-tested agent runtime you can invoke programmatically. You define agent behavior, while Copilot handles planning, tool invocation, file edits, and more. ## Prerequisites 1. **GitHub Copilot access** and an authenticated environment 2. **Language runtime**: Node.js ^20.19.0 or >=22.12.0, Python 3.11+, Go 1.24+, or a .NET Standard 2.0-compatible implementation 3. **Go**: GitHub Copilot CLI installed and authenticated ([Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)) The TypeScript, Python, and .NET packages use a bundled Copilot runtime by default, so they do not need a separate CLI installation. ## Installation ### Node.js/TypeScript ```bash mkdir copilot-demo && cd copilot-demo npm init -y --init-type module npm install @github/copilot-sdk tsx ``` ### Python ```bash pip install github-copilot-sdk # Optional: pre-download the bundled runtime instead of downloading it on first use python -m copilot download-runtime ``` Published Python wheels include a pinned runtime version. The pre-download command caches that runtime locally; if skipped, the SDK attempts to download it automatically on first use. ### Go ```bash mkdir copilot-demo && cd copilot-demo go mod init copilot-demo go get github.com/github/copilot-sdk/go ``` ### .NET ```bash dotnet new console -n CopilotDemo && cd CopilotDemo dotnet add package GitHub.Copilot.SDK ``` ## Quick Start ### TypeScript ```typescript import { CopilotClient, approveAll } from "@github/copilot-sdk"; const client = new CopilotClient(); const session = await client.createSession({ onPermissionRequest: approveAll, model: "gpt-4.1", }); const response = await session.sendAndWait({ prompt: "What is 2 + 2?" }); console.log(response?.data.content); await client.stop(); process.exit(0); ``` Run: `npx tsx index.ts` ### Python ```python import asyncio from copilot import CopilotClient, PermissionHandler async def main(): async with CopilotClient() as client: async with await client.create_session( on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", ) as session: response = await session.send_and_wait("What is 2 + 2?") print(response.data.content) asyncio.run(main()) ``` ### Go ```go package main import ( "fmt" "log" "os" copilot "github.com/github/copilot-sdk/go" ) func main() { client := copilot.NewClient(nil) if err := client.Start(); err != nil { log.Fatal(err) } defer client.Stop() session, err := client.CreateSession(&copilot.SessionConfig{ OnPermissionRequest: copilot.PermissionHandler.ApproveAll, Model: "gpt-4.1", }) if err != nil { log.Fatal(err) } response, err := session.SendAndWait(copilot.MessageOptions{Prompt: "What is 2 + 2?"}, 0) if err != nil { log.Fatal(err) } fmt.Println(*response.Data.Content) os.Exit(0) } ``` ### .NET (C#) ```csharp using GitHub.Copilot.SDK; await using var client = new CopilotClient(); await using var session = await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest = PermissionHandler.ApproveAll, Model = "gpt-4.1", }); var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" }); Console.WriteLine(response?.Data.Content); ``` Run: `dotnet run` ## Streaming Responses Enable real-time output for better UX: ### TypeScript ```typescript import { CopilotClient, approveAll, SessionEvent } from "@github/copilot-sdk"; const client = new CopilotClient(); const session = await client.createSession({ onPermissionRequest: approveAll, model: "gpt-4.1", streaming: true, }); session.on((event: SessionEvent) => { if (event.type === "assistant.message_delta") { process.stdout.write(event.data.deltaContent); } if (event.type === "session.idle") { console.log(); // New line when done } }); await session.sendAndWait({ prompt: "Tell me a short joke" }); await client.stop(); process.exit(0); ``` ### Python ```python import asyncio import sys from copilot import CopilotClient, PermissionHandler from copilot.generated.session_events import SessionEventType async def main(): async with CopilotClient() as client: async with await client.create_session( on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", streaming=True, ) as session: def handle_event(event): if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA: sys.stdout.write(event.data.delta_content) sys.stdout.flush() if event.type == SessionEventType.SESSION_IDLE: print() session.on(handle_event) await session.send_and_wait("Tell me a short joke") asyncio.run(main()) ``` ### Go ```go session, err := client.CreateSession(&copilot.SessionConfig{ OnPermissionRequest: copilot.PermissionHandler.ApproveAll, Model: "gpt-4.1", Streaming: true, }) session.On(func(event copilot.SessionEvent) { if event.Type == "assistant.message_delta" { fmt.Print(*event.Data.DeltaContent) } if event.Type == "session.idle" { fmt.Println() } }) _, err = session.SendAndWait(copilot.MessageOptions{Prompt: "Tell me a short joke"}, 0) ``` ### .NET ```csharp await using var session = await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest = PermissionHandler.ApproveAll, Model = "gpt-4.1", Streaming = true, }); session.On(ev => { if (ev is AssistantMessageDeltaEvent deltaEvent) Console.Write(deltaEvent.Data.DeltaContent); if (ev is SessionIdleEvent) Console.WriteLine(); }); await session.SendAndWaitAsync(new MessageOptions { Prompt = "Tell me a short joke" }); ``` ## Custom Tools Define tools that Copilot can invoke during reasoning. When you define a tool, you tell Copilot: 1. **What the tool does** (description) 2. **What parameters it needs** (schema) 3. **What code to run** (handler) ### TypeScript (JSON Schema) ```typescript import { CopilotClient, approveAll, defineTool, SessionEvent } from "@github/copilot-sdk"; const getWeather = defineTool("get_weather", { description: "Get the current weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "The city name" }, }, required: ["city"], }, handler: async (args: { city: string }) => { const { city } = args; // In a real app, call a weather API here const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]; const temp = Math.floor(Math.random() * 30) + 50; const condition = conditions[Math.floor(Math.random() * conditions.length)]; return { city, temperature: `${temp}°F`, condition }; }, }); const client = new CopilotClient(); const session = await client.createSession({ onPermissionRequest: approveAll, model: "gpt-4.1", streaming: true, tools: [getWeather], }); session.on((event: SessionEvent) => { if (event.type === "assistant.message_delta") { process.stdout.write(event.data.deltaContent); } }); await session.sendAndWait({ prompt: "What's the weather like in Seattle and Tokyo?", }); await client.stop(); process.exit(0); ``` ### Python (Pydantic) ```python import asyncio import random import sys from copilot import CopilotClient, PermissionHandler from copilot.tools import define_tool from copilot.generated.session_events import SessionEventType from pydantic import BaseModel, Field class GetWeatherParams(BaseModel): city: str = Field(description="The name of the city to get weather for") @define_tool(description="Get the current weather for a city") async def get_weather(params: GetWeatherParams) -> dict: city = params.city conditions = ["sunny", "cloudy", "rainy", "partly cloudy"] temp = random.randint(50, 80) condition = random.choice(conditions) return {"city": city, "temperature": f"{temp}°F", "condition": condition} async def main(): async with CopilotClient() as client: async with await client.create_session( on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", streaming=True, tools=[get_weather], ) as session: def handle_event(event): if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA: sys.stdout.write(event.data.delta_content) sys.stdout.flush() session.on(handle_event) await session.send_and_wait( "What's the weather like in Seattle and Tokyo?" ) asyncio.run(main()) ``` ### Go ```go type WeatherParams struct { City string `json:"city" jsonschema:"The city name"` } type WeatherResult struct { City string `json:"city"` Temperature string `json:"temperature"` Condition string `json:"condition"` } getWeather := copilot.DefineTool( "get_weather", "Get the current weather for a city", func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) { conditions := []string{"sunny", "cloudy", "rainy", "partly cloudy"} temp := rand.Intn(30) + 50 condition := conditions[rand.Intn(len(conditions))] return WeatherResult{ City: params.City, Temperature: fmt.Sprintf("%d°F", temp), Condition: condition, }, nil }, ) session, _ := client.CreateSession(&copilot.SessionConfig{ OnPermissionRequest: copilot.PermissionHandler.ApproveAll, Model: "gpt-4.1", Streaming: true, Tools: []copilot.Tool{getWeather}, }) ``` ### .NET (Microsoft.Extensions.AI) ```csharp using GitHub.Copilot.SDK; using Microsoft.Extensions.AI; using System.ComponentModel; var getWeather = AIFunctionFactory.Create( ([Description("The city name")] string city) => { var conditions = new[] { "sunny", "cloudy", "rainy", "partly cloudy" }; var temp = Random.Shared.Next(50, 80); var condition = conditions[Random.Shared.Next(conditions.Length)]; return new { city, temperature = $"{temp}°F", condition }; }, "get_weather", "Get the current weather for a city" ); await using var session = await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest = PermissionHandler.ApproveAll, Model = "gpt-4.1", Streaming = true, Tools = [getWeather], }); ``` ## How Tools Work When Copilot decides to call your tool: 1. Copilot sends a tool call request with the parameters 2. The SDK runs your handler function 3. The result is sent back to Copilot 4. Copilot incorporates the result into its response Copilot decides when to call your tool based on the user's question and your tool's description. ## Interactive CLI Assistant Build a complete interactive assistant: ### TypeScript ```typescript import { CopilotClient, approveAll, defineTool, SessionEvent } from "@github/copilot-sdk"; import * as readline from "readline"; const getWeather = defineTool("get_weather", { description: "Get the current weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "The city name" }, }, required: ["city"], }, handler: async ({ city }) => { const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]; const temp = Math.floor(Math.random() * 30) + 50; const condition = conditions[Math.floor(Math.random() * conditions.length)]; return { city, temperature: `${temp}°F`, condition };