Configuração padrão (CLI empacotada)

Melhor para: A maioria das aplicações—aplicativos para desktop, ferramentas autônomas, utilitários de linha de comando, protótipos e muito mais.

Como funciona

Quando você instala o SDK, o binário da CLI Copilot é incluído automaticamente. O SDK o inicia como um processo filho e se comunica via stdio. Não há nada extra para configurar.

Diagrama: Fluxograma mostrando o processo descrito.

Principais características:

O binário da CLI está incluído com o SDK — nenhuma instalação separada é necessária
O SDK gerencia a versão da CLI para garantir a compatibilidade
Os usuários se autenticam por meio de seu aplicativo (ou usam env vars/BYOK)
As sessões são gerenciadas por usuário em seu computador

Início rápido

TypeScript

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

const client = new CopilotClient();

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
from copilot.session import PermissionHandler

client = CopilotClient()
await client.start()

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

await client.stop()

Observação

O SDK do Go não agrupa a CLI. Você deve instalar a CLI separadamente ou definir Connection para apontar para um binário existente. Confira Configuração da CLI local para obter detalhes.

package main

import (
    "context"
    "fmt"
    "log"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()

    client := copilot.NewClient(nil)
    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!"})
    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
        fmt.Println(d.Content)
    }
}

client := copilot.NewClient(nil)
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!"})
if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
    fmt.Println(d.Content)
}

.NET

await using var client = new CopilotClient();
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);

Java

Observação

O SDK do Java não agrupa ou insira a CLI do Copilot. Você deve instalar a CLI separadamente e configurar seu caminho por meio de Connection ou pela variável de ambiente COPILOT_CLI_PATH.

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient(new CopilotClientOptions()
    // Point to the CLI binary installed on the system
    .setCliPath("/path/to/vendor/copilot")
);
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("Hello!")).get();
System.out.println(response.getData().content());

client.stop().get();

Estratégias de autenticação

Você precisa decidir como os usuários se autenticarão. Aqui estão os padrões comuns:

Diagrama: Fluxograma mostrando o processo descrito.

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

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

const client = new CopilotClient();
// Default: uses signed-in user credentials

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

Envie seu aplicativo com instruções para definir um token ou defina-o programaticamente:

const client = new CopilotClient({
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),  // Your app provides the token
    },
});

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

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

const client = new CopilotClient();

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

Consulte o BYOK (bring your own key) para obter detalhes completos.

Gerenciamento de sessão

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

const client = new CopilotClient();

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

// User closes app...
// Later, resume where they left off
const resumed = await client.resumeSession(sessionId);

O estado da sessão persiste em ~/.copilot/session-state/{sessionId}/.

Quando seguir em frente

Necessidade	Próximo Guia
Usuários entrando com contas GitHub
Configuração do OAuth do GitHub
Executar em um servidor em vez de computadores de usuário
Configuração de serviços de back-end
Usar suas próprias chaves de modelo
BYOK (bring your own key)

Próximas Etapas

BYOK (bring your own key): Use suas próprias chaves de provedor de modelo
Retomada e persistência da sessão: Gerenciamento avançado de sessão
Crie seu primeiro aplicativo com tecnologia do Copilot: Criar um aplicativo completo

Neste artigo