O que é o SDK do GitHub Copilot?

Concluído

O SDK do GitHub Copilot é um kit de ferramentas de várias plataformas (atualmente no Technical Preview) que permite inserir um runtime do agente de IA em seus próprios aplicativos. O SDK expõe o mesmo mecanismo por trás da CLI do GitHub Copilot como uma interface programável, dando ao seu aplicativo a capacidade de entender instruções de linguagem natural, planejar ações e invocar ferramentas para atender a essas instruções. Você não precisa criar toda essa infraestrutura do zero.

Por que usar um SDK para agentes de IA?

Criar um agente de IA completo do zero é complexo. Você precisa lidar com o gerenciamento de estado de conversa em turnos, decidir quando chamar qual API externa, garantir que as respostas da IA permaneçam dentro dos limites, gerenciar vários modelos de IA para tarefas diferentes e implementar medidas de segurança. Construir fluxos de trabalho agênticos do zero significa que você essencialmente criou uma pequena plataforma antes mesmo de chegar à sua lógica de negócios.

O SDK do GitHub Copilot remove essa complexidade fornecendo um mecanismo de agente predefinido e testado em produção. O SDK manipula autenticação, gerenciamento de modelos, sessões de chat e streaming. Você se concentra no que é criado com base nesses blocos de construção: suas ferramentas específicas de domínio e lógica de negócios.

Visão geral da arquitetura

O SDK do GitHub Copilot se comunica com a CLI do GitHub Copilot, que é executada no modo de servidor como um processo local. O SDK gerencia automaticamente o ciclo de vida do processo da CLI. Todas as linguagens do SDK compartilham essa mesma arquitetura.

A arquitetura segue este fluxo:

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

Você interage com o SDK por meio de uma biblioteca de clientes em sua linguagem de programação de sua escolha. O SDK manipula o protocolo de comunicação, portanto, você trabalha com chamadas de método simples em vez de mensagens brutas.

Suporte ao idioma

O SDK fornece bibliotecas idiomáticas para quatro linguagens de programação:

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

Se você estiver criando um aplicativo Web no TypeScript ou em um serviço de back-end em C#, poderá incorporar os mesmos recursos do agente de IA.

Características principais

O SDK fornece vários recursos internos que simplificam a criação de agentes de IA.

Loop de agente do nível de produção

O SDK fornece o mesmo loop de execução comprovado que alimenta a CLI do GitHub Copilot. Esse loop de execução gerencia conversas de vários turnos, chama ferramentas e itera até que a tarefa seja concluída. Você não precisa codificar a lógica de planejamento e orquestração.

Orquestração de ferramentas

Você pode definir ferramentas personalizadas que o agente de IA invoca conforme necessário durante seu processo de raciocínio. Quando você registra uma ferramenta (como lookupCustomer(id)), o modelo de IA do agente pode determinar quando chamá-la. O SDK manipula a fiação para que a IA possa chamar sua ferramenta de forma estruturada por meio de uma chamada de função real no runtime, em vez de adivinhar o código.

No .NET, as ferramentas são definidas usando o AIFunctionFactory do pacote Microsoft.Extensions.AI. Cada ferramenta inclui um nome, uma descrição, um esquema de parâmetro e uma função de manipulador.

Flexibilidade de vários modelos

O SDK não está vinculado a um modelo de IA. Ele dá suporte a vários modelos de IA e permite o roteamento de modelo dinâmico. Por exemplo, você pode usar um modelo mais rápido para tarefas simples e um modelo mais capaz para raciocínio complexo, dentro do mesmo aplicativo.

Streaming em tempo real

O SDK dá suporte a respostas de streaming, ou seja, à medida que a IA gera saída, você pode transmiti-la para seu aplicativo. Por exemplo, você pode transmitir tokens para mostrar um indicador de digitação ou uma resposta parcial em uma interface do usuário de chat. Esse comportamento torna a experiência mais interativa e responsiva.

Autenticação e segurança

O SDK dá suporte a vários métodos de autenticação:

• Usuário conectado do GitHub: reutiliza as credenciais OAuth armazenadas do logon da CLI do Copilot.
• Aplicativo GitHub OAuth: transfere tokens de usuário do aplicativo OAuth do GitHub.
• Variáveis de ambiente: Usa COPILOT_GITHUB_TOKEN, GH_TOKENou GITHUB_TOKEN.
• Traga sua própria chave (BYOK): usa suas próprias chaves de API para provedores como OpenAI, Azure AI Foundry ou Anthropic sem a necessidade de autenticação do GitHub.

Uma assinatura do GitHub Copilot é necessária, a menos que você use a opção BYOK.

Gerenciamento de contexto

O SDK gerencia automaticamente o histórico de conversas em uma sessão. Ele rastreia as mensagens anteriores e as saídas da ferramenta para que o modelo de IA tenha o contexto necessário para interações coerentes de vários turnos. Para sessões longas, o SDK fornece um recurso de sessões infinitas que compacta automaticamente o contexto quando a janela de contexto se aproxima de seu limite, evitando erros de estouro de token.

Conceitos fundamentais

Entender os principais conceitos do SDK ajuda você a trabalhar com ele com eficiência.

Cliente

A CopilotClient classe gerencia a conexão com o servidor da CLI do Copilot. Crie uma instância de cliente para seu aplicativo e use-a para criar sessões. O cliente lida com a inicialização e interrupção do processo da CLI, estabelecendo o canal de comunicação e gerenciando ciclos de vida de sessão.

As opções de configuração incluem AutoStart (inicia automaticamente o servidor da CLI quando a primeira sessão é criada), LogLevel (controla a verbosidade de log), CliPath (especifica um caminho personalizado para o executável da CLI) e GithubToken (fornece um token GitHub diretamente em vez de depender de variáveis de ambiente ou logon da CLI).

Session

Um CopilotSession representa um único contexto de conversa ou tarefa. Cada sessão tem seu próprio histórico de conversa, configuração de modelo, definições de ferramenta e prompt do sistema. Você cria sessões do cliente usando CreateSessionAsync, envia mensagens para eles e recebe respostas por meio de um modelo controlado por eventos.

As principais opções de configuração de sessão incluem:

• Modelo: o modelo de IA a ser usado (por exemplo, gpt-4.1).
• SystemMessage: define a função e o comportamento do agente por meio de um objeto SystemMessageConfig com uma cadeia de caracteres Mode(Acréscimo ou Substituição) e Content.
• Ferramentas: definições de ferramenta personalizadas que o agente pode invocar.
• InfiniteSessions: controla a compactação automática de contexto por meio de um InfiniteSessionConfig objeto. Quando habilitado, você pode configurar BackgroundCompactionThreshold (a porcentagem de uso da janela de contexto que dispara a compactação em segundo plano) e BufferExhaustionThreshold (a porcentagem na qual o SDK força a compactação para evitar o transbordamento de token).

Tools

Ferramentas são funções que você registra com uma sessão para que o agente de IA possa chamá-las durante o raciocínio. Cada ferramenta tem um nome, uma descrição, parâmetros e uma função de manipulador. Quando o modelo de IA decide usar uma ferramenta, o SDK intercepta a solicitação, chama seu manipulador e alimenta o resultado de volta para o modelo para um raciocínio adicional.

No .NET, você define as ferramentas usando AIFunctionFactory.Create de 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

O SDK usa um modelo de comunicação controlado por eventos. Quando você envia uma mensagem para uma sessão, o SDK aciona eventos à medida que o processamento ocorre:

• AssistantMessageEvent: O modelo de IA produziu uma resposta completa.
• AssistantMessageDeltaEvent: o modelo de IA produziu um token de resposta parcial durante o streaming. A Data.DeltaContent propriedade contém o texto incremental, que você pode exibir em tempo real.
• SessionIdleEvent: O processamento concluído da sessão (incluindo todas as chamadas de ferramenta).
• SessionErrorEvent: ocorreu um erro durante o processamento.
• ToolExecutionStartEvent e ToolExecutionCompleteEvent: uma ferramenta foi invocada.

Você assina esses eventos para capturar as respostas do agente e tratar os erros. Para cenários sem streaming, use AssistantMessageEvent para coletar a resposta completa. Para cenários de streaming (como mostrar um indicador de digitação em uma interface do usuário de chat), use AssistantMessageDeltaEvent para exibir tokens conforme eles chegam.

Ganchos de sessão

O SDK fornece ganchos que permitem interceptar e modificar o comportamento do agente em pontos-chave:

• OnPreToolUse: interceptar chamadas de ferramenta antes da execução. Seu manipulador retorna um PermissionDecision valor:Allow continuar, Deny bloquear a chamada ou Ask solicitar confirmação ao usuário.
• OnPostToolUse: processar os resultados da ferramenta após a execução, útil para registrar ou modificar resultados antes que eles cheguem ao modelo.
• OnUserPromptSubmitted: intercepte e modifique os prompts do usuário antes do processamento.
• OnErrorOccurred: manipular erros retornando um ErrorHandling valor:Retry para tentar a operação novamente, Skip para continuar sem o resultado ou Abort para interromper o processamento.
• OnSessionStart: é executado quando uma sessão começa, útil para tarefas de inicialização.
• OnSessionEnd: é executado quando uma sessão termina, útil para limpeza ou registro em log.

Esses ganchos permitem que você implemente controles de permissão, registre logs e estabeleça barreiras de segurança.

Pré-requisitos para desenvolvimento do .NET

Para usar o SDK do GitHub Copilot em um aplicativo .NET, seu ambiente precisa:

• .NET 8.0 ou posterior.
• A CLI do GitHub Copilot, instalada e disponível no PATH do sistema.
• Uma conta do GitHub com uma assinatura do Copilot ativa (ou suas próprias chaves de API para BYOK).
• O GitHub.Copilot.SDK pacote NuGet.
• O Microsoft.Extensions.AI pacote NuGet (para definir ferramentas usando AIFunctionFactory).

Resumo

O SDK do GitHub Copilot fornece uma plataforma poderosa e pronta para produção para criar agentes de IA em seus aplicativos. Ao abstrair as complexidades da orquestração do agente, da integração de ferramentas e do gerenciamento de contexto, o SDK permite que você se concentre em definir os recursos do agente e a lógica de negócios. Com suporte para vários idiomas, streaming em tempo real e opções de autenticação flexível, o SDK do GitHub Copilot é uma opção versátil para adicionar a funcionalidade do agente de IA a uma ampla gama de aplicativos.