Configuración del SDK de Copilot para los servicios de back-end

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

La CLI se ejecuta como un servidor sin encabezado al que se conecta el código back-end a través de la red.

          **Lo mejor para:** Back-end de aplicaciones web, servicios de API, herramientas internas, integraciones de CI/CD, cualquier carga de trabajo del lado servidor.

Cómo funciona

En lugar del SDK que genera un proceso secundario de la CLI, ejecute la CLI de forma independiente en modo de servidor sin encabezado. El backend se conecta a través de TCP mediante la opción cliUrl. Para obtener diagramas detallados de la arquitectura del servidor sin encabezado y cómo se compara con la CLI administrada automáticamente predeterminada, consulte el github/copilot-sdkrepositorio.

Características clave:

• La CLI se ejecuta como un proceso de servidor persistente, no generado por solicitud.
• El SDK se conecta a través de TCP: la CLI y la aplicación se pueden ejecutar en contenedores diferentes.
• Varios clientes del SDK pueden compartir un servidor de la CLI.
• Funciona con cualquier método de autenticación (GitHub tokens, variables de entorno, BYOK).

Paso 1: Iniciar la CLI en modo sin encabezado

Ejecute la CLI como servidor en segundo plano.

# 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

Para producción, ejecútelo como un servicio del sistema o en un contenedor:

# 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

Paso 2: Conexión del 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})

Go

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

Autenticación para servicios back-end

Tokens de variables de entorno

El enfoque más sencillo: establezca un token en el servidor de la CLI:

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

Reemplace YOUR-SERVICE-ACCOUNT-TOKEN con su GitHubpersonal access token token OAuth para la cuenta de servicio.

Tokens de usuario individual (OAuth)

Pase tokens de usuario individuales al crear sesiones:

// 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 (sin GitHub autenticación)

Use sus propias claves de API para el proveedor de modelos:

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

Patrones de back-end comunes

API web con 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);

Trabajo en segundo plano

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
}

Implementación de 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:

Exámenes de salud

Supervise el estado del servidor de la CLI:

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

Limpieza de sesión

Los servicios back-end deben limpiar activamente las sesiones para evitar pérdidas de recursos:

// 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);

Limitaciones

Limitación	Detalles

          **Servidor de la CLI único = punto único de error** | Considere los patrones de alta disponibilidad para las implementaciones de producción. |

| Ninguna autenticación integrada entre el SDK y la CLI | Proteja la ruta de acceso de red (el mismo host, VPC, etc.). | | Estado de sesión en el disco local | Monte el almacenamiento persistente para los reinicios del contenedor. | | Tiempo de espera de inactividad de 30 minutos | Las sesiones sin actividad se limpian automáticamente. |

Pasos siguientes

• Para la instalación y el primer mensaje, consulte Introducción al SDK de Copilot.
• Para obtener información sobre cómo reanudar sesiones entre reinicios, consulte Persistencia de sesión en el github/copilot-sdk repositorio.
• Para obtener información sobre cómo agregar autenticación de usuario, consulte GitHub OAuth en el github/copilot-sdk repositorio.