Benutzerdefinierte Agents und Sub-Agent-Orchestrierung

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Benutzerdefinierte Agents sind einfache Agentdefinitionen, die Sie an eine Sitzung anfügen. Jeder Agent verfügt über eine eigene Systemaufforderung, Tooleinschränkungen und optionale MCP-Server. Wenn die Anforderung eines Benutzers mit dem Know-how eines Agents übereinstimmt, delegiert die Copilot SDK Laufzeit automatisch an diesen Agenten als Unter-Agenten, wobei sie ihn in einem isolierten Kontext ausführt, während Lebenszyklusereignisse an die übergeordnete Sitzung gestreamt werden. Eine visuelle Übersicht über den Delegierungsfluss finden Sie im github/copilot-sdk Repository.

Konzept	Beschreibung

          **Benutzerdefinierter Agent** | Eine benannte Agent-Konfiguration mit einer eigenen Eingabeaufforderung und einem eigenen Toolsatz |

| Unter-Agent | Ein benutzerdefinierter Agent, der von der Laufzeit aufgerufen wird, um einen Teil einer Aufgabe zu verarbeiten | | Schlussfolgerung | Die Fähigkeit der Laufzeit, einen Agent basierend auf der Absicht des Benutzers automatisch auszuwählen | | Übergeordnete Sitzung | Die Sitzung, die den Teilagent erzeugte, empfängt alle Lebenszyklus-Ereignisse |

Definieren von benutzerdefinierten Agents

Übergeben Sie customAgents beim Erstellen einer Sitzung. Jeder Agent benötigt mindestens ein name und prompt.

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

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    customAgents: [
        {
            name: "researcher",
            displayName: "Research Agent",
            description: "Explores codebases and answers questions using read-only tools",
            tools: ["grep", "glob", "view"],
            prompt: "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
        },
        {
            name: "editor",
            displayName: "Editor Agent",
            description: "Makes targeted code changes",
            tools: ["view", "edit", "bash"],
            prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
        },
    ],
    onPermissionRequest: async () => ({ kind: "approved" }),
});

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

Konfigurationsreferenz

Eigentum	Typ	Erforderlich	Beschreibung
name	string	✅	Eindeutiger Bezeichner für den Agent
displayName	string
Lesbarer Name, der in Ereignissen angezeigt wird
description	string
Was der Agent tut – hilft der Laufzeit, ihn auszuwählen.
tools

          `string[]` oder `null` |

| Namen von Tools, die der Agent verwenden kann. null oder weggelassen = alle Tools | | prompt | string | ✅ | Systemaufforderung für den Agent | | mcpServers | object | | MCP-Serverkonfigurationen, die für diesen Agent spezifisch sind | | infer | boolean | | Gibt an, ob die Laufzeit diesen Agent automatisch auswählen kann (Standard: true) |

Zusätzlich zur Konfiguration pro Agent können Sie für die agent festlegen****, dass sie vorwählt, welcher benutzerdefinierte Agent aktiv ist, wenn die Sitzung gestartet wird.

Sessionkonfigurationseigenschaft	Typ	Beschreibung
agent	string	Name des benutzerdefinierten Agents, der bei der Sitzungserstellung vorab ausgewählt werden soll. Muss mit einem name in customAgents übereinstimmen.

Auswählen eines Agents bei der Sitzungserstellung

Sie können agent in die Sitzungskonfiguration einfügen, um vorab auszuwählen, welcher benutzerdefinierte Agent aktiv sein soll, wenn die Sitzung beginnt. Der Wert muss mit dem name eines der in customAgents definierten Agenten übereinstimmen.

const session = await client.createSession({
    customAgents: [
        {
            name: "researcher",
            prompt: "You are a research assistant. Analyze code and answer questions.",
        },
        {
            name: "editor",
            prompt: "You are a code editor. Make minimal, surgical changes.",
        },
    ],
    agent: "researcher", // Pre-select the researcher agent
});

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

Funktionsweise der Sub-Agent-Delegierung

Wenn Sie eine Eingabeaufforderung an eine Sitzung mit benutzerdefinierten Agents senden, wertet die Laufzeit aus, ob sie an einen Unter-Agent delegiert werden soll:

1.        **Intent-Abgleich** – Während der Laufzeit wird die Aufforderung des Benutzers mit jedem `name` Agenten und `description` abgeglichen.
   

2.        **Agentauswahl** – Wenn eine Übereinstimmung gefunden wird und `infer` nicht `false`, wählt die Laufzeit den Agent aus.
   

3.        **Isolierte Ausführung** – Der Unter-Agent wird mit einer eigenen Eingabeaufforderung und einem eingeschränkten Toolsatz ausgeführt.
   

4.        **Ereignisstreaming** – Lebenszyklusereignisse (`subagent.started`, `subagent.completed`usw.) werden zurück zur übergeordneten Sitzung gestreamt
   

5.        **Ergebnisintegration** – Die Ausgabe des Unter-Agents wird in die Antwort des übergeordneten Agents integriert.
   

Steuern von Rückschlüssen

Standardmäßig sind alle benutzerdefinierten Agents für die automatische Auswahl (infer: true) verfügbar. Um zu verhindern, dass die Laufzeit automatisch einen Agenten auswählt – nützlich für Agenten, die nur über explizite Benutzeranforderungen aufgerufen werden sollen, legen Sie infer: false fest:

{
    name: "dangerous-cleanup",
    description: "Deletes unused files and dead code",
    tools: ["bash", "edit", "view"],
    prompt: "You clean up codebases by removing dead code and unused files.",
    infer: false, // Only invoked when user explicitly asks for this agent
}

Abhören von Sub-Agent-Ereignissen

Wenn ein Unter-Agent ausgeführt wird, löst die übergeordnete Sitzung Lebenszyklusereignisse aus. Abonnieren Sie diese Ereignisse, um UIs zu erstellen, die Agentaktivitäten visualisieren.

Ereignistypen

Ereignis	Wird ausgegeben, wenn	Daten
subagent.selected	Laufzeit wählt einen Agent für die Aufgabe aus.

          `agentName`, `agentDisplayName``tools` |

| subagent.started | Der Unter-Agent beginnt mit der Ausführung. | toolCallId agentName agentDisplayName agentDescription | | subagent.completed | Unteragent ist erfolgreich abgeschlossen. | toolCallId, agentName``agentDisplayName | | subagent.failed | Bei einem Unteragent tritt ein Fehler auf. | toolCallId agentName agentDisplayName error | | subagent.deselected | Die Laufzeitumgebung wechselt vom Subagenten ab. | — |

Abonnieren von Ereignissen

session.on((event) => {
    switch (event.type) {
        case "subagent.started":
            console.log(`▶ Sub-agent started: ${event.data.agentDisplayName}`);
            console.log(`  Description: ${event.data.agentDescription}`);
            console.log(`  Tool call ID: ${event.data.toolCallId}`);
            break;

        case "subagent.completed":
            console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`);
            break;

        case "subagent.failed":
            console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
            console.log(`  Error: ${event.data.error}`);
            break;

        case "subagent.selected":
            console.log(`🎯 Agent selected: ${event.data.agentDisplayName}`);
            console.log(`  Tools: ${event.data.tools?.join(", ") ?? "all"}`);
            break;

        case "subagent.deselected":
            console.log("↩ Agent deselected, returning to parent");
            break;
    }
});

const response = await session.sendAndWait({
    prompt: "Research how authentication works in this codebase",
});

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

Erstellen einer Agentstruktur-UI

Sub-Agent-Ereignisse umfassen toolCallId Felder, mit denen Sie den Ausführungsbaum rekonstruieren können. Hier ist ein Muster für die Nachverfolgung von Agentaktivitäten:

interface AgentNode {
    toolCallId: string;
    name: string;
    displayName: string;
    status: "running" | "completed" | "failed";
    error?: string;
    startedAt: Date;
    completedAt?: Date;
}

const agentTree = new Map<string, AgentNode>();

session.on((event) => {
    if (event.type === "subagent.started") {
        agentTree.set(event.data.toolCallId, {
            toolCallId: event.data.toolCallId,
            name: event.data.agentName,
            displayName: event.data.agentDisplayName,
            status: "running",
            startedAt: new Date(event.timestamp),
        });
    }

    if (event.type === "subagent.completed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "completed";
            node.completedAt = new Date(event.timestamp);
        }
    }

    if (event.type === "subagent.failed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "failed";
            node.error = event.data.error;
            node.completedAt = new Date(event.timestamp);
        }
    }

    // Render your UI with the updated tree
    renderAgentTree(agentTree);
});

Bereichsdefinitionstools pro Agent

Verwenden Sie die tools Eigenschaft, um einzuschränken, auf welche Tools ein Agent zugreifen kann. Dies ist wesentlich für die Sicherheit und dafür, dass Agenten fokussiert bleiben.

const session = await client.createSession({
    customAgents: [
        {
            name: "reader",
            description: "Read-only exploration of the codebase",
            tools: ["grep", "glob", "view"],  // No write access
            prompt: "You explore and analyze code. Never suggest modifications directly.",
        },
        {
            name: "writer",
            description: "Makes code changes",
            tools: ["view", "edit", "bash"],   // Write access
            prompt: "You make precise code changes as instructed.",
        },
        {
            name: "unrestricted",
            description: "Full access agent for complex tasks",
            tools: null,                        // All tools available
            prompt: "You handle complex multi-step tasks using any available tools.",
        },
    ],
});

Anfügen von MCP-Servern an Agenten

Jeder benutzerdefinierte Agent kann über eigene MCP-Server (Model Context Protocol) verfügen, sodass er Zugriff auf spezialisierte Datenquellen erhält:

const session = await client.createSession({
    customAgents: [
        {
            name: "db-analyst",
            description: "Analyzes database schemas and queries",
            prompt: "You are a database expert. Use the database MCP server to analyze schemas.",
            mcpServers: {
                "database": {
                    command: "npx",
                    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
                },
            },
        },
    ],
});

Muster und bewährte Methoden

Koppeln eines Forschers mit einem Editor

Ein gängiges Muster besteht darin, einen schreibgeschützten Recherche-Agent und einen schreibfähigen Editor-Agent zu definieren. Die Laufzeit delegiert Explorationsaufgaben an den Forscher und Änderungsaufgaben an den Editor.

customAgents: [
    {
        name: "researcher",
        description: "Analyzes code structure, finds patterns, and answers questions",
        tools: ["grep", "glob", "view"],
        prompt: "You are a code analyst. Thoroughly explore the codebase to answer questions.",
    },
    {
        name: "implementer",
        description: "Implements code changes based on analysis",
        tools: ["view", "edit", "bash"],
        prompt: "You make minimal, targeted code changes. Always verify changes compile.",
    },
]

Agentbeschreibungen spezifisch beibehalten

Die Laufzeit verwendet description, um die Absicht des Benutzers zu erkennen. Vage Beschreibungen führen zu einer schlechten Aufgabenzuweisung.

// ❌ Too vague — runtime can't distinguish from other agents
{ description: "Helps with code" }

// ✅ Specific — runtime knows when to delegate
{ description: "Analyzes Python test coverage and identifies untested code paths" }

Fehler geschickt bewältigen

Unter-Agents können fehlschlagen. Achten Sie immer auf subagent.failed Ereignisse, und behandeln Sie sie in Ihrer Anwendung:

session.on((event) => {
    if (event.type === "subagent.failed") {
        logger.error(`Agent ${event.data.agentName} failed: ${event.data.error}`);
        // Show error in UI, retry, or fall back to parent agent
    }
});