Angepasste Agents und Orchestrierung von Unteragenten

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

Angepasste Agents sind schlanke Agent-Definitionen, die Sie einer Sitzung zuordnen. Jeder Agent verfügt über eine eigene Systemaufforderung, Tooleinschränkungen und optionale MCP-Server. Wenn die Anfrage eines Benutzers mit dem Fachwissen eines Agenten übereinstimmt, delegiert die Copilot SDK-Laufzeit automatisch an diesen Agenten als Unter-Agenten und führt ihn in einem isolierten Kontext aus, während Lebenszyklusereignisse an die übergeordnete Sitzung zurückgesendet 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 Runtime zur automatischen Auswahl eines Agents auf der Grundlage des Intents des Benutzers | | Ü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 Runtime bei der Auswahl des Agenten
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**-Die Runtime analysiert den Prompt des Benutzers mit den `name` und `description`Agenten
   

2.           **-Agentenauswahl**-Wenn eine Übereinstimmung gefunden wird und `infer` nicht `false` ist, wählt die Runtime den Agenten 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 Sub-Agent ausgeführt wird, sendet 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	Runtime wählt einen Agenten für die Aufgabe aus

          `agentName`, `agentDisplayName``tools` |

| subagent.started | Der Unter-Agent beginnt mit der Ausführung. | toolCallId agentName agentDisplayName agentDescription | | subagent.completed | Sub-Agent schließt erfolgreich ab | toolCallId, agentName``agentDisplayName | | subagent.failed | Bei einem Unteragent tritt ein Fehler auf. | toolCallId agentName agentDisplayName error | | subagent.deselected | Runtime schaltet weg vom Sub-Agenten | — |

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

Scoping Tools 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 ist die Definition eines schreibgeschützten Recherche-Agenten und eines schreibfähigen Editor-Agenten. 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. Hören Sie immer auf subagent.failed-Ereignisse und behandeln Sie diese 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
    }
});