copilot-sdk

# GitHub Copilot SDK Embed Copilot's agentic workflows in any application using Python, TypeScript, Go, or .NET. ## Overview The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration - you define agent behavior, Copilot handles planning, tool invocation, file edits, and more. ## Prerequisites 1. **GitHub Copilot CLI** installed and authenticated ([Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)) 2. **Language runtime**: Node.js 18+, Python 3.8+, Go 1.21+, or .NET 8.0+ Verify CLI: `copilot --version` ## 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 ``` ### 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(): client = CopilotClient() await client.start() session = await client.create_session({ "on_permission_request": PermissionHandler.approve_all, "model": "gpt-4.1", }) response = await session.send_and_wait({"prompt": "What is 2 + 2?"}) print(response.data.content) await client.stop() 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(): client = CopilotClient() await client.start() session = await client.create_session({ "on_permission_request": PermissionHandler.approve_all, "model": "gpt-4.1", "streaming": True, }) 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({"prompt": "Tell me a short joke"}) await client.stop() 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(): client = CopilotClient() await client.start() session = await client.create_session({ "on_permission_request": PermissionHandler.approve_all, "model": "gpt-4.1", "streaming": True, "tools": [get_weather], }) 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({ "prompt": "What's the weather like in Seattle and Tokyo?" }) await client.stop() 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)];