Che cos'è GitHub Copilot SDK?

Completato

GitHub Copilot SDK è un toolkit multipiattaforma (attualmente in Technical Preview) che consente di incorporare un runtime dell'agente di intelligenza artificiale nelle proprie applicazioni. L'SDK espone lo stesso motore dietro l'interfaccia della riga di comando di GitHub Copilot come interfaccia programmabile, offrendo all'app la possibilità di comprendere le istruzioni in linguaggio naturale, pianificare le azioni e richiamare gli strumenti per soddisfare tali istruzioni. Non è necessario creare tutta l'infrastruttura da zero.

Perché usare un SDK per gli agenti di intelligenza artificiale?

La creazione di un agente di intelligenza artificiale completo da zero è complessa. È necessario gestire la gestione dello stato della conversazione a turno, decidere quando chiamare l'API esterna, assicurarsi che le risposte dell'intelligenza artificiale rimangano entro i limiti, gestire più modelli di intelligenza artificiale per attività diverse e implementare misure di sicurezza. La creazione di flussi di lavoro agenti da zero significa essenzialmente aver creato una mini piattaforma prima di passare anche alla logica di business.

GitHub Copilot SDK rimuove tale complessità fornendo un motore agente predefinito testato dall'ambiente di produzione. L'SDK gestisce l'autenticazione, la gestione dei modelli, le sessioni di chat e lo streaming. Ti concentri su ciò che viene costruito sopra questi blocchi fondamentali, cioè gli strumenti specifici del dominio e la logica aziendale.

Panoramica dell'architettura

GitHub Copilot SDK comunica con l'interfaccia della riga di comando di GitHub Copilot, che viene eseguita in modalità server come processo locale. Il SDK gestisce automaticamente il ciclo di vita del processo a riga di comando. Tutti i linguaggi SDK condividono questa stessa architettura.

L'architettura segue questo flusso:

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

È possibile interagire con l'SDK tramite una libreria client nel linguaggio di programmazione preferito. L'SDK gestisce il protocollo di comunicazione, quindi è possibile usare chiamate di metodo semplici anziché messaggi non elaborati.

Supporto linguistico

L'SDK offre librerie idiomatiche per quattro linguaggi di programmazione:

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

Sia che si stia creando un'applicazione Web in TypeScript o in un servizio back-end in C#, è possibile incorporare le stesse funzionalità dell'agente di intelligenza artificiale.

Funzionalità principali

L'SDK offre diverse funzionalità predefinite che semplificano la creazione di agenti di intelligenza artificiale.

Ciclo degli agenti per la produzione

L'SDK offre lo stesso ciclo di esecuzione collaudato che supporta l'interfaccia della riga di comando di GitHub Copilot. Questo ciclo di esecuzione gestisce le conversazioni a più turni, chiama gli strumenti ed esegue l'iterazione fino al completamento dell'attività. Non è necessario codificare la logica di pianificazione e orchestrazione.

Orchestrazione degli strumenti

È possibile definire strumenti personalizzati richiamati dall'agente di intelligenza artificiale in base alle esigenze durante il processo di ragionamento. Quando si registra uno strumento (ad esempio lookupCustomer(id)), il modello di intelligenza artificiale dell'agente può determinare quando chiamarlo. L'SDK gestisce il cablaggio in modo che l'intelligenza artificiale possa chiamare lo strumento in modo strutturato tramite una chiamata di funzione effettiva nel runtime, invece di indovinare il codice.

In .NET, gli strumenti vengono definiti usando AIFunctionFactory dal pacchetto Microsoft.Extensions.AI. Ogni strumento include un nome, una descrizione, uno schema di parametri e una funzione del gestore.

Flessibilità multimodello

L'SDK non è associato a un modello di intelligenza artificiale. Supporta più modelli di intelligenza artificiale e consente il routing di modelli dinamici. Ad esempio, è possibile usare un modello più veloce per attività semplici e un modello più idoneo per un ragionamento complesso, all'interno della stessa applicazione.

Streaming in tempo reale

L'SDK supporta le risposte in streaming, vale a dire che l'intelligenza artificiale genera l'output, è possibile trasmetterlo all'app. Ad esempio, è possibile trasmettere i token per visualizzare un indicatore di digitazione o una risposta parziale in un'interfaccia utente di chat. Questo comportamento rende l'esperienza più interattiva e reattiva.

Autenticazione e sicurezza

L'SDK supporta più metodi di autenticazione:

• Utente connesso a GitHub: Riutilizza le credenziali OAuth archiviate dall'accesso alla CLI di Copilot.
• OAuth App GitHub: trasferisce i token utente dalla tua app OAuth GitHub.
• Variabili di ambiente: usa COPILOT_GITHUB_TOKEN, GH_TOKENo GITHUB_TOKEN.
• Bring Your Own Key (BYOK): usa chiavi API personalizzate per provider come OpenAI, Azure AI Foundry o Anthropic senza richiedere l'autenticazione di GitHub.

È necessaria una sottoscrizione di GitHub Copilot a meno che non si usi l'opzione BYOK.

Gestione del contesto

L'SDK gestisce automaticamente la cronologia delle conversazioni all'interno di una sessione. Tiene traccia dei messaggi precedenti e degli output degli strumenti in modo che il modello di intelligenza artificiale abbia il contesto necessario per interazioni coerenti a più turni. Per sessioni lunghe, l'SDK offre una funzionalità di sessioni infinite che compatta automaticamente il contesto quando la finestra di contesto si avvicina al limite, impedendo gli errori di overflow del token.

Concetti principali

La comprensione dei concetti di base dell'SDK consente di usarli in modo efficace.

Cliente

La CopilotClient classe gestisce la connessione al server dell'interfaccia della riga di comando di Copilot. Creare un'istanza client per l'applicazione e usarla per creare sessioni. Il client gestisce l'avvio e l'arresto del processo dell'interfaccia della riga di comando, la definizione del canale di comunicazione e la gestione dei cicli di vita delle sessioni.

Le opzioni di configurazione includono AutoStart (avvia automaticamente il server dell'interfaccia della riga di comando quando viene creata la prima sessione), LogLevel (controlla la registrazione dettagliata), CliPath (specifica un percorso personalizzato per l'eseguibile dell'interfaccia della riga di comando) e GithubToken (fornisce direttamente un token GitHub anziché basarsi su variabili di ambiente o account di accesso dell'interfaccia della riga di comando).

Session

Un oggetto CopilotSession rappresenta una singola conversazione o contesto di attività. Ogni sessione ha una propria cronologia delle conversazioni, la configurazione del modello, le definizioni degli strumenti e la richiesta di sistema. È possibile creare sessioni dal client usando CreateSessionAsync, inviare messaggi e ricevere risposte tramite un modello basato su eventi.

Le opzioni di configurazione della sessione chiave includono:

• Modello: modello di intelligenza artificiale da usare (ad esempio, gpt-4.1).
• SystemMessage: definisce il ruolo e il comportamento dell'agente tramite un oggetto SystemMessageConfig con una Mode (Append o Replace) e una stringa Content.
• Strumenti: definizioni personalizzate degli strumenti che l'agente può richiamare.
• InfiniteSessions: controlla la compattazione automatica del contesto tramite un InfiniteSessionConfig oggetto . Se abilitata, è possibile configurare BackgroundCompactionThreshold (la percentuale di utilizzo della finestra di contesto che attiva la compattazione in background) e BufferExhaustionThreshold (la percentuale in corrispondenza della quale l'SDK forza la compattazione per impedire l'overflow del token).

Tools

Gli strumenti sono funzioni registrate con una sessione in modo che l'agente di intelligenza artificiale possa chiamarli durante il ragionamento. Ogni strumento ha un nome, una descrizione, parametri e una funzione del gestore. Quando il modello di intelligenza artificiale decide di usare uno strumento, l'SDK intercetta la richiesta, chiama il gestore e invia il risultato al modello per un ulteriore ragionamento.

In .NET si definiscono gli strumenti usando AIFunctionFactory.Create :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.")

Events

L'SDK usa un modello di comunicazione basato su eventi. Quando si invia un messaggio a una sessione, l'SDK genera eventi durante l'elaborazione:

• AssistantMessageEvent: il modello di intelligenza artificiale ha prodotto una risposta completa.
• AssistantMessageDeltaEvent: il modello di intelligenza artificiale ha prodotto un token di risposta parziale durante lo streaming. La Data.DeltaContent proprietà contiene il testo incrementale, che è possibile visualizzare in tempo reale.
• SessionIdleEvent: la sessione ha terminato l'elaborazione (incluse le chiamate agli strumenti).
• SessionErrorEvent: si è verificato un errore durante l'elaborazione.
• ToolExecutionStartEvent e ToolExecutionCompleteEvent: è stato richiamato uno strumento.

Ci si iscrive a questi eventi per acquisire le risposte dell'agente e gestire eventuali errori. Per gli scenari non streaming, usare AssistantMessageEvent per raccogliere la risposta completa. Per gli scenari di streaming ,ad esempio la visualizzazione di un indicatore di digitazione in un'interfaccia utente di chat, usare AssistantMessageDeltaEvent per eseguire il rendering dei token man mano che arrivano.

Hook di sessione

L'SDK fornisce hook che consentono di intercettare e modificare il comportamento dell'agente nei punti chiave:

• OnPreToolUse: intercettare le chiamate degli strumenti prima dell'esecuzione. Il gestore restituisce un PermissionDecision valore:Allow per continuare, Deny bloccare la chiamata o Ask richiedere conferma all'utente.
• OnPostToolUse: elaborare i risultati dello strumento dopo l'esecuzione, utile per registrare o modificare i risultati prima di raggiungere il modello.
• OnUserPromptSubmitted: intercettare e modificare le richieste dell'utente prima dell'elaborazione.
• OnErrorOccurred: gestire gli errori restituendo un ErrorHandling valore,Retry per tentare di nuovo l'operazione, Skip continuare senza il risultato o Abort interrompere l'elaborazione.
• OnSessionStart: viene eseguito all'avvio di una sessione, utile per le attività di inizializzazione.
• OnSessionEnd: viene eseguito al termine di una sessione, utile per la pulizia o la registrazione.

Questi hook consentono di implementare controlli delle autorizzazioni, registrazione e protezioni di sicurezza.

Prerequisiti per lo sviluppo di .NET

Per usare GitHub Copilot SDK in un'applicazione .NET, l'ambiente deve:

• .NET 8.0 o versione successiva.
• La CLI di GitHub Copilot, installata e disponibile nel PATH di sistema.
• Un account GitHub con una sottoscrizione copilot attiva (o le proprie chiavi API per BYOK).
• Pacchetto NuGet GitHub.Copilot.SDK.
• Pacchetto Microsoft.Extensions.AI NuGet (per la definizione degli strumenti tramite AIFunctionFactory).

Riassunto

GitHub Copilot SDK offre una potente piattaforma pronta per la produzione per la creazione di agenti di intelligenza artificiale nelle applicazioni. Astraendo le complessità dell'orchestrazione dell'agente, dell'integrazione degli strumenti e della gestione del contesto, l'SDK consente di concentrarsi sulla definizione delle funzionalità dell'agente e della logica di business. Con il supporto per più linguaggi, streaming in tempo reale e opzioni di autenticazione flessibili, GitHub Copilot SDK è una scelta versatile per l'aggiunta di funzionalità dell'agente di intelligenza artificiale a un'ampia gamma di applicazioni.