Implementieren von KI-Agents mit GitHub Copilot SDK

  • 10 Minuten

Diese Einheit befasst sich mit den kernen Implementierungsmustern für die Erstellung eines KI-Agents mithilfe des GitHub Copilot SDK. Diese Muster gelten für jedes Agentszenario. In den Codebeispielen wird C# und .NET verwendet. Dies ist die Plattform, die in der Modulübung verwendet wird.

Einrichten des GitHub Copilot SDK-Clients

Der erste Schritt besteht darin, eine CopilotClient Instanz zu erstellen, die die Verbindung mit dem Copilot CLI-Server verwaltet. In der Regel registrieren Sie den Client als Singletondienst in Ihrer Anwendung.

Installieren Sie die erforderlichen Pakete

Fügen Sie das GitHub Copilot SDK und das Microsoft.Extensions.AI-Paket (verwendet für Tooldefinitionen) zu Ihrem Projekt hinzu:

dotnet add package GitHub.Copilot.SDK
dotnet add package Microsoft.Extensions.AI

Konfigurieren des Clients

Erstellen Sie ein CopilotClient mit CopilotClientOptions, die das Startverhalten und die Protokollierung steuern.

var client = new CopilotClient(new CopilotClientOptions
{
    AutoStart = true,
    LogLevel = "info"
});

Die AutoStart Option weist das SDK an, den Copilot CLI-Serverprozess automatisch zu starten, wenn die erste Sitzung erstellt wird. Die LogLevel Option steuert die Ausführlichkeit der SDK-Diagnoseausgabe.

Starten Sie ihn nach dem Erstellen des Clients:

await client.StartAsync();

Dieser Code stellt die Verbindung mit dem CLI-Server her und bereitet den Client für die Sitzungserstellung vor.

Definition von Agenten-Tools

Tools bieten dem Agent die Möglichkeit, mit den Back-End-Diensten Ihrer Anwendung zu interagieren. Im GitHub Copilot SDK für .NET definieren Sie Tools mithilfe von AIFunctionFactory.Create aus dem Microsoft.Extensions.AI Paket.

Erstellen eines Tooldiensts

Ein gängiges Muster besteht darin, eine dedizierte Dienstklasse zu erstellen, die alle Toolmethoden enthält, die Ihr Agent aufrufen kann. Jede Methode stellt eine Aktion dar, die der Agent ausführen kann:

public class SupportAgentTools
{
    public async Task<string> GetOrderDetailsAsync(int orderId)
    {
        // Query the database for order information
        var order = await _dbContext.Orders.FindAsync(orderId);
        return order != null
            ? $"Order {orderId}: {order.ProductName}, Status: {order.Status}"
            : "Order not found.";
    }

    public async Task<string> ProcessReturnAsync(int orderId, string reason)
    {
        // Business logic to process the return
        var order = await _dbContext.Orders.FindAsync(orderId);
        order.Status = "Return Initiated";
        await _dbContext.SaveChangesAsync();
        return $"Return initiated for order {orderId}.";
    }
}

Registrieren von Tools mit dem SDK

Konvertieren Sie Ihre Dienstmethoden in Tooldefinitionen, die das SDK verwenden kann. Jedes Tool benötigt einen Namen, eine Beschreibung und Parameterbeschreibungen, damit das KI-Modell versteht, wann und wie es verwendet werden kann:

var toolService = new SupportAgentTools(dbContext);

var tools = new List<AIFunction>
{
    AIFunctionFactory.Create(
        async ([Description("The order ID number")] int orderId) =>
            await toolService.GetOrderDetailsAsync(orderId),
        "get_order_details",
        "Look up the status and details of a specific order."),

    AIFunctionFactory.Create(
        async ([Description("The order ID")] int orderId,
               [Description("The reason for the return")] string reason) =>
            await toolService.ProcessReturnAsync(orderId, reason),
        "process_return",
        "Process a return request for an order.")
};

Jeder AIFunctionFactory.Create Aufruf akzeptiert drei Argumente:

  1. Eine Lambda-Funktion , die Ihre Dienstmethode umschließt, mit [Description] Attributen für jeden Parameter.
  2. Ein Toolname , den das KI-Modell verwendet, um auf das Tool zu verweisen.
  3. Eine Beschreibung , die dem Modell hilft, zu verstehen, wann das Tool aufgerufen werden soll.

Die [Description] Attribute für Parameter sind wichtig – sie teilen dem KI-Modell mit, was jeder Parameter darstellt, wodurch das Modell beim Aufrufen des Tools genaue Werte bereitstellt.

Erstellen und Konfigurieren einer Sitzung

Sitzungen stellen einzelne Unterhaltungen oder Aufgabenkontexte dar. Sie konfigurieren eine Sitzung mit dem Modell, der Systemaufforderung, den Tools und anderen Einstellungen.

Sitzung konfigurieren

Verwenden Sie SessionConfig, um das Verhalten der Sitzung festzulegen:

var config = new SessionConfig
{
    Model = "gpt-4.1",
    SystemMessage = new SystemMessageConfig
    {
        Mode = SystemMessageMode.Replace,
        Content = @"You are a customer support agent for an e-commerce company.

CAPABILITIES:
- Look up order details
- Process returns

RULES:
- Only assist with order-related inquiries
- Always verify order details before taking action
- Be polite and professional"
    },
    Tools = tools,
    InfiniteSessions = new InfiniteSessionConfig
    {
        Enabled = false
    }
};

Wichtige Konfigurationsoptionen:

  • Modell: Gibt an, welches KI-Modell für diese Sitzung verwendet werden soll.
  • SystemMessage: Definiert die Rolle und das Verhalten des Agents. Dies Mode bestimmt, ob die Eingabeaufforderung die Standardsystemmeldung (Replace) ersetzt oder an sie angefügt wird (Append).
  • Tools: Die Liste der Tooldefinitionen, die der Agent verwenden kann.
  • InfiniteSessions: Steuert die automatische Kontextkomprimierung für lange Unterhaltungen. Wenn diese Option aktiviert ist, können Sie BackgroundCompactionThreshold und BufferExhaustionThreshold anpassen, um zu steuern, wann die Komprimierung erfolgt.

Sitzung erstellen

Erstellen Sie eine Sitzung vom Client mithilfe Ihrer Konfiguration:

var session = await client.CreateSessionAsync(config);

Antworten mit Ereignissen behandeln

Das GitHub Copilot SDK verwendet ein ereignisgesteuertes Modell für die Kommunikation. Nach dem Senden einer Nachricht abonnieren Sie Ereignisse, um Antworten zu empfangen und zu erkennen, wann die Verarbeitung abgeschlossen ist.

Abonnieren von Sitzungsereignissen

Verwenden Sie die session.On Methode mit Musterabgleich, um verschiedene Ereignistypen zu behandeln:

var responseBuilder = new StringBuilder();
var tcs = new TaskCompletionSource<string>();

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageEvent msg:
            responseBuilder.Append(msg.Data.Content);
            break;

        case SessionIdleEvent:
            tcs.SetResult(responseBuilder.ToString());
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

Jeder Ereignistyp dient einem bestimmten Zweck:

  • AssistantMessageEvent: Enthält einen Teil des Antworttexts des Agents. Sie sammeln diese Nachrichtenteile, um die vollständige Antwort zu erstellen.
  • SessionIdleEvent: Signalisiert, dass der Agent die Verarbeitung abgeschlossen hat, einschließlich aller Toolaufrufe. Dieses Ereignis gibt an, dass die Antwort abgeschlossen ist.
  • SessionErrorEvent: Gibt an, dass während der Verarbeitung ein Fehler aufgetreten ist. Die Data.Message Eigenschaft enthält die Fehlerbeschreibung.

Senden einer Nachricht und Warten der Antwort

Wird SendAsync mit einem MessageOptions Objekt verwendet, um die Eingabeaufforderung des Benutzers an den Agent zu senden:

await session.SendAsync(new MessageOptions
{
    Prompt = "What is the status of order 12345?"
});

// Wait for the response with a timeout
var response = await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30));

Das hier gezeigte TaskCompletionSource-Muster ermöglicht es Ihnen, das ereignisgesteuerte SDK-Modell mit async/await-Code zu verbinden. Wenn die SessionIdleEvent ausgelöst wird, wird die Aufgabe mit dem gesammelten Antworttext abgeschlossen.

Bewährte Methoden für die Fehlerbehandlung

Eine robuste Fehlerbehandlung ist für Produktionsmitarbeiter von entscheidender Bedeutung.

Toolhandlerfehler

Schließen Sie die Tool-Handler in Try-Catch-Blöcke ein und geben Sie aussagekräftige Fehlermeldungen zurück, anstatt Ausnahmen auszuwerfen. Wenn ein Tool eine Fehlermeldung zurückgibt, kann das KI-Modell sie interpretieren und eine hilfreiche Antwort auf den Benutzer bereitstellen:

AIFunctionFactory.Create(
    async ([Description("The order ID")] int orderId) =>
    {
        try
        {
            return await toolService.GetOrderDetailsAsync(orderId);
        }
        catch (Exception ex)
        {
            return $"Error retrieving order: {ex.Message}";
        }
    },
    "get_order_details",
    "Look up the status and details of a specific order.")

Fehlerbehandlung auf Sitzungsebene

Verwenden Sie SessionErrorEvent, um Fehler während der Agentenverarbeitung aufzufangen. Sie können auch den OnErrorOccurred Sitzungshaken konfigurieren, der einen ErrorHandling Wert zurückgibt, um zu steuern, wie der Agent auf Fehler reagiert:

  • Wiederholen: Wiederholen Sie den Vorgang erneut.
  • Überspringen: Fortsetzen der Verarbeitung ohne das fehlgeschlagene Ergebnis.
  • Abbrechen: Beenden Sie die Verarbeitung, und zeigen Sie den Fehler an.

Timeouts

Legen Sie beim Warten auf Antworten immer ein Timeout fest. Im vorherigen Beispiel wird WaitAsync(TimeSpan.FromSeconds(30)) verwendet, um unbestimmte Wartezeiten zu verhindern, falls ein unerwartetes Problem auftritt.

Systemaufforderungsentwurf

Die Systemaufforderung ist eine der wichtigsten Konfigurationsentscheidungen. Er definiert, wer der Agent ist, was er tun kann und wie er sich verhalten soll. Eine gut strukturierte Systemaufforderung umfasst in der Regel Folgendes:

  • Rollendefinition: Was der Agent darstellt (z. B. "Sie sind Ein Kundendienstmitarbeiter für ContosoShop").
  • Funktionen: Welche Tools verfügbar sind und was sie tun.
  • Workflowleitfaden: Wie der Agent Aufgaben angehen soll (z. B. "Bestelldetails vor der Verarbeitung einer Rückgabe immer überprüfen").
  • Regeln und Einschränkungen: Grenzen, denen der Agent folgen muss (z. B. "Nur bestellbezogene Themen besprechen" oder "Eskalieren von Rückerstattungsanforderungen über $100").

Halten Sie die Systemaufforderung fokussiert und spezifisch. Vage Anweisungen führen zu unvorhersehbarem Verhalten, während übermäßig restriktive Regeln den Agent nicht hilfreich machen können.

Streamen von Antworten mit Delta-Ereignissen

Bei interaktiven Anwendungen wie Chat-Benutzeroberflächen können Sie das Agentenantwort Token für Token streamen, anstatt auf die vollständige Nachricht zu warten. Verwenden Sie AssistantMessageDeltaEvent, um jedes Teiltoken beim Eintreffen zu erfassen.

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageDeltaEvent delta:
            // Render each token as it arrives
            Console.Write(delta.Data.DeltaContent);
            break;

        case SessionIdleEvent:
            Console.WriteLine();
            tcs.SetResult("Done");
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

Die DeltaContent Eigenschaft enthält das inkrementelle Textfragment. Streaming bietet eine reaktionsfähigere Erfahrung, da Benutzer die Antwort sehen, während sie sich bildet, anstatt darauf zu warten, dass das Modell die gesamte Nachricht generiert.

Zusammenfassung

Das GitHub Copilot SDK bietet ein leistungsfähiges Framework für die Implementierung von KI-Agenten, die schließen, Tools verwenden und Kontext verwalten können. Indem Sie die Funktionen Ihres Agents mithilfe von Tools definieren, Sitzungen mit klaren Systemaufforderungen konfigurieren und Antworten mit Ereignissen behandeln, können Sie anspruchsvolle Agents erstellen, die einen echten Geschäftswert bieten. Robuste Fehlerbehandlung und durchdachtes Eingabeaufforderungsdesign sind entscheidend, um sicherzustellen, dass Ihr Agent in Produktionsszenarien zuverlässig und effektiv funktioniert. In der nächsten Lektion erfahren Sie, wie Sie diese Implementierungsmuster anwenden, um einen Beispiel-Kundendienstmitarbeiter mit dem GitHub Copilot SDK zu erstellen.