Skip to main content
copilot-sdk Build applications powered by GitHub Copilot using the Copilot SDK — session management, custom tools, streaming, hooks, MCP servers, BYOK, deployment patterns
Ir para a instalação Skills Marketplace Descubra e explore skills de IA criadas pela comunidade.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Mostrar detalhes do prompt Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
npx skills add https://github.com/fabioc-aloha/Alex_Plug_In --skill copilot-sdkO comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Baixar Zip Baixando... Ocupações relacionadas SOC
Baseado na classificação ocupacional SOC
name copilot-sdk description Build applications powered by GitHub Copilot using the Copilot SDK — session management, custom tools, streaming, hooks, MCP servers, BYOK, deployment patterns tier standard applyTo **/copilot*,**/*copilot-sdk*,**/*github-copilot*
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 BYOKRuntime: Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+
Installation
Language Package Install Node.js @github/copilot-sdknpm install @github/copilot-sdkPython github-copilot-sdkpip install github-copilot-sdkGo
github.com/github/copilot-sdk/go
go get github.com/github/copilot-sdk/go
.NET GitHub.Copilot.SDKdotnet add package GitHub.Copilot.SDK
Architecture Your App → SDK Client → [stdio/TCP] → Copilot CLI → Model Provider
↕
MCP Servers
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
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:
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" });
Custom Tools Define tools that Copilot can call:
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],
});
Tool Requirements
Handler must return JSON-serializable data (not undefined)
Parameters must follow JSON Schema format
Tool description should clearly state when to use
Hooks Intercept and customize session behavior at key lifecycle points:
Hook Trigger Use Case onPreToolUseBefore tool executes Permission control, argument modification onPostToolUseAfter tool executes Result transformation, logging, redaction onUserPromptSubmittedUser sends message Prompt modification, context injection onSessionStartSession begins Add context, configure session onSessionEndSession ends Cleanup, analytics, metrics onErrorOccurredError happens Custom error handling, retry logic
Pre-Tool Use Hook 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" };
},
},
});
Post-Tool Use Hook (Redaction) hooks : {
onPostToolUse : async (input) => {
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 ;
},
}
MCP Server Integration Connect to MCP servers for pre-built tool capabilities:
Local Stdio Server const session = await client.createSession ({
mcpServers : {
filesystem : {
type : "local" ,
command : "npx" ,
args : ["-y" , "@modelcontextprotocol/server-filesystem" , "/allowed/path" ],
tools : ["*" ],
env : { DEBUG : "true" },
cwd : "./servers" ,
timeout : 30000 ,
},
},
});
Remote HTTP Server const session = await client.createSession ({
mcpServers : {
github : {
type : "http" ,
url : "https://api.githubcopilot.com/mcp/" ,
headers : { Authorization : "Bearer ${TOKEN}" },
tools : ["*" ],
},
},
});
MCP Debugging
npx @modelcontextprotocol/inspector /path/to/your/mcp-server
Tools not appearing → Set tools: ["*"] and verify server responds to tools/list
Server not starting → Use absolute command paths, check cwd
Stdout pollution → Debug output must go to stderr, not stdout
Authentication
Methods (Priority Order)
Explicit token — githubToken in constructorHMAC key — CAPI_HMAC_KEY or COPILOT_HMAC_KEY env varsDirect API token — GITHUB_COPILOT_API_TOKEN with COPILOT_API_URLEnvironment variables — COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKENStored OAuth — From copilot auth loginGitHub CLI — gh auth credentials
OAuth GitHub App const client = new CopilotClient ({
githubToken : userAccessToken,
useLoggedInUser : false ,
});
Supported: gho_ (OAuth), ghu_ (GitHub App), github_pat_ (fine-grained PAT)
Not supported: ghp_ (classic PAT — deprecated)
BYOK (Bring Your Own Key) Use your own API keys — no Copilot subscription required:
Provider Configurations provider : { type : "openai" , baseUrl : "https://api.openai.com/v1" , apiKey : process.env .OPENAI_API_KEY }
provider : {
type : "openai" ,
baseUrl : "https://your-resource.openai.azure.com/openai/v1/" ,
apiKey : process.env .FOUNDRY_API_KEY ,
wireApi : "responses" ,
}
provider : {
type : "azure" ,
baseUrl : "https://my-resource.openai.azure.com" ,
apiKey : process.env .AZURE_OPENAI_KEY ,
azure : { apiVersion : "2024-10-21" },
}
provider : { type : "anthropic" , baseUrl : "https://api.anthropic.com" , apiKey : process.env .ANTHROPIC_API_KEY }
provider : { type : "openai" , baseUrl : "http://localhost:11434/v1" }
BYOK Limitations
Static credentials only — no native Entra ID, OIDC, or managed identity supportNo auto-refresh — expired tokens require creating a new sessionKeys not persisted — must re-provide provider config on session resume
Session Persistence Resume sessions across restarts by providing your own session ID:
const session = await client.createSession ({
sessionId : "user-123-task-456" ,
model : "gpt-4.1" ,
});
const resumed = await client.resumeSession ("user-123-task-456" );
await resumed.sendAndWait ({ prompt : "What did we discuss?" });
Session ID Best Practices Pattern Example Use Case user-{userId}-{taskId}user-alice-pr-review-42Multi-user apps tenant-{tenantId}-{workflow}tenant-acme-onboardingMulti-tenant SaaS {userId}-{taskType}-{timestamp}alice-deploy-1706932800Time-based cleanup
What Gets Persisted Data Persisted? Notes Conversation history ✅ Yes Full message thread Tool call results ✅ Yes Cached for context Agent planning state ✅ Yes plan.md fileProvider/API keys ❌ No Must re-provide on resume In-memory tool state ❌ No Design tools to be stateless
Infinite Sessions For long-running workflows that may exceed context limits:
const session = await client.createSession ({
infiniteSessions : {
enabled : true ,
backgroundCompactionThreshold : 0.80 ,
bufferExhaustionThreshold : 0.95 ,
},
});
Deployment Patterns
Local CLI (Default) const client = new CopilotClient ();
External CLI Server (Backend Services) copilot --headless --port 4321
const client = new CopilotClient ({ cliUrl : "localhost:4321" });
Docker Compose services:
copilot-cli:
image: ghcr.io/github/copilot-cli:latest
command: ["--headless" , "--port" , "4321" ]
environment:
- COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}
volumes:
- session-data:/root/.copilot/session-state
api:
build: .
environment:
- CLI_URL=copilot-cli:4321
depends_on: [copilot-cli ]
volumes:
session-data:
Session Isolation Patterns Pattern Isolation Resources Best For CLI per user Complete High Multi-tenant SaaS, compliance Shared CLI + session IDs Logical Low Internal tools Shared sessions None Low Team collaboration (requires locking)
Production Checklist
Session cleanup: periodic deletion of expired sessions
Health checks: ping CLI server, restart if unresponsive
Persistent storage: mount ~/.copilot/session-state/ for containers
Secret management: use Vault/K8s Secrets for tokens
Session locking: Redis or similar for shared session access
Graceful shutdown: drain active sessions before stopping CLI
Configuration Reference
Client Configuration Option Type Default Description cliPathstring Auto-detected Path to Copilot CLI executable cliUrlstring — URL of external CLI server githubTokenstring — GitHub token for auth useLoggedInUserboolean trueUse stored CLI credentials logLevelstring "none""none" | "error" | "warning" | "info" | "debug"autoRestartboolean trueAuto-restart CLI on crash
Session Configuration Option Type Description modelstring Model to use (e.g., "gpt-4.1", "claude-sonnet-4") sessionIdstring Custom ID for resumable sessions streamingboolean Enable streaming responses toolsTool[] Custom tools mcpServersobject MCP server configurations hooksobject Session hooks providerobject BYOK provider config customAgentsobject[] Custom agent definitions systemMessageobject System message override skillDirectoriesstring[] Directories to load skills from infiniteSessionsobject Auto-compaction config
API Summary Language Client Session Create Send Resume Stop Node.js new CopilotClient()client.createSession()session.sendAndWait()client.resumeSession()client.stop()Python CopilotClient()client.create_session()session.send_and_wait()client.resume_session()client.stop()Go copilot.NewClient(nil)client.CreateSession()session.SendAndWait()client.ResumeSession()client.Stop().NET new CopilotClient()client.CreateSessionAsync()session.SendAndWaitAsync()client.ResumeSessionAsync()client.DisposeAsync()
References 