Usando uma CLI agrupada com o SDK do Copilot

Empacotar CLI do Copilot junto com seu aplicativo para que os usuários não precisem instalar ou configurar nada separadamente.

Quem pode usar esse recurso?

SDK do GitHub Copilot está disponível com todos os Copilot planos.

Neste artigo

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Envie CLI do Copilot como parte do aplicativo para que os usuários possam começar sem nenhuma configuração adicional.

          **Melhor para:** Aplicativos de área de trabalho, ferramentas autônomas, aplicativos Electron e utilitários de CLI distribuíveis.

Como funciona

Em vez de depender de uma CLI instalada globalmente, você inclui o binário da CLI no pacote de aplicativos. O SDK faz referência à sua cópia empacotada por meio da opção cliPath. As principais características são:

  • O binário da CLI é fornecido com seu aplicativo— nenhuma instalação separada é necessária.
  • Você controla a versão exata da CLI que seu aplicativo usa.
  • Os usuários se autenticam por meio de seu aplicativo, variáveis de ambiente ou BYOK.
  • As sessões são gerenciadas por usuário em seu computador.

Configuração

Etapa 1: Incluir a CLI em seu projeto

A CLI é distribuída como parte do @github/copilot pacote npm.

npm install @github/copilot

Etapa 2: aponte o SDK para a CLI agrupada

Node.js/TypeScript

import { CopilotClient } from "@github/copilot-sdk";
import path from "path";

const client = new CopilotClient({
    // Point to the CLI binary in your app bundle
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

Python

from copilot import CopilotClient, PermissionHandler
from pathlib import Path

client = CopilotClient({
    "cli_path": str(Path(__file__).parent / "vendor" / "copilot"),
})
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)

await client.stop()

Go

client := copilot.NewClient(&copilot.ClientOptions{
    CLIPath: "./vendor/copilot",
})
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
fmt.Println(*response.Data.Content)

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = Path.Combine(AppContext.BaseDirectory, "vendor", "copilot"),
});

await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-4.1" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);

Estratégias de autenticação

Ao agrupar a CLI, você precisa decidir como os usuários se autenticarão. O diagrama a seguir ilustra padrões comuns.

Diagrama mostrando as opções de estratégia de autenticação para uma implantação da CLI agrupada.

Opção A: credenciais de entrada do usuário (mais simples)

O usuário entra na CLI uma vez e seu aplicativo empacotado usa essas credenciais. Nenhum código extra é necessário, esse é o comportamento padrão.

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    // Default: uses signed-in user credentials
});

Opção B: Token via variável de ambiente

Defina um token programaticamente ou instrua os usuários a definir um antes de iniciar seu aplicativo:

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),
    },
});

Substitua getUserToken() pela lógica em seu aplicativo que recupera o token OAuth do GitHub usuário.

Opção C: BYOK (nenhuma GitHub autenticação necessária)

Se você gerenciar suas próprias chaves de provedor de modelo, os usuários não precisarão de GitHub contas:

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

Gerenciamento de sessão

Normalmente, os aplicativos empacotados desejam sessões nomeadas para que os usuários possam retomar as conversas:

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-4.1",
});

// Resume the session in a later run
const resumed = await client.resumeSession(sessionId);

O estado da sessão é armazenado em ~/.copilot/session-state/SESSION-ID/, onde SESSION-ID está a ID da sessão fornecida.

Padrões de distribuição

Aplicativo da área de trabalho (Electron, Tauri)

Inclua o binário da CLI no diretório de recursos do aplicativo:

import { app } from "electron";
import path from "path";

const cliPath = path.join(
    app.isPackaged ? process.resourcesPath : __dirname,
    "copilot"
);

const client = new CopilotClient({ cliPath });

Ferramenta da CLI

Para ferramentas de CLI distribuíveis, determine o caminho relativo ao seu binário.

import { fileURLToPath } from "url";
import path from "path";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const cliPath = path.join(__dirname, "..", "vendor", "copilot");

const client = new CopilotClient({ cliPath });

Binários específicos da plataforma

Ao distribuir para várias plataformas, inclua o binário correto para cada destino:

my-app/
├── vendor/
│   ├── copilot-darwin-arm64    # macOS Apple Silicon
│   ├── copilot-darwin-x64      # macOS Intel
│   ├── copilot-linux-x64       # Linux x64
│   └── copilot-win-x64.exe     # Windows x64
└── src/
    └── index.ts

import os from "os";

function getCLIPath(): string {
    const platform = process.platform;   // "darwin", "linux", "win32"
    const arch = os.arch();              // "arm64", "x64"
    const ext = platform === "win32" ? ".exe" : "";
    const name = `copilot-${platform}-${arch}${ext}`;
    return path.join(__dirname, "vendor", name);
}

const client = new CopilotClient({
    cliPath: getCLIPath(),
});

Limitações

LimitationDetalhes
          **Tamanho do conjunto** | O binário da CLI aumenta o tamanho da distribuição do aplicativo. |

| Atualizações | Você gerencia as atualizações de versão da CLI em seu ciclo de lançamento. | | Builds de plataforma | Binários separados são necessários para cada sistema operacional/arquitetura. | | Usuário único | Cada instância da CLI agrupada atende a um usuário. |

Próximas Etapas