copilot-sdk

name copilot-sdk description Build applications powered by GitHub Copilot using the Copilot SDK. Use when creating programmatic integrations with Copilot across Node.js/TypeScript, Python, Go, or .NET. Covers session management, custom tools, streaming, hooks, MCP servers, BYOK providers, session persistence, custom agents, skills, and deployment patterns. Requires GitHub Copilot CLI installed and a GitHub Copilot subscription (unless using BYOK). GitHub Copilot SDK Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET. Prerequisites GitHub Copilot CLI installed and authenticated ( copilot --version ) GitHub Copilot subscription (Individual, Business, or Enterprise) — not required for BYOK Runtime: Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+ Installation Language Package Install Node.js @github/copilot-sdk npm install @github/copilot-sdk Python github-copilot-sdk pip install github-copilot-sdk Go github.com/github/copilot-sdk/go go get github.com/github/copilot-sdk/go .NET GitHub.Copilot.SDK dotnet add package GitHub.Copilot.SDK Architecture The SDK communicates with the Copilot CLI via JSON-RPC over stdio (default) or TCP. The CLI manages model calls, tool execution, session state, and MCP server lifecycle. Your App → SDK Client → [stdio/TCP] → Copilot CLI → Model Provider ↕ MCP Servers Transport modes: Mode Description Use Case Stdio (default) CLI as subprocess via pipes Local dev, single process TCP CLI as network server Multi-client, backend services Core Pattern: Client → Session → Message All SDK usage follows: create a client, create a session, send messages. Node.js / TypeScript import { CopilotClient } from "@github/copilot-sdk" ; const client = new CopilotClient (); const session = await client. createSession ({ model : "gpt-4.1" }); const response = await session. sendAndWait ({ prompt : "What is 2 + 2?" }); console . log (response?. data . content ); await client. stop (); Python import asyncio from copilot import CopilotClient async def main (): client = CopilotClient() await client.start() session = await client.create_session({ "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 client := copilot.NewClient( nil ) if err := client.Start(ctx); err != nil { log.Fatal(err) } defer client.Stop() session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1" }) response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?" }) fmt.Println(*response.Data.Content) .NET await using var client = new CopilotClient(); await using var session = await client.CreateSessionAsync( new SessionConfig { Model = "gpt-4.1" }); var response = await session.SendAndWaitAsync( new MessageOptions { Prompt = "What is 2 + 2?" }); Console.WriteLine(response?.Data.Content); Streaming Responses Enable real-time output by setting streaming: true and subscribing to delta events. Node.js const session = await client. createSession ({ model : "gpt-4.1" , streaming : true }); session. on ( "assistant.message_delta" , ( event ) => { process. stdout . write (event. data . deltaContent ); }); session. on ( "session.idle" , () => console . log ()); await session. sendAndWait ({ prompt : "Tell me a joke" }); Python from copilot.generated.session_events import SessionEventType session = await client.create_session({ "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 joke" }) Event Subscription Method Description on(handler) Subscribe to all events; returns unsubscribe function on(eventType, handler) Subscribe to specific event type (Node.js only) Call the returned function to unsubscribe. In .NET, call .Dispose() on the returned disposable. Custom Tools Define tools that Copilot can call to extend its capabilities. Node.js import { CopilotClient , defineTool } 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 ({ city }) => ({ city, temperature : "72°F" , condition : "sunny" }), }); const session = await client. createSession ({ model : "gpt-4.1" , tools : [getWeather], }); Python from copilot.tools import define_tool from pydantic import BaseModel, Field class GetWeatherParams ( BaseModel ): city: str = Field(description= "The city name" ) @define_tool( description= "Get the current weather for a city" ) async def get_weather ( params: GetWeatherParams ) -> dict : return { "city" : params.city, "temperature" : "72°F" , "condition" : "sunny" } session = await client.create_session({ "model" : "gpt-4.1" , "tools" : [get_weather]}) Go type WeatherParams struct { City string `json:"city" jsonschema:"The city name"` } getWeather := copilot.DefineTool( "get_weather" , "Get weather for a city" , func (params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error ) { return WeatherResult{City: params.City, Temperature: "72°F" }, nil }, ) session, _ := client.CreateSession(ctx, &copilot.SessionConfig{ Model: "gpt-4.1" , Tools: []copilot.Tool{getWeather}, }) .NET using Microsoft.Extensions.AI; using System.ComponentModel; var getWeather = AIFunctionFactory.Create( ([Description( "The city name" )] string city) => new { city, temperature = "72°F" }, "get_weather" , "Get the current weather for a city" ); await using var session = await client.CreateSessionAsync( new SessionConfig { Model = "gpt-4.1" , Tools = [getWeather], }); Tool Requirements Handler must return JSON-serializable data (not undefined ) Parameters must follow JSON Schema format Tool description should clearly state when the tool should be used Hooks Intercept and customize session behavior at key lifecycle points. Hook Trigger Use Case onPreToolUse Before tool executes Permission control, argument modification onPostToolUse After tool executes Result transformation, logging, redaction onUserPromptSubmitted User sends message Prompt modification, filtering, context injection onSessionStart Session begins (new or resumed) Add context, configure session onSessionEnd Session ends Cleanup, analytics, metrics onErrorOccurred Error happens Custom error handling, retry logic, monitoring Pre-Tool Use Hook Control tool permissions, modify arguments, or inject context before tool execution. const session = await client. createSession ({ hooks : { onPreToolUse : async (input) => { if ([ "shell" , "bash" ]. includes (input. toolName )) { return { permissionDecision : "deny" , permissionDecisionReason : "Shell access not permitted" }; } return { permissionDecision : "allow" }; }, }, }); Input fields: timestamp , cwd , toolName , toolArgs Output fields: Field Type Description permissionDecision "allow" | "deny" | "ask" Whether to allow the tool call permissionDecisionReason string Explanation for deny/ask modifiedArgs object Modified arguments to pass additionalContext string Extra context for conversation suppressOutput boolean Hide tool output from conversation Post-Tool Use Hook Transform results, redact sensitive data, or log tool activity after execution. hooks : { onPostToolUse : async (input) => { // Redact sensitive data from results if ( typeof input. toolResult === "string" ) { let redacted = input. toolResult ; for ( const pattern of SENSITIVE_PATTERNS ) { redacted = redacted. replace (pattern, "[REDACTED]" ); } if (redacted !== input. toolResult ) { return { modifiedResult : redacted }; } } return null ; // Pass through unchanged }, } Output fields: modifiedResult , additionalContext , suppressOutput User Prompt Submitted Hook Modify or enhance user prompts before processing. Useful for prompt templates, context injection, and input validation. hooks : { onUserPromptSubmitted : async (input) => { return { modifiedPrompt : `[User from engineering team] ${input.prompt} ` , additionalContext : "Follow company coding standards." , }; }, } Output fields: modifiedPrompt , additionalContext , suppressOutput Session Lifecycle Hooks hooks : { onSessionStart : async (input, invocation) => { // input.source: "startup" | "resume" | "new" console . log ( `Session ${invocation.sessionId} started ( ${input.source} )` ); return { additionalContext : "Project uses TypeScript and React." }; }, onSessionEnd : async (input, invocation) => { // input.reason: "complete" | "error" | "abort" | "timeout" | "user_exit" await recordMetrics ({ sessionId : invocation. sessionId , reason : input. reason }); return null ; }, } Error Handling Hook hooks : { onErrorOccurred : async (input) => { // input.errorContext: "model_call" | "tool_execution" | "system" | "user_input" // input.recoverable: boolean if (input. errorContext === "model_call" && input. error . includes ( "rate" )) { return { errorHandling : "retry" , retryCount : 3 , userNotification : "Rate limited. Retrying..." }; } return null ; // Default error handling }, } Output fields: suppressOutput , errorHandling ( "retry" | "skip" | "abort" ), retryCount , userNotification Python Hook Example async def on_pre_tool_use ( input_data, invocation ): if input_data[ "toolName" ] in [ "shell" , "bash" ]: return { "permissionDecision" : "deny" , "permissionDecisionReason" : "Not permitted" }