Implémenter des agents IA à l’aide du Kit de développement logiciel (SDK) GitHub Copilot

10 minutes

Cette unité couvre les principaux modèles d’implémentation pour la création d’un agent IA à l’aide du Kit de développement logiciel (SDK) GitHub Copilot. Ces modèles s’appliquent à n’importe quel scénario d’agent. Les exemples de code utilisent C# et .NET, qui est la plateforme utilisée dans l’exercice du module.

Configurer le client du Kit de développement logiciel (SDK) Copilot GitHub

La première étape consiste à créer une CopilotClient instance qui gère la connexion au serveur CLI Copilot. En règle générale, vous inscrivez le client en tant que service singleton dans votre application.

Installer les packages requis

Ajoutez le Kit de développement logiciel (SDK) GitHub Copilot et le package Microsoft.Extensions.AI (utilisé pour les définitions d’outils) à votre projet :

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

Configurer le client

Créez un CopilotClient avec CopilotClientOptions qui contrôlent le comportement de démarrage et la journalisation :

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

L’option AutoStart indique au Kit de développement logiciel (SDK) de lancer automatiquement le processus du serveur Cli Copilot lors de la création de la première session. L’option LogLevel contrôle le niveau de verbosité de la sortie de diagnostic du SDK.

Après avoir créé le client, démarrez-le :

await client.StartAsync();

Ce code établit la connexion au serveur CLI et prépare le client pour la création de session.

Définir des outils d’agent

Les outils permettent à l’agent d’interagir avec les services principaux de votre application. Dans le kit SDK GitHub Copilot pour .NET, vous définissez des outils avec AIFunctionFactory.Create à partir du package Microsoft.Extensions.AI.

Créer un service d’outil

Un modèle courant consiste à créer une classe de service dédiée qui contient toutes les méthodes d’outil que votre agent peut appeler. Chaque méthode représente une action que l’agent peut effectuer :

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}.";
    }
}

Inscrire des outils auprès du Kit de développement logiciel (SDK)

Convertissez vos méthodes de service en définitions d’outils que le Kit de développement logiciel (SDK) peut utiliser. Chaque outil a besoin d’un nom, d’une description et d’une description des paramètres afin que le modèle IA comprenne quand et comment l’utiliser :

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

Chaque AIFunctionFactory.Create appel prend trois arguments :

Fonction lambda qui encapsule votre méthode de service, avec [Description] des attributs sur chaque paramètre.
Nom d’outil utilisé par le modèle IA pour référencer l’outil.
Description qui aide le modèle à comprendre quand appeler l’outil.

Les [Description] attributs sur les paramètres sont importants : ils indiquent au modèle IA ce que chaque paramètre représente, ce qui permet au modèle de fournir des valeurs précises lors de l’appel de l’outil.

Créer et configurer une session

Les sessions représentent des conversations individuelles ou des contextes de tâche. Vous configurez une session avec le modèle, l’invite système, les outils et d’autres paramètres.

Configurer la session

Permet SessionConfig de spécifier le comportement de la session :

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

Options de configuration clés :

Modèle : spécifie le modèle IA à utiliser pour cette session.
SystemMessage : définit le rôle et le comportement de l’agent. Détermine Mode si votre invite remplace le message système par défaut (Replace) ou l’ajoute (Append).
Outils : liste des définitions d’outils que l’agent peut utiliser.
InfiniteSessions : contrôle le compactage automatique du contexte pour les conversations longues. Lorsque cette option est activée, vous pouvez paramétrer BackgroundCompactionThresholdBufferExhaustionThreshold pour contrôler le moment où le compactage se produit.

Créer la session

Créez une session à partir du client à l’aide de votre configuration :

var session = await client.CreateSessionAsync(config);

Gérer les réponses avec des événements

Le Kit de développement logiciel (SDK) GitHub Copilot utilise un modèle piloté par les événements pour la communication. Après l’envoi d’un message, vous vous abonnez aux événements pour recevoir des réponses et détecter une fois le traitement terminé.

Utilisez la méthode session.On avec correspondance de motifs pour traiter différents types d’événements :

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

Chaque type d’événement a un but spécifique :

AssistantMessageEvent : contient une partie du texte de réponse de l’agent. Vous accumulez ces éléments de message pour générer la réponse complète.
SessionIdleEvent : signale que l’agent a terminé le traitement, y compris tous les appels d’outils. Cet événement indique que la réponse est terminée.
SessionErrorEvent : indique qu’une erreur s’est produite pendant le traitement. La Data.Message propriété contient la description de l’erreur.

Envoyer un message et attendre la réponse

Utilisez SendAsync avec un MessageOptions objet pour envoyer l’invite de l’utilisateur à l’agent :

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

Le modèle TaskCompletionSource présenté ici vous permet de faire le lien entre le modèle d'SDK événementiel et le code async/await. Lorsque le SessionIdleEvent se déclenche, il finalise la tâche avec le texte de réponse accumulé.

Bonnes pratiques de gestion des erreurs

La gestion robuste des erreurs est essentielle pour les agents de production.

Erreurs de gestionnaire d’outils

Incluez dans un wrapper vos gestionnaires d’outils dans des blocs try-catch et renvoyez des messages d’erreur significatifs plutôt que de lever des exceptions. Lorsqu’un outil retourne un message d’erreur, le modèle IA peut l’interpréter et fournir une réponse utile à l’utilisateur :

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

Gestion des erreurs au niveau de la session

Utilisez la SessionErrorEvent commande pour intercepter les erreurs pendant le traitement de l’agent. Vous pouvez également configurer le OnErrorOccurred hook de session, qui retourne une ErrorHandling valeur pour contrôler la façon dont l’agent répond aux erreurs :

Nouvelle tentative : réessayez l’opération ayant échoué.
Ignorer : continuer le traitement sans le résultat échoué.
Abandon : arrêtez le traitement et faites apparaître l’erreur.

Délais d’expiration

Définissez toujours un délai d’attente lors de l’attente de réponses. L’exemple précédent utilise WaitAsync(TimeSpan.FromSeconds(30)) pour empêcher l’attente indéfinie si l’agent rencontre un problème inattendu.

Conception de l’invite système

L’invite système est l’une des décisions de configuration les plus importantes. Il définit qui est l’agent, ce qu’il peut faire et comment il doit se comporter. Une invite de système bien structurée inclut généralement les éléments suivants :

Définition de rôle : ce que l’agent représente (par exemple, « Vous êtes un agent de support client pour ContosoShop »).
Fonctionnalités : quels outils sont disponibles et ce qu’ils font.
Conseils de flux de travail : Comment l’agent doit aborder les tâches (par exemple, « Toujours vérifier les détails de la commande avant de traiter un retour »).
Règles et contraintes : les limites que l’agent doit suivre (par exemple, « Discuter uniquement des rubriques liées aux commandes » ou « Escalader les demandes de remboursement au-dessus de 100 $ »).

Veillez à ce que l’invites système soit concise et précise. Des instructions vagues entraînent un comportement imprévisible, tandis que les règles trop restrictives peuvent rendre l’agent inutile.

Diffuser des réponses avec des événements delta

Pour les applications interactives telles que les interfaces de chat, vous pouvez diffuser en continu le jeton de réponse de l’agent jeton par jeton au lieu d’attendre le message complet. Permet AssistantMessageDeltaEvent de capturer chaque jeton partiel à mesure qu’il arrive :

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

La DeltaContent propriété contient le fragment de texte incrémentiel. La diffusion en continu offre une expérience plus réactive, car les utilisateurs voient la réponse sous forme de formulaire, plutôt que d’attendre que le modèle génère l’intégralité du message.

Résumé

Le Kit de développement logiciel (SDK) Copilot GitHub fournit une infrastructure puissante pour implémenter des agents IA qui peuvent raisonner, utiliser des outils et gérer le contexte. En définissant les fonctionnalités de votre agent via des outils, en configurant des sessions avec des invites système claires et en gérant les réponses avec des événements, vous pouvez créer des agents sophistiqués qui offrent une valeur métier réelle. Une gestion robuste des erreurs et une conception réfléchie des invites sont essentielles pour garantir que votre agent fonctionne de manière fiable et efficace dans les scénarios de production. Dans l’unité suivante, vous verrez comment appliquer ces modèles d’implémentation pour créer un exemple d’agent de support client à l’aide du Kit de développement logiciel (SDK) GitHub Copilot.

Commentaires

Cette page a-t-elle été utile ?