Implementación de agentes de IA mediante el SDK de Copilot de GitHub

  • 10 minutos

En esta unidad se describen los patrones de implementación principales para crear un agente de IA mediante el SDK de GitHub Copilot. Estos patrones se aplican a cualquier escenario de agente. Los ejemplos de código usan C# y .NET, que es la plataforma que se usa en el ejercicio del módulo.

Configuración del cliente del SDK de Copilot de GitHub

El primer paso consiste en crear una CopilotClient instancia que administre la conexión al servidor de la CLI de Copilot. Normalmente, registras el cliente como un servicio singleton en tu aplicación.

Instalación de paquetes necesarios

Agregue el SDK de Copilot de GitHub y el paquete de Microsoft.Extensions.AI (que se usa para las definiciones de herramientas) al proyecto:

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

Configurar el cliente

Cree un CopilotClient con CopilotClientOptions que controle el comportamiento de arranque y el registro:

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

La AutoStart opción indica al SDK que inicie automáticamente el proceso del servidor de la CLI de Copilot cuando se crea la primera sesión. La LogLevel opción controla el nivel de detalle de la salida de diagnóstico del SDK.

Después de crear el cliente, inícielo:

await client.StartAsync();

Este código establece la conexión con el servidor de la CLI y prepara el cliente para la creación de la sesión.

Definir herramientas de agente

Las herramientas proporcionan al agente la capacidad de interactuar con los servicios back-end de la aplicación. En el SDK de GitHub Copilot para .NET, se definen herramientas mediante AIFunctionFactory.Create del paquete Microsoft.Extensions.AI.

Creación de un servicio de herramientas

Un patrón común es crear una clase de servicio dedicada que contenga todos los métodos de herramienta a los que puede llamar el agente. Cada método representa una acción que el agente puede realizar:

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

Registro de herramientas con el SDK

Convierta los métodos de servicio en definiciones de herramientas que puede usar el SDK. Cada herramienta necesita un nombre, una descripción y una descripción de parámetros para que el modelo de IA comprenda cuándo y cómo usarlo:

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

Cada AIFunctionFactory.Create llamada toma tres argumentos:

  1. Función lambda que encapsula el método de servicio, con [Description] atributos en cada parámetro.
  2. Nombre de herramienta que usa el modelo de IA para hacer referencia a la herramienta.
  3. Descripción que ayuda al modelo a comprender cuándo llamar a la herramienta.

Los [Description] atributos de los parámetros son importantes: indican al modelo de inteligencia artificial lo que representa cada parámetro, lo que ayuda al modelo a proporcionar valores precisos al llamar a la herramienta.

Creación y configuración de una sesión

Las sesiones representan conversaciones individuales o contextos de tareas. Configure una sesión con el modelo, el mensaje del sistema, las herramientas y otras configuraciones.

Configuración de la sesión

Use SessionConfig para especificar cómo debe comportarse la sesión:

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

Opciones de configuración de claves:

  • Modelo: especifica el modelo de IA que se va a usar para esta sesión.
  • SystemMessage: define el rol y el comportamiento del agente. Mode determina si el mensaje reemplaza el mensaje del sistema predeterminado () o lo anexa (ReplaceAppend).
  • Herramientas: la lista de definiciones de herramientas que puede usar el agente.
  • InfiniteSessions: controla la compactación automática de contexto para conversaciones largas. Cuando se activa, puede ajustar los elementos BackgroundCompactionThreshold y BufferExhaustionThreshold para controlar cuándo se produce la compactación.

Creación de la sesión

Cree una sesión desde el cliente mediante la configuración:

var session = await client.CreateSessionAsync(config);

Control de respuestas con eventos

El SDK de Copilot de GitHub usa un modelo controlado por eventos para la comunicación. Después de enviar un mensaje, se suscribe a eventos para recibir respuestas y detectar cuándo se completa el procesamiento.

Suscribirse a eventos de sesión

Use el método session.On con coincidencia de patrones para controlar diferentes tipos de eventos.

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

Cada tipo de evento sirve para un propósito específico:

  • AssistantMessageEvent: contiene una parte del texto de respuesta del agente. Estos fragmentos de mensaje se acumulan para crear la respuesta completa.
  • SessionIdleEvent: indica que el agente finalizó el procesamiento, incluidas todas las llamadas a herramientas. Este evento indica que la respuesta está completa.
  • SessionErrorEvent: indica un error durante el procesamiento. La Data.Message propiedad contiene la descripción del error.

Enviar un mensaje y esperar la respuesta

Utilice SendAsync con un objeto MessageOptions para enviar el mensaje del usuario al agente:

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

El patrón TaskCompletionSource que se muestra aquí le permite conectar el modelo del SDK dirigido por eventos con código async/await. Cuando se activa SessionIdleEvent, completa la tarea con texto de respuesta acumulado.

Procedimientos recomendados de control de errores

El control de errores sólido es fundamental para los agentes de producción.

Errores del controlador de herramientas

Encapsule los controladores de herramientas en bloques try-catch para devolver mensajes de error significativos en lugar de lanzar excepciones. Cuando una herramienta devuelve un mensaje de error, el modelo de IA puede interpretarlo y proporcionar una respuesta útil al usuario:

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

Control de errores de nivel de sesión

Usa el SessionErrorEvent para detectar errores durante el procesamiento del agente. También puede configurar el OnErrorOccurred enlace de sesión, que devuelve un ErrorHandling valor para controlar cómo responde el agente a errores:

  • Reintentar: Intentar de nuevo la operación fallida.
  • Omitir: continúe el procesamiento sin el resultado con error.
  • Abortar: detener el procesamiento y mostrar el error.

Tiempos de expiración

Establezca siempre un tiempo de espera al esperar respuestas. En el ejemplo anterior se usa WaitAsync(TimeSpan.FromSeconds(30)) para evitar la espera indefinida si el agente encuentra un problema inesperado.

Diseño del símbolo del sistema

La solicitud del sistema es una de las decisiones de configuración más importantes. Define quién es el agente, qué puede hacer y cómo debe comportarse. Normalmente, un mensaje bien estructurado del sistema incluye:

  • Definición de roles: lo que representa el agente (por ejemplo, "Usted es un agente de soporte al cliente para ContosoShop").
  • Funcionalidades: qué herramientas están disponibles y qué hacen.
  • Guía de flujo de trabajo: cómo debe abordar el agente las tareas (por ejemplo, "Comprobar siempre los detalles del pedido antes de procesar una devolución").
  • Reglas y restricciones: límites que debe seguir el agente (por ejemplo, "Solo discutir temas relacionados con pedidos" o "Escalar solicitudes de reembolso más de $100").

Mantenga el mensaje del sistema centrado y específico. Las instrucciones vagas conducen a un comportamiento impredecible, mientras que las reglas excesivamente restrictivas pueden hacer que el agente no sea útil.

Transmitir respuestas con eventos delta

En aplicaciones interactivas como las interfaces de usuario de chat, puede transmitir la respuesta del agente token a token en lugar de esperar al mensaje completo. Use AssistantMessageDeltaEvent para capturar cada token parcial a medida que llegue:

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 propiedad contiene el fragmento de texto incremental. El streaming proporciona una experiencia más dinámica porque los usuarios ven la respuesta a medida que se forma, en lugar de esperar a que el modelo genere todo el mensaje.

Resumen

El SDK de Copilot de GitHub proporciona un marco eficaz para implementar agentes de inteligencia artificial que pueden razonar, usar herramientas y mantener el contexto. Mediante la definición de las funcionalidades del agente a través de herramientas, la configuración de sesiones con mensajes claros del sistema y el control de respuestas con eventos, puede crear agentes sofisticados que ofrecen valor empresarial real. El control de errores sólido y el diseño de mensajes atentos son fundamentales para garantizar que el agente funcione de forma confiable y eficaz en escenarios de producción. En la unidad siguiente, verá cómo aplicar estos patrones de implementación para crear un agente de soporte al cliente de ejemplo mediante el SDK de GitHub Copilot.