Configuration du Kit de développement logiciel (SDK) Copilot pour les services principaux

Remarque

SDK Copilot est actuellement en préversion technique. Les fonctionnalités et la disponibilité sont susceptibles de changer.

L’interface CLI s’exécute en tant que serveur sans tête auquel votre code principal se connecte sur le réseau.

          **Meilleur pour :** Back-ends d’application web, services API, outils internes, intégrations CI/CD, n’importe quelle charge de travail côté serveur.

Fonctionnement

Au lieu du SDK qui génère un processus enfant CLI, vous exécutez l’interface CLI indépendamment en mode serveur sans tête. Votre back-end se connecte à celui-ci via TCP à l’aide de l’option cliUrl . Pour obtenir des diagrammes détaillés de l’architecture du serveur sans tête et la façon dont il se compare à l’interface CLI gérée automatiquement par défaut, consultez le github/copilot-sdkréférentiel.

Principales caractéristiques :

L’interface CLI s’exécute en tant que processus de serveur persistant, pas généré par requête.
Le Kit de développement logiciel (SDK) se connecte via TCP : l’interface CLI et l’application peuvent s’exécuter dans différents conteneurs.
Plusieurs clients du Kit de développement logiciel (SDK) peuvent partager un serveur CLI.
Fonctionne avec n’importe quelle méthode d’authentification (GitHub jetons, variables d’environnement, BYOK).

Étape 1 : Démarrer l’interface CLI en mode sans tête

Exécutez l’interface CLI en tant que serveur en arrière-plan.

# Start with a specific port
copilot --headless --port 4321

# Or let it pick a random port (prints the URL)
copilot --headless
# Output: Listening on http://localhost:52431

Pour la production, exécutez-le en tant que service système ou dans un conteneur :

# Docker
docker run -d --name copilot-cli \
    -p 4321:4321 \
    -e COPILOT_GITHUB_TOKEN="$TOKEN" \
    ghcr.io/github/copilot-cli:latest \
    --headless --port 4321

# systemd
[Service]
ExecStart=/usr/local/bin/copilot --headless --port 4321
Environment=COPILOT_GITHUB_TOKEN=YOUR-GITHUB-TOKEN
Restart=always

Étape 2 : Connecter le Kit de développement logiciel (SDK)

Node.js / TypeScript

import { CopilotClient } from "@github/copilot-sdk";

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

const session = await client.createSession({
    sessionId: `user-${userId}-${Date.now()}`,
    model: "gpt-4.1",
});

const response = await session.sendAndWait({ prompt: req.body.message });
res.json({ content: response?.data.content });

Python

from copilot import CopilotClient

client = CopilotClient({
    "cli_url": "localhost:4321",
})
await client.start()

session = await client.create_session({
    "session_id": f"user-{user_id}-{int(time.time())}",
    "model": "gpt-4.1",
})

response = await session.send_and_wait({"prompt": message})

Allez

client := copilot.NewClient(&copilot.ClientOptions{
    CLIUrl: "localhost:4321",
})
client.Start(ctx)
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    SessionID: fmt.Sprintf("user-%s-%d", userID, time.Now().Unix()),
    Model:     "gpt-4.1",
})

response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message})

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    CliUrl = "localhost:4321",
    UseStdio = false,
});

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    SessionId = $"user-{userId}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}",
    Model = "gpt-4.1",
});

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = message });

Authentification pour les services principaux

Jetons de variables d'environnement

L’approche la plus simple : définissez un jeton sur le serveur CLI :

# All requests use this token
export COPILOT_GITHUB_TOKEN="YOUR-SERVICE-ACCOUNT-TOKEN"
copilot --headless --port 4321

Remplacez YOUR-SERVICE-ACCOUNT-TOKEN par votre jeton d'accès OAuth GitHubpersonal access token du compte de service.

Jetons OAuth par utilisateur

Transmettez des jetons d’utilisateur individuels lors de la création de sessions :

// Your API receives user tokens from your auth layer
app.post("/chat", authMiddleware, async (req, res) => {
    const client = new CopilotClient({
        cliUrl: "localhost:4321",
        githubToken: req.user.githubToken,
        useLoggedInUser: false,
    });

    const session = await client.createSession({
        sessionId: `user-${req.user.id}-chat`,
        model: "gpt-4.1",
    });

    const response = await session.sendAndWait({
        prompt: req.body.message,
    });

    res.json({ content: response?.data.content });
});

BYOK (aucune GitHub authentification)

Utilisez vos propres clés API pour le fournisseur de modèles :

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

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

Modèles courants de backend

API web avec Express

import express from "express";
import { CopilotClient } from "@github/copilot-sdk";

const app = express();
app.use(express.json());

// Single shared CLI connection
const client = new CopilotClient({
    cliUrl: process.env.CLI_URL || "localhost:4321",
});

app.post("/api/chat", async (req, res) => {
    const { sessionId, message } = req.body;

    // Create or resume session
    let session;
    try {
        session = await client.resumeSession(sessionId);
    } catch {
        session = await client.createSession({
            sessionId,
            model: "gpt-4.1",
        });
    }

    const response = await session.sendAndWait({ prompt: message });
    res.json({
        sessionId,
        content: response?.data.content,
    });
});

app.listen(3000);

Travailleur en arrière-plan

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
    cliUrl: process.env.CLI_URL || "localhost:4321",
});

// Process jobs from a queue
async function processJob(job: Job) {
    const session = await client.createSession({
        sessionId: `job-${job.id}`,
        model: "gpt-4.1",
    });

    const response = await session.sendAndWait({
        prompt: job.prompt,
    });

    await saveResult(job.id, response?.data.content);
    await session.disconnect(); // Clean up after job completes
}

Déploiement Docker Compose

version: "3.8"

services:
  copilot-cli:
    image: ghcr.io/github/copilot-cli:latest
    command: ["--headless", "--port", "4321"]
    environment:
      - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}
    ports:
      - "4321:4321"
    restart: always
    volumes:
      - session-data:/root/.copilot/session-state

  api:
    build: .
    environment:
      - CLI_URL=copilot-cli:4321
    depends_on:
      - copilot-cli
    ports:
      - "3000:3000"

volumes:
  session-data:

Contrôles de santé

Surveillez l’intégrité du serveur CLI :

// Periodic health check
async function checkCLIHealth(): Promise<boolean> {
    try {
        const status = await client.getStatus();
        return status !== undefined;
    } catch {
        return false;
    }
}

Nettoyage de session

Les services principaux doivent nettoyer activement les sessions pour éviter les fuites de ressources :

// Clean up expired sessions periodically
async function cleanupSessions(maxAgeMs: number) {
    const sessions = await client.listSessions();
    const now = Date.now();

    for (const session of sessions) {
        const age = now - new Date(session.createdAt).getTime();
        if (age > maxAgeMs) {
            await client.deleteSession(session.sessionId);
        }
    }
}

// Run every hour
setInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000);

Limites

Limitation	Détails

          **Serveur CLI unique = point de défaillance unique** | Tenez compte des modèles de haute disponibilité pour les déploiements de production. |

| Aucune authentification intégrée entre le SDK et l’interface CLI | Sécurisez le chemin d’accès réseau (même hôte, VPC, etc.). | | État de session sur le disque local | Monter le stockage persistant au moment des redémarrages de conteneur. | | Délai d’inactivité de 30 minutes | Les sessions sans activité sont automatiquement nettoyées. |

Étapes suivantes

Pour l’installation et votre premier message, consultez Getting started avec le Kit de développement logiciel (SDK) Copilot.
Pour plus d’informations sur la reprise des sessions entre les redémarrages, consultez la Persistance de session dans le github/copilot-sdk référentiel.
Pour plus d’informations sur l’ajout de l’authentification utilisateur, consultez GitHub OAuth dans le github/copilot-sdk référentiel.