SDK GitHub Copilot

Construisez des applications qui interagissent de manière programmatique avec GitHub Copilot. Le SDK enveloppe l'interface CLI Copilot via JSON-RPC, fournissant la gestion des sessions, les outils personnalisés, les hooks, l'intégration MCP server et le streaming sur Node.js, Python, Go et .NET.

Prérequis

• GitHub Copilot CLI installé et authentifié (copilot --version)
• Abonnement GitHub Copilot (Individual, Business ou Enterprise) — non requis pour BYOK
• Runtime : Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+

Installation

Architecture

Le SDK communique avec l'interface CLI Copilot via JSON-RPC sur stdio (par défaut) ou TCP. L'interface CLI gère les appels de modèle, l'exécution des outils, l'état de la session et le cycle de vie du MCP server.

Votre app → Client SDK → [stdio/TCP] → CLI Copilot → Fournisseur de modèle
                                          ↕
                                     Serveurs MCP

Modes de transport :

Motif fondamental : Client → Session → Message

Tous les usages du SDK suivent : créer un client, créer une session, envoyer des 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);

Réponses en streaming

Activez la sortie en temps réel en définissant streaming: true et en vous abonnant aux événements delta.

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"})

Abonnement aux événements

Appelez la fonction retournée pour vous désabonner. Dans .NET, appelez .Dispose() sur le disposable retourné.

Outils personnalisés

Définissez des outils que Copilot peut appeler pour étendre ses capacités.

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],
});

Exigences des outils

• Le handler doit retourner des données sérialisables en JSON (pas undefined)
• Les paramètres doivent suivre le format JSON Schema
• La description de l'outil doit clairement indiquer quand il doit être utilisé

Hooks

Interceptez et personnalisez le comportement de la session à des points clés du cycle de vie.

Hook de pré-utilisation d'outil

Contrôlez les permissions de l'outil, modifiez les arguments ou injectez du contexte avant l'exécution de l'outil.

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" };
        },
    },
});

Champs d'entrée : timestamp, cwd, toolName, toolArgs

Champs de sortie :

Hook de post-utilisation d'outil

Transformez les résultats, rédigez les données sensibles ou enregistrez l'activité de l'outil après l'exécution.

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
    },
}

Champs de sortie : modifiedResult, additionalContext, suppressOutput

Hook de soumission du prompt utilisateur

Modifiez ou améliorez les prompts utilisateur avant traitement. Utile pour les modèles de prompt, l'injection de contexte et la validation d'entrée.

hooks: {
    onUserPromptSubmitted: async (input) => {
        return {
            modifiedPrompt: `[User from engineering team] ${input.prompt}`,
            additionalContext: "Follow company coding standards.",
        };
    },
}

Champs de sortie : modifiedPrompt, additionalContext, suppressOutput

Hooks du cycle de vie de la session

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;
    },
}

Hook de gestion des erreurs

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
    },
}

Champs de sortie : suppressOutput, errorHandling ("retry" | "skip" | "abort"), retryCount, userNotification

Exemple de hook Python

async def on_pre_tool_use(input_data, invocation):
    if input_data["toolName"] in ["shell", "bash"]:
        return {"permissionDecision": "deny", "permissionDecisionReason": "Not permitted"}
    return {"permissionDecision": "allow"}

session = await client.create_session({
    "hooks": {"on_pre_tool_use": on_pre_tool_use}
})

Exemple de hook Go

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Hooks: &copilot.SessionHooks{
        OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
            return &copilot.PreToolUseHookOutput{PermissionDecision: "allow"}, nil
        },
    },
})

Intégration MCP Server

Connectez-vous à des serveurs MCP (Model Context Protocol) pour obtenir des capacités d'outils pré-construits.

Serveur Stdio local

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,
        },
    },
});

Serveur HTTP distant

const session = await client.createSession({
    mcpServers: {
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
            headers: { Authorization: "Bearer ${TOKEN}" },
            tools: ["*"],
        },
    },
});

Champs de configuration MCP

Local/Stdio :

HTTP distant :

Débogage MCP

Testez les serveurs MCP indépendamment avant l'intégration :

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

Utilisez MCP Inspector pour le débogage interactif :

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Problèmes MCP courants :

• Les outils n'apparaissent pas → Définissez tools: ["*"] et vérifiez que le serveur répond à tools/list
• Le serveur ne démarre pas → Utilisez les chemins de commande absolus, vérifiez cwd
• Pollution de stdout → La sortie de débogage doit aller à stderr, pas à stdout

Authentification

Méthodes (ordre de priorité)

1. Token explicite — githubToken dans le constructeur
2. Clé HMAC — Variables d'environnement CAPI_HMAC_KEY ou COPILOT_HMAC_KEY
3. Token API direct — GITHUB_COPILOT_API_TOKEN avec COPILOT_API_URL
4. Variables d'environnement — COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN
5. OAuth stocké — De copilot auth login
6. GitHub CLI — Identifiants gh auth

Token par programmation

const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });

Application GitHub OAuth

Pour les applications multi-utilisateurs où les utilisateurs se connectent avec GitHub :

const client = new CopilotClient({
    githubToken: userAccessToken,    // gho_ or ghu_ token from OAuth flow
    useLoggedInUser: false,          // Don't use stored CLI credentials
});

Types de token supportés : gho_ (OAuth), ghu_ (GitHub App), github_pat_ (PAT à grain fin). Non supporté : ghp_ (PAT classique — déprécié).

Désactiver la connexion automatique

Empêchez le SDK d'utiliser les identifiants stockés :

const client = new CopilotClient({ useLoggedInUser: false });

BYOK (Bring Your Own Key)

Utilisez vos propres clés API — aucun abonnement Copilot requis. L'interface CLI agit comme runtime d'agent uniquement.

Configurations de fournisseur

OpenAI :

provider: { type: "openai", baseUrl: "https://api.openai.com/v1", apiKey: process.env.OPENAI_API_KEY }

Azure AI Foundry (compatible OpenAI) :

provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // Use "responses" for GPT-5 series, "completions" for others
}

Azure OpenAI (endpoint natif) :

provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",  // Just the host — no /openai/v1
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: { apiVersion: "2024-10-21" },
}

Anthropic :

provider: { type: "anthropic", baseUrl: "https://api.anthropic.com", apiKey: process.env.ANTHROPIC_API_KEY }

Ollama (local) :

provider: { type: "openai", baseUrl: "http://localhost:11434/v1" }

Référence de configuration du fournisseur

Azure Managed Identity avec BYOK

Utilisez DefaultAzureCredential pour obtenir des tokens bearer de courte durée pour les déploiements Azure :

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient, ProviderConfig, SessionConfig

credential = DefaultAzureCredential()
token = credential.get_token("https://cognitiveservices.azure.com/.default").token

session = await client.create_session(SessionConfig(
    model="gpt-4.1",
    provider=ProviderConfig(
        type="openai",
        base_url=f"{foundry_url}/openai/v1/",
        bearer_token=token,
        wire_api="responses",
    ),
))

Note : Les tokens bearer expirent (~1 heure). Pour les applications longues, actualisez le token avant chaque nouvelle session. Le SDK n'actualise pas automatiquement les tokens.

Limitations BYOK

• Identifiants statiques uniquement — pas de support natif Entra ID, OIDC ou managed identity
• Pas d'actualisation automatique — les tokens expirés nécessitent de créer une nouvelle session
• Les clés ne sont pas persistées — vous devez fournir à nouveau la configuration provider lors de la reprise de session
• Disponibilité des modèles — limitée à ce que votre fournisseur propose

Persistence de session

Reprenez les sessions après les redémarrages en fournissant votre propre ID de session.

// Create with explicit ID
const session = await client.createSession({
    sessionId: "user-123-task-456",
    model: "gpt-4.1",
});

// Resume later (even from a different client instance)
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });

Gestion des sessions

const sessions = await client.listSessions();           // List all
const lastId = await client.getLastSessionId();          // Get most recent
await client.deleteSession("user-123-task-456");         // Delete from storage
await session.destroy();                                 // Destroy active session

Options de reprise

Lors de la reprise, vous pouvez reconfigurer : model, systemMessage, availableTools, excludedTools, provider (requis pour BYOK), reasoningEffort, streaming, mcpServers, customAgents, skillDirectories, infiniteSessions.

Bonnes pratiques pour les ID de session

Quelles données sont persistées

L'état de la session est enregistré dans ~/.copilot/session-state/{sessionId}/ :

Sessions infinies

Pour les workflows longues qui peuvent dépasser les limites de contexte, activez la compaction automatique :

const session = await client.createSession({
    infiniteSessions: {
        enabled: true,
        backgroundCompactionThreshold: 0.80,  // Start background compaction at 80%
        bufferExhaustionThreshold: 0.95,       // Block and compact at 95%
    },
});

Les seuils sont des rapports d'utilisation du contexte (0,0–1,0), pas des nombres de tokens absolus.

Agents personnalisés

Définissez des personas d'IA spécialisées :

const session = await client.createSession({
    customAgents: [{
        name: "pr-reviewer",
        displayName: "PR Reviewer",
        description: "Reviews pull requests for best practices",
        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
    }],
});

Message système

Contrôlez le comportement et la personnalité de l'IA :

const session = await client.createSession({
    systemMessage: { content: "You are a helpful assistant. Always be concise." },
});

Intégration des skills

Chargez les répertoires de skills pour étendre les capacités de Copilot :

const session = await client.createSession({
    skillDirectories: ["./skills/code-review", "./skills/documentation"],
    disabledSkills: ["experimental-feature"],
});

Les skills peuvent être combinées avec des agents personnalisés et des serveurs MCP :

const session = await client.createSession({
    skillDirectories: ["./skills/security"],
    customAgents: [{ name: "auditor", prompt: "Focus on OWASP Top 10." }],
    mcpServers: { postgres: { type: "local", command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], tools: ["*"] } },
});

Gestionnaires de permissions et d'entrées

Traitez les permissions d'outils et les demandes d'entrée utilisateur de manière programmatique. Le SDK utilise un modèle de permission deny-by-default — toutes les demandes de permission sont refusées sauf si vous fournissez un gestionnaire.

const session = await client.createSession({
    onPermissionRequest: async (request) => {
        if (request.kind === "shell") {
            return { approved: request.command.startsWith("git") };
        }
        return { approved: true };
    },
    onUserInputRequest: async (request) => {
        return { response: "yes" };
    },
});

Suivi de l'utilisation des tokens

Abonnez-vous aux événements d'utilisation au lieu d'utiliser /usage CLI :

session.on("assistant.usage", (event) => {
    console.log("Tokens:", { input: event.data.inputTokens, output: event.data.outputTokens });
});

Modèles de déploiement

CLI local (par défaut)

Le SDK lance automatiquement l'interface CLI en tant que sous-processus. Configuration la plus simple — zéro configuration.

const client = new CopilotClient(); // Auto-manages CLI process

Serveur CLI externe (services backend)

Exécutez l'interface CLI en mode headless, connectez le SDK via TCP :

copilot --headless --port 4321

const client = new CopilotClient({ cliUrl: "localhost:4321" });

Support multi-clients : Plusieurs clients SDK peuvent partager un serveur CLI.

CLI intégré (applications de bureau)

Livrez le binaire CLI avec votre application :

const client = new CopilotClient({ cliPath: path.join(__dirname, "vendor", "copilot") });

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:

Modèles d'isolation de session

Checklist de production

• Nettoyage de session : suppression périodique des sessions expirées
• Contrôles de santé : ping du serveur CLI, redémarrage s'il ne répond pas
• Stockage persistant : montez ~/.copilot/session-state/ pour les conteneurs
• Gestion des secrets : utilisez Vault/K8s Secrets pour les tokens
• Verrouillage de session : Redis ou similaire pour l'accès aux sessions partagées
• Arrêt gracieux : videz les sessions actives avant d'arrêter l'interface CLI

Configuration du client

Configuration de session

Comparaison des features SDK vs CLI

✅ Disponible dans le SDK

Gestion des sessions, messages (send/sendAndWait/abort), historique des messages (getMessages), outils personnalisés, hooks de permission d'outils, serveurs MCP (locaux + HTTP), streaming, sélection de modèle, fournisseurs BYOK, agents personnalisés, message système, skills, sessions infinies, gestionnaires de permission, 40+ types d'événements.

❌ Features CLI uniquement

Export de session (--share), commandes slash, interface interactive, rendu du terminal, mode YOLO, flux de connexion/déconnexion, /compact (utilisez infiniteSessions à la place), /usage (utilisez les événements d'utilisation), /review, /delegate.

Contournements :

• Export de session → Collectez les événements manuellement avec session.on() + session.getMessages()
• Contrôle des permissions → Utilisez le gestionnaire onPermissionRequest au lieu de --allow-all-paths
• Compaction de contexte → Utilisez la configuration infiniteSessions au lieu de /compact

Débogage

Activez le logging de débogage :

const client = new CopilotClient({ logLevel: "debug" });

Répertoire de logs personnalisé :

const client = new CopilotClient({ cliArgs: ["--log-dir", "/path/to/logs"] });

Problèmes courants

État de connexion

console.log("State:", client.getState());  // "connected" after start()
client.on("stateChange", (state) => console.log("Changed to:", state));

Résumé des API clés

Références

• GitHub Copilot SDK
• Installation de Copilot CLI
• Spécification du protocole MCP
• Répertoire des serveurs MCP
• Serveur GitHub MCP