Persistance de session dans le Kit de développement logiciel (SDK) Copilot

Remarque

          Kit de développement logiciel (SDK) Copilot est actuellement en préversion technique. Les fonctionnalités et la disponibilité sont susceptibles de changer.

Lorsque vous créez une session, Kit de développement logiciel (SDK) Copilot conservez 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. Pour obtenir une vue d’ensemble visuelle du cycle de vie de l’état de session, consultez le github/copilot-sdk référentiel.

State	Que se passe-t-il ?

          **Créer** | 
          `sessionId` Attribué |

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

La clé pour les sessions pouvant être reprises est de fournir vos propres sessionId SDK (d'autres kits SDK peuvent utiliser session_id). Sans un, le SDK génère un ID aléatoire et la session ne peut pas être reprise ultérieurement.

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

Pour obtenir des exemples dans Python, Go et C#, consultez le github/copilot-sdkréférentiel.

Reprise d’une session

Vous pouvez reprendre une session à partir de laquelle elle s’est terminée (minutes, heures ou même jours plus tard). Pour obtenir une vue d’ensemble visuelle de la reprise de session inter-clients, consultez le github/copilot-sdk référentiel.

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

Pour obtenir des exemples dans Python, Go et C#, consultez le github/copilot-sdk référentiel.

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.

Choix	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 : Modification du modèle sur le CV

// 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 avec des sessions reprises

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

Quels éléments sont persistés

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 |

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.

Modèle	Exemple	Cas d’utilisation

          ❌
          `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"

Pour obtenir un exemple dans Python, consultez le github/copilot-sdk référentiel.

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

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 des modèles de nettoyage automatique idiomatiques :

Language	Modèle	Exemple

          **TypeScript** | `Symbol.asyncDispose` | `await using session = await client.createSession(config);` |

Remarque

          `destroy()` a été remplacé par `disconnect()` et sera supprimé dans une prochaine version. Le code existant utilise `destroy()` continuera de fonctionner, mais doit être migré.

Suppression définitive d’une session

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

Conseil

          `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é

Le SDK a un délai d’inactivité intégré de 30 minutes. Les sessions sans activité sont automatiquement nettoyées. Pour obtenir une vue d’ensemble visuelle du flux de délai d’inactivité, consultez le github/copilot-sdk référentiel.

Écoutez les événements d'inactivité pour savoir quand le travail est terminé :

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, sessions dynamiques Azure. Pour obtenir un diagramme visuel, consultez le github/copilot-sdk référentiel.

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. Pour obtenir un diagramme visuel, consultez le github/copilot-sdk référentiel.

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, le répertoire d’état de session doit être monté dans le 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

Pour obtenir un diagramme visuel de persistance du redémarrage du conteneur, consultez le github/copilot-sdk référentiel.

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

Remarque

Les seuils sont des ratios d’utilisation du contexte (0,0 à 1,0), et non des nombres de jetons absolus.

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, vous devez vous assurer que chaque session est verrouillée pour empêcher le détournement :

// 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é	Guide pratique pour utiliser

          **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 |

Persistance de session dans le Kit de développement logiciel (SDK) Copilot

Qui peut utiliser cette fonctionnalité ?

Dans cet article

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

Reprise d’une session

Options de reprise

Exemple : Modification du modèle sur le CV

Utilisation de BYOK avec des sessions reprises

Quels éléments sont persistés

Bonnes pratiques relatives à l’ID de session

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

Gestion du cycle de vie des sessions

Liste des sessions actives

Nettoyage des anciennes sessions

Déconnexion d’une session

Suppression définitive d’une session

Nettoyage automatique : temporisation d'inactivité

Modèles de déploiement

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

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

Sessions dynamiques Azure

Sessions infinies pour les workflows de longue durée

Limitations et considérations

Gestion de l’accès simultané

Résumé