Reprise de session et persistance

Fonctionnement des sessions

Lorsque vous créez une session, l’interface cli Copilot gère l’historique des conversations, l’état de l’outil et le contexte de planification. Par défaut, cet état vit en mémoire et disparaît lorsque la session se termine. Une fois la persistance activée, vous pouvez reprendre des sessions entre les redémarrages, les migrations de conteneurs ou même différentes instances clientes.

State	Que se passe-t-il ?
Créer
session_id Attribué
Active	Envoyer des invites, des appels d’outils, des réponses
suspendu	État enregistré sur le disque
Resume	État chargé à partir du disque

Démarrage rapide : création d’une session pouvant être reprise

La clé des sessions reprenables est de fournir votre propre session_id. Sans un, le SDK génère un ID aléatoire et la session ne peut pas être reprise ultérieurement.

TypeScript

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

const client = new CopilotClient();

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

// Do some work...
await session.sendAndWait({ prompt: "Analyze my codebase" });

// Session state is automatically persisted
// You can safely close the client

Python

from copilot import CopilotClient
from copilot.session import PermissionHandler

client = CopilotClient()
await client.start()

# Create a session with a meaningful ID
session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", session_id="user-123-task-456")

# Do some work...
await session.send_and_wait("Analyze my codebase")

# Session state is automatically persisted

Allez

package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)

    session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
        SessionID: "user-123-task-456",
        Model:     "gpt-5.2-codex",
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })

    session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Analyze my codebase"})
    _ = session
}

ctx := context.Background()
client := copilot.NewClient(nil)

// Create a session with a meaningful ID
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    SessionID: "user-123-task-456",
    Model:     "gpt-5.2-codex",
})

// Do some work...
session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Analyze my codebase"})

// Session state is automatically persisted

C# (.NET)

using GitHub.Copilot;

var client = new CopilotClient();

// Create a session with a meaningful ID
var session = await client.CreateSessionAsync(new SessionConfig
{
    SessionId = "user-123-task-456",
    Model = "gpt-5.2-codex",
});

// Do some work...
await session.SendAndWaitAsync(new MessageOptions { Prompt = "Analyze my codebase" });

// Session state is automatically persisted

Reprise d’une session

Plus tard, minutes, heures ou même jours, vous pouvez reprendre la session à partir de l’endroit où vous vous êtes arrêté.

TypeScript

// Resume from a different client instance (or after restart)
const session = await client.resumeSession("user-123-task-456");

// Continue where you left off
await session.sendAndWait({ prompt: "What did we discuss earlier?" });

Python

# Resume from a different client instance (or after restart)
session = await client.resume_session("user-123-task-456", on_permission_request=PermissionHandler.approve_all)

# Continue where you left off
await session.send_and_wait("What did we discuss earlier?")

Allez

package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)

    session, _ := client.ResumeSession(ctx, "user-123-task-456", nil)

    session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What did we discuss earlier?"})
    _ = session
}

ctx := context.Background()

// Resume from a different client instance (or after restart)
session, _ := client.ResumeSession(ctx, "user-123-task-456", nil)

// Continue where you left off
session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What did we discuss earlier?"})

C# (.NET)

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

public static class ResumeSessionExample
{
    public static async Task Main()
    {
        await using var client = new CopilotClient();

        var session = await client.ResumeSessionAsync("user-123-task-456", new ResumeSessionConfig
        {
            OnPermissionRequest = (req, inv) =>
                Task.FromResult(PermissionDecision.ApproveOnce()),
        });

        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What did we discuss earlier?" });
    }
}

// Resume from a different client instance (or after restart)
var session = await client.ResumeSessionAsync("user-123-task-456");

// Continue where you left off
await session.SendAndWaitAsync(new MessageOptions { Prompt = "What did we discuss earlier?" });

Options de reprise

Lors de la reprise d’une session, vous pouvez éventuellement reconfigurer de nombreux paramètres. Cela est utile lorsque vous devez modifier le modèle, mettre à jour les configurations de l’outil ou modifier le comportement.

Option	Description
model	Modifier le modèle de la session reprise
systemMessage	Remplacer ou étendre l’invite système
availableTools	Restreindre les outils disponibles
excludedTools	Désactiver des outils spécifiques
provider	Fournir à nouveau des informations d’identification BYOK (requises pour les sessions BYOK)
reasoningEffort	Ajuster le niveau d’effort de raisonnement
streaming	Activer/désactiver les réponses de diffusion en continu
workingDirectory	Modifier le répertoire de travail
configDir	Remplacer le répertoire de configuration
mcpServers	Configurer les serveurs MCP
customAgents	Configurer des agents personnalisés
agent	Pré-sélection d’un agent personnalisé par nom
skillDirectories	Répertoires à partir duquel charger des compétences
disabledSkills	Compétences à désactiver
infiniteSessions	Configurer le comportement de session infinie

Exemple : changement de modèle à la reprise

// Resume with a different model
const session = await client.resumeSession("user-123-task-456", {
  model: "claude-sonnet-4",  // Switch to a different model
  reasoningEffort: "high",   // Increase reasoning effort
});

Utilisation de BYOK (apportez votre propre clé) avec des sessions reprise

Lorsque vous utilisez vos propres clés API, vous devez fournir à nouveau la configuration du fournisseur lors de la reprise. Les clés API ne sont jamais conservées sur le disque pour des raisons de sécurité.

// Original session with BYOK
const session = await client.createSession({
  sessionId: "user-123-task-456",
  model: "gpt-5.2-codex",
  provider: {
    type: "azure",
    endpoint: "https://my-resource.openai.azure.com",
    apiKey: process.env.AZURE_OPENAI_KEY,
    deploymentId: "my-gpt-deployment",
  },
});

// When resuming, you MUST re-provide the provider config
const resumed = await client.resumeSession("user-123-task-456", {
  provider: {
    type: "azure",
    endpoint: "https://my-resource.openai.azure.com",
    apiKey: process.env.AZURE_OPENAI_KEY,  // Required again
    deploymentId: "my-gpt-deployment",
  },
});

Qu’est-ce qui est conservé ?

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

~/.copilot/session-state/
└── user-123-task-456/
    ├── checkpoints/           # Conversation history snapshots
    │   ├── 001.json          # Initial state
    │   ├── 002.json          # After first interaction
    │   └── ...               # Incremental checkpoints
    ├── plan.md               # Agent's planning state (if any)
    └── files/                # Session artifacts
        ├── analysis.md       # Files the agent created
        └── notes.txt         # Working documents

Data	Persisté?	Remarques
Historique des conversations
✅ Oui	Fil de message complet
Résultats des appels d’outil
✅ Oui	Mis en cache pour le contexte
État de planification de l’agent
✅ Oui	Fichier plan.md
Artefacts de session
✅ Oui	Dans files/ le répertoire
Clés fournisseur/API
❌ Non	Sécurité : doit re-fournir
État de l’outil en mémoire
❌ Non	Les outils doivent être sans état

Bonnes pratiques relatives à l’ID de session

Choisissez les ID de session qui encodent la propriété et l’objectif. Cela facilite beaucoup l’audit et le nettoyage.

Pattern	Example	Cas d’usage
❌
abc123
ID aléatoires	Difficile à auditer, aucune information sur la propriété
✅
user-{userId}-{taskId}
user-alice-pr-review-42	Applications multi-utilisateurs
✅
tenant-{tenantId}-{workflow}
tenant-acme-onboarding	SaaS multilocataire
✅
{userId}-{taskId}-{timestamp}
alice-deploy-1706932800	Nettoyage basé sur le temps

Avantages des ID structurés :

• Simple à auditer : « Afficher toutes les sessions pour l’utilisateur alice »
• Nettoyer facilement : « Supprimer toutes les sessions antérieures à X »
• Contrôle d’accès naturel : Analyser l’ID utilisateur à partir de l’ID de session

Exemple : génération d’ID de session

function createSessionId(userId: string, taskType: string): string {
  const timestamp = Date.now();
  return `${userId}-${taskType}-${timestamp}`;
}

const sessionId = createSessionId("alice", "code-review");
// → "alice-code-review-1706932800000"

import time

def create_session_id(user_id: str, task_type: str) -> str:
    timestamp = int(time.time())
    return f"{user_id}-{task_type}-{timestamp}"

session_id = create_session_id("alice", "code-review")
# → "alice-code-review-1706932800"

Gestion du cycle de vie des sessions

Liste des sessions actives

// List all sessions
const sessions = await client.listSessions();
console.log(`Found ${sessions.length} sessions`);

for (const session of sessions) {
  console.log(`- ${session.sessionId} (created: ${session.createdAt})`);
}

// Filter sessions by repository
const repoSessions = await client.listSessions({ repository: "owner/repo" });

Nettoyage des anciennes sessions

async function cleanupExpiredSessions(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);
      console.log(`Deleted expired session: ${session.sessionId}`);
    }
  }
}

// Clean up sessions older than 24 hours
await cleanupExpiredSessions(24 * 60 * 60 * 1000);

Déconnexion d’une session (disconnect)

Lorsqu’une tâche est terminée, déconnectez-vous de la session explicitement plutôt que d’attendre des délais d’expiration. Cette opération libère des ressources en mémoire, mais conserve les données de session sur le disque, de sorte que la session peut toujours être reprise ultérieurement :

try {
  // Do work...
  await session.sendAndWait({ prompt: "Complete the task" });
  
  // Task complete — release in-memory resources (session can be resumed later)
  await session.disconnect();
} catch (error) {
  // Clean up even on error
  await session.disconnect();
  throw error;
}

Chaque KIT SDK fournit également des modèles de nettoyage automatique idiomatiques :

Language	Pattern	Example
TypeScript	Symbol.asyncDispose	await using session = await client.createSession(config);
Python
async with gestionnaire de contexte	async with await client.create_session(on_permission_request=handler) as session:
C#	IAsyncDisposable	await using var session = await client.CreateSessionAsync(config);
Go	defer	defer session.Disconnect()

Suppression définitive d’une session (deleteSession)

Pour supprimer définitivement une session et toutes ses données du disque (historique des conversations, état de planification, artefacts), utilisez deleteSession. Cela est irréversible : la session ne peut pas être reprise après la suppression :

// Permanently remove session data
await client.deleteSession("user-123-task-456");

disconnect() vs deleteSession():disconnect() libère des ressources en mémoire, mais conserve les données de session sur le disque pour une reprise ultérieure. deleteSession() supprime définitivement tout, y compris les fichiers sur le disque.

Nettoyage automatique : temporisation d'inactivité

Par défaut, les sessions n’ont pas de délai d’inactivité et vivent indéfiniment jusqu’à ce qu’elles aient été explicitement déconnectées ou supprimées. Vous pouvez éventuellement configurer un délai d’inactivité à l’échelle du serveur via CopilotClientOptions.sessionIdleTimeoutSeconds:

const client = new CopilotClient({
  sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes
});

Lorsqu’un délai d’expiration est configuré, les sessions sans activité pendant cette durée sont automatiquement nettoyées. Définissez sur 0 ou omettez pour désactiver.

Les sessions avec travail actif (commandes en cours d’exécution, agents en arrière-plan) sont toujours protégées contre le nettoyage inactif, quel que soit le paramètre de délai d’expiration.

Surveillez les événements d’inactivité pour réagir à l’inactivité de la session :

session.on("session.idle", (event) => {
  console.log(`Session idle for ${event.idleDurationMs}ms`);
});

Modèles de déploiement

Modèle 1 : un serveur CLI par utilisateur (recommandé)

Idéal pour : isolation forte, environnements multilocataires, Azure sessions dynamiques.

**Avantages:**✅ Isolation complète | ✅ Sécurité simple | ✅ Mise à l’échelle simple

Modèle 2 : serveur CLI partagé (ressource efficace)

Idéal pour : outils internes, environnements approuvés, configurations contraintes de ressources.

Exigences:

• ⚠️ ID de session uniques par utilisateur
• ⚠️ Contrôle d’accès au niveau de l’application
• ⚠️ Validation de l’ID de session avant les opérations

// Application-level access control for shared CLI
async function resumeSessionWithAuth(
  client: CopilotClient,
  sessionId: string,
  currentUserId: string
): Promise<Session> {
  // Parse user from session ID
  const [sessionUserId] = sessionId.split("-");
  
  if (sessionUserId !== currentUserId) {
    throw new Error("Access denied: session belongs to another user");
  }
  
  return client.resumeSession(sessionId);
}

sessions dynamiques Azure

Pour les déploiements serverless/conteneur où les conteneurs peuvent redémarrer ou migrer :

Monter un stockage persistant

Le répertoire d’état de session doit être monté sur un stockage persistant :

# Azure Container Instance example
containers:
  - name: copilot-agent
    image: my-agent:latest
    volumeMounts:
      - name: session-storage
        mountPath: /home/app/.copilot/session-state

volumes:
  - name: session-storage
    azureFile:
      shareName: copilot-sessions
      storageAccountName: myaccount

La session survit aux redémarrages du conteneur !

Sessions infinies pour les workflows de longue durée

Pour les flux de travail qui peuvent dépasser les limites de contexte, activez des sessions infinies avec compactage automatique :

const session = await client.createSession({
  sessionId: "long-workflow-123",
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start compaction at 80% context
    bufferExhaustionThreshold: 0.95,      // Block at 95% if needed
  },
});

Limitations et considérations

Limitation	Description	Atténuation
Ré-authentification BYOK	Les clés API ne sont pas persistantes	Stockez les clés dans votre gestionnaire de secrets ; fournissez-les lors de la reprise
Stockage accessible en écriture
~/.copilot/session-state/ doit être accessible en écriture	Monter un volume persistant dans des conteneurs
Aucun verrouillage de session	L’accès simultané à la même session n’est pas défini	Implémenter le verrouillage ou la file d’attente au niveau de l’application
État de l’outil non persistant	L’état de l’outil en mémoire est perdu	Conception d'outils qui soient sans état ou conservent leur propre état

Gestion de l’accès simultané

Le Kit de développement logiciel (SDK) ne fournit pas de verrouillage de session intégré. Si plusieurs clients peuvent accéder à la même session :

// Option 1: Application-level locking with Redis
import Redis from "ioredis";

const redis = new Redis();

async function withSessionLock<T>(
  sessionId: string,
  fn: () => Promise<T>
): Promise<T> {
  const lockKey = `session-lock:${sessionId}`;
  const acquired = await redis.set(lockKey, "locked", "NX", "EX", 300);
  
  if (!acquired) {
    throw new Error("Session is in use by another client");
  }
  
  try {
    return await fn();
  } finally {
    await redis.del(lockKey);
  }
}

// Usage
await withSessionLock("user-123-task-456", async () => {
  const session = await client.resumeSession("user-123-task-456");
  await session.sendAndWait({ prompt: "Continue the task" });
});

Résumé

Fonctionnalité	Utilisation
Créer une session pouvant être reprise	Fournissez vos propres sessionId
Reprendre la session	client.resumeSession(sessionId)
BYOK RESUME	Re-fournir la provider configuration
Répertorier les sessions	client.listSessions(filter?)
Se déconnecter de la session active
session.disconnect()— libère des ressources en mémoire ; les données de session sur le disque sont conservées pour la reprise
Supprimer une session définitivement
client.deleteSession(sessionId): supprime définitivement toutes les données de session du disque ; ne peut pas être repris
Déploiement en conteneur	Monter ~/.copilot/session-state/ dans un stockage persistant

Étapes suivantes

• Points d'ancrage de session - Personnaliser le comportement de session avec des hooks
• Compatibilité du Kit de développement logiciel (SDK) et de l’interface - Comparaison des fonctionnalités sdk et CLI
• Guide de débogage - Résoudre les problèmes de session