Schnellstart für Hooks

Hooks ermöglichen es Ihnen, das Verhalten von Copilot SDK-Sitzungen an entscheidenden Punkten im Lebenszyklus der Unterhaltung zu überwachen und anzupassen. Verwenden Sie Hooks für:

•         **Steuern der Toolausführung** – Genehmigen, Verweigern oder Ändern von Toolaufrufen
  

•         **Transformieren von Ergebnissen** – Ändern von Toolausgaben, bevor sie verarbeitet werden
  

•         **Kontext hinzufügen – Zusätzliche** Informationen beim Start der Sitzung einfügen
  

•         **Behandeln von Fehlern** – Implementieren der benutzerdefinierten Fehlerbehandlung
  

•         **Überwachen und Protokollieren** – Nachverfolgen aller Interaktionen zur Einhaltung von Vorschriften
  

Verfügbare Hooks

Hook	Auslöser	Anwendungsfall
onPreToolUse	Bevor ein Tool ausgeführt wird	Berechtigungssteuerung, Argumentvalidierung
onPostToolUse	Nach Ausführung eines Tools	Ergebnistransformation, Protokollierung
onUserPromptSubmitted	Wenn der Benutzer eine Nachricht sendet	Promptmodifikation, Filterung
onSessionStart	Sitzung beginnt	Kontext hinzufügen, Sitzung konfigurieren
onSessionEnd	Sitzung endet	Bereinigen, Analysen
onErrorOccurred	Fehler tritt auf	Benutzerdefinierte Fehlerbehandlung

Schnellstart

Im folgenden Beispiel wird veranschaulicht, wie Hooks beim Erstellen einer Sitzung in Node.js/TypeScript registriert werden.

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

const client = new CopilotClient();

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(`Tool called: ${input.toolName}`);
      // Allow all tools
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `Tool result: ${JSON.stringify(input.toolResult)}`
      );
      return null; // No modifications
    },
    onSessionStart: async (input) => {
      return {
        additionalContext:
          "User prefers concise answers.",
      };
    },
  },
});

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Hook-Aufrufkontext

Jeder Hook empfängt einen invocation Parameter mit Kontext zur aktuellen Sitzung.

Feld	Typ	Beschreibung
sessionId	Schnur	Die ID der aktuellen Sitzung

Auf diese Weise können Hooks den Zustand beibehalten oder sitzungsspezifische Logik ausführen.

Allgemeine Muster

Protokollierung aller Toolaufrufe

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] Tool: `
        + `${input.toolName}, `
        + `Args: ${JSON.stringify(input.toolArgs)}`
      );
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] `
        + `Result: ${JSON.stringify(input.toolResult)}`
      );
      return null;
    },
  },
});

Blockieren gefährlicher Werkzeuge

const BLOCKED_TOOLS = ["shell", "bash", "exec"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (BLOCKED_TOOLS.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason:
            "Shell access is not permitted",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Hinzufügen des Benutzerkontexts

const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const userPrefs = await loadUserPreferences();
      return {
        additionalContext:
          `User preferences: `
          + `${JSON.stringify(userPrefs)}`,
      };
    },
  },
});

Nächste Schritte

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/pre-tool-use)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/post-tool-use)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/user-prompt-submitted)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/session-lifecycle)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/error-handling)