¿Qué es el SDK de Copilot de GitHub?

Completado

El SDK de Copilot de GitHub es un kit de herramientas multiplataforma (actualmente en Technical Preview) que permite insertar un entorno de ejecución de agente de IA en sus propias aplicaciones. El SDK expone el mismo motor detrás de la CLI de GitHub Copilot como una interfaz programable, lo que proporciona a la aplicación la capacidad de comprender las instrucciones de lenguaje natural, las acciones del plan y las herramientas de invocación para cumplir esas instrucciones. No es necesario construir toda esa infraestructura desde cero.

¿Por qué usar un SDK para agentes de IA?

La creación de un agente de IA completo desde cero es complejo. Debe controlar la administración del estado de conversación entre turnos, decidir cuándo llamar a qué API externa, asegurarse de que las respuestas de la inteligencia artificial permanecen dentro de los límites, administrar varios modelos de IA para diferentes tareas e implementar medidas de seguridad. La creación de flujos de trabajo agenciales desde cero significa que, esencialmente, ha construido una mini plataforma antes de llegar a la lógica empresarial.

El SDK de Copilot de GitHub quita esa complejidad proporcionando un motor de agente precompilado y probado por producción. El SDK controla la autenticación, la administración de modelos, las sesiones de chat y el streaming. Te centras en lo que se construye sobre esos bloques de construcción: tus herramientas específicas del dominio y la lógica empresarial.

Información general sobre la arquitectura

El SDK de Copilot de GitHub se comunica con la CLI de GitHub Copilot, que se ejecuta en modo de servidor como un proceso local. El SDK administra automáticamente el ciclo de vida del proceso de la CLI. Todos los lenguajes del SDK comparten esta misma arquitectura.

La arquitectura sigue este flujo:

Your Application → SDK Client → (JSON-RPC) → Copilot CLI (server mode)

Puede interactuar con el SDK a través de una biblioteca cliente en el lenguaje de programación que prefiera. El SDK controla el protocolo de comunicación, por lo que se trabaja con llamadas de método simples en lugar de mensajes sin procesar.

Compatibilidad con idiomas

El SDK proporciona bibliotecas idiomáticas para cuatro lenguajes de programación:

Language	Package
Node.js (TypeScript)	npm install @github/copilot-sdk
Pitón	pip install github-copilot-sdk
Go	go get github.com/github/copilot-sdk/go
.NET (C#)	dotnet add package GitHub.Copilot.SDK

Tanto si va a compilar una aplicación web en TypeScript como en un servicio back-end en C#, puede incorporar las mismas funcionalidades del agente de IA.

Características clave

El SDK proporciona varias funcionalidades integradas que simplifican la creación de agentes de inteligencia artificial.

Bucle de agente en nivel de producción

El SDK proporciona el mismo bucle de ejecución probado que impulsa la CLI de GitHub Copilot. Este bucle de ejecución administra conversaciones de múltiples turnos, llama a herramientas, e itera hasta que se complete la tarea. No es necesario codificar la lógica de planeación y orquestación.

Orquestación de herramientas

Puede definir herramientas personalizadas que el agente de IA invoca según sea necesario durante su proceso de razonamiento. Al registrar una herramienta (como lookupCustomer(id)), el modelo de IA del agente puede determinar cuándo llamarlo. El SDK se encarga de la conexión para que la IA pueda llamar a tu herramienta de manera estructurada a través de una llamada de función real durante la ejecución, en lugar de adivinar el código.

En .NET, las herramientas se definen mediante AIFunctionFactory desde el Microsoft.Extensions.AI paquete. Cada herramienta incluye un nombre, una descripción, un esquema de parámetros y una función de controlador.

Flexibilidad multimodelo

El SDK no está vinculado a un modelo de IA. Admite varios modelos de IA y permite el enrutamiento dinámico de modelos. Por ejemplo, puede usar un modelo más rápido para tareas sencillas y un modelo más capaz para un razonamiento complejo, dentro de la misma aplicación.

Streaming en directo

El SDK admite respuestas de streaming, lo que significa que, a medida que la inteligencia artificial genera la salida, puede transmitirla a la aplicación. Por ejemplo, puede transmitir tokens para mostrar un indicador de escritura o una respuesta parcial en una interfaz de usuario de chat. Este comportamiento hace que la experiencia sea más interactiva y con capacidad de respuesta.

Autenticación y seguridad

El SDK admite varios métodos de autenticación:

• Usuario que ha iniciado sesión en GitHub: reutiliza las credenciales de OAuth almacenadas desde el inicio de sesión de la CLI de Copilot.
• Aplicación OAuth de GitHub: pasa tokens de usuario desde la aplicación OAuth de GitHub.
• Variables de entorno: usa COPILOT_GITHUB_TOKEN, GH_TOKENo GITHUB_TOKEN.
• Traiga su propia clave (BYOK): usa sus propias claves de API para proveedores como OpenAI, Azure AI Foundry o Antropic sin necesidad de autenticación de GitHub.

Se requiere una suscripción a GitHub Copilot a menos que use la opción BYOK.

Administración de contexto

El SDK administra automáticamente el historial de conversaciones dentro de una sesión. Realiza un seguimiento de los mensajes anteriores y las salidas de herramientas para que el modelo de IA tenga el contexto que necesita para interacciones coherentes de varios turnos. Para sesiones largas, el SDK proporciona una característica de sesiones infinitas que compacta automáticamente el contexto cuando la ventana de contexto se aproxima a su límite, lo que impide errores de desbordamiento de tokens.

Conceptos principales

Comprender los conceptos básicos del SDK le ayuda a trabajar con él de forma eficaz.

Client

La CopilotClient clase administra la conexión al servidor de la CLI de Copilot. Cree una instancia de cliente para la aplicación y úsela para crear sesiones. El cliente controla el inicio y detención del proceso de la CLI, el establecimiento del canal de comunicación y la administración de los ciclos de vida de la sesión.

Las opciones de configuración incluyen AutoStart (inicia automáticamente el servidor de la CLI cuando se crea la primera sesión), LogLevel (controla el nivel de detalle del registro), CliPath (especifica una ruta de acceso personalizada al ejecutable de la CLI) y GithubToken (proporciona un token de GitHub directamente en lugar de confiar en variables de entorno o inicio de sesión de la CLI).

Session

Un CopilotSession representa un único contexto de conversación o tarea. Cada sesión tiene su propio historial de conversaciones, configuración del modelo, definiciones de herramientas y aviso del sistema. Las sesiones se crean desde el cliente mediante CreateSessionAsync, se envían mensajes a ellos y se reciben respuestas a través de un modelo controlado por eventos.

Entre las opciones de configuración de sesión clave se incluyen:

• Modelo: modelo de IA que se va a usar (por ejemplo, gpt-4.1).
• SystemMessage: Define el rol y el comportamiento del agente a través de un SystemMessageConfig objeto con un Mode (Append o Replace) y una cadena Content.
• Herramientas: definiciones de herramientas personalizadas que el agente puede invocar.
• InfiniteSessions: controla la compactación automática del contexto a través de un InfiniteSessionConfig objeto . Cuando se habilita, puede configurar BackgroundCompactionThreshold (el porcentaje de uso de la ventana de contexto que desencadena la compactación en segundo plano) y BufferExhaustionThreshold (el porcentaje en el que el SDK fuerza la compactación para evitar el desbordamiento del token).

Tools

Las herramientas son funciones que se registran con una sesión para que el agente de IA pueda llamarlas durante el razonamiento. Cada herramienta tiene un nombre, una descripción, parámetros y una función de controlador. Cuando el modelo de IA decide usar una herramienta, el SDK intercepta la solicitud, llama al controlador y devuelve el resultado al modelo para un razonamiento adicional.

En .NET, se definen herramientas mediante AIFunctionFactory.Create desde Microsoft.Extensions.AI:

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

Eventos

El SDK usa un modelo de comunicación controlado por eventos. Al enviar un mensaje a una sesión, el SDK desencadena eventos a medida que se produce el procesamiento:

• AssistantMessageEvent: el modelo de IA generó una respuesta completa.
• AssistantMessageDeltaEvent: el modelo de IA generó un token de respuesta parcial durante el streaming. La Data.DeltaContent propiedad contiene el texto incremental, que se puede mostrar en tiempo real.
• SessionIdleEvent: la sesión finalizó el procesamiento (incluidas las llamadas a herramientas).
• SessionErrorEvent: error durante el procesamiento.
• ToolExecutionStartEvent y ToolExecutionCompleteEvent: se invocó una herramienta.

Suscríbase a estos eventos para capturar las respuestas del agente y controlar los errores. Para escenarios que no son de streaming, use AssistantMessageEvent para recopilar la respuesta completa. En escenarios de streaming (como mostrar un indicador de escritura en una interfaz de usuario de chat), use AssistantMessageDeltaEvent para representar tokens a medida que llegan.

Enlaces de sesión

El SDK proporciona enlaces que permiten interceptar y modificar el comportamiento del agente en puntos clave:

• OnPreToolUse: intercepte las llamadas a herramientas antes de la ejecución. El controlador devuelve un PermissionDecision valor,Allow para continuar, Deny bloquear la llamada o Ask pedir al usuario que confirme.
• OnPostToolUse: procesar los resultados de la herramienta después de la ejecución, útil para registrar o modificar los resultados antes de que lleguen al modelo.
• OnUserPromptSubmitted: intercepte y modifique las solicitudes del usuario antes del procesamiento.
• OnErrorOccurred: controle los errores devolviendo un ErrorHandling valor paraRetry intentar la operación de nuevo, Skip continuar sin el resultado o Abort detener el procesamiento.
• OnSessionStart: se ejecuta cuando comienza una sesión, útil para las tareas de inicialización.
• OnSessionEnd: se ejecuta cuando finaliza una sesión, útil para la limpieza o el registro.

Estos ganchos permiten implementar controles de permisos, registro de eventos y barreras de seguridad.

Requisitos previos para el desarrollo de .NET

Para usar el SDK de Copilot de GitHub en una aplicación .NET, el entorno necesita:

• .NET 8.0 o posterior.
• La CLI de GitHub Copilot, instalada y disponible en el PATH del sistema.
• Una cuenta de GitHub con una suscripción activa de Copilot (o sus propias claves de API para BYOK).
• Paquete GitHub.Copilot.SDK NuGet.
• Paquete Microsoft.Extensions.AI NuGet (para definir herramientas mediante AIFunctionFactory).

Resumen

El SDK de GitHub Copilot proporciona una plataforma potente y lista para producción para desarrollar agentes de inteligencia artificial en sus aplicaciones. Al abstraer las complejidades de la orquestación del agente, la integración de herramientas y la administración de contextos, el SDK le permite centrarse en definir las funcionalidades y la lógica de negocios del agente. Con compatibilidad con varios lenguajes, streaming en tiempo real y opciones de autenticación flexibles, el SDK de Copilot de GitHub es una opción versátil para agregar la funcionalidad del agente de IA a una amplia gama de aplicaciones.