Úselo cuando: necesite fijar una versión específica de la CLI, o trabajar con el SDK de Go (que no incluye una CLI).
Cómo funciona
De forma predeterminada, los SDK de Node.js, Python y .NET incluyen su propia dependencia de la CLI (consulte Configuración predeterminada (CLI agrupada)). Si necesita invalidar esto (por ejemplo, para usar una CLI instalada por el sistema), puede usar la Connection opción .
Características principales:
- Proporcione explícitamente la ruta de acceso binaria de la CLI.
- Es responsable de la compatibilidad de la versión de la CLI con el SDK.
- La autenticación usa las credenciales del usuario que ha iniciado sesión desde la cadena de claves del sistema (o env vars)
- La comunicación se produce a través de stdio
Configuración
Uso de un binario local de CLI
TypeScript
import { CopilotClient } from "@github/copilot-sdk";
const client = new CopilotClient({
cliPath: "/usr/local/bin/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
from copilot.generated.session_events import AssistantMessageData
from copilot.session import PermissionHandler
client = CopilotClient({
"cli_path": "/usr/local/bin/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("Hello!")
if response:
match response.data:
case AssistantMessageData() as data:
print(data.content)
await client.stop()
Go
Nota:
El SDK de Go no agrupa una CLI, por lo que siempre debe proporcionar Connection.
package main
import (
"context"
"fmt"
"log"
copilot "github.com/github/copilot-sdk/go"
)
func main() {
ctx := context.Background()
client := copilot.NewClient(&copilot.ClientOptions{
Connection: copilot.StdioConnection{Path: "/usr/local/bin/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!"})
if response != nil {
if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
fmt.Println(d.Content)
}
}
}
client := copilot.NewClient(&copilot.ClientOptions{
Connection: copilot.StdioConnection{Path: "/usr/local/bin/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!"})
if response != nil {
if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
fmt.Println(d.Content)
}
}
.NET
var client = new CopilotClient(new CopilotClientOptions
{
Connection = RuntimeConnection.ForStdio(path: "/usr/local/bin/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);
Opciones adicionales
const client = new CopilotClient({
cliPath: "/usr/local/bin/copilot",
// Set log level for debugging
logLevel: "debug",
// Pass extra CLI arguments
cliArgs: ["--log-dir=/tmp/copilot-logs"],
// Set working directory
cwd: "/path/to/project",
});
Uso de variables de entorno
En lugar de la cadena de claves, puede autenticarse a través de variables de entorno. Esto es útil para CI o cuando no desea el inicio de sesión interactivo.
# Set one of these (in priority order):
export COPILOT_GITHUB_TOKEN="gho_xxxx" # Recommended
export GH_TOKEN="gho_xxxx" # GitHub CLI compatible
export GITHUB_TOKEN="gho_xxxx" # GitHub Actions compatible
El SDK los recoge automáticamente, sin necesidad de cambios de código.
Administración de sesiones
Las sesiones tienen como valor predeterminado efímero. Para crear sesiones reanudables, proporcione su propio identificador de sesión:
// Create a named session
const session = await client.createSession({
sessionId: "my-project-analysis",
model: "gpt-4.1",
});
// Later, resume it
const resumed = await client.resumeSession("my-project-analysis");
El estado de sesión se almacena localmente en ~/.copilot/session-state/{sessionId}/.
Limitaciones
| Limitación | Detalles |
|---|---|
| Compatibilidad de versiones | Debe asegurarse de que la versión de la CLI sea compatible con el SDK. |
| Usuario único | Las credenciales están vinculadas a la persona que ha iniciado sesión en la CLI |
| Solo local | La CLI se ejecuta en la misma máquina que la aplicación. |
| Sin multiinquilino | No se pueden atender varios usuarios desde una instancia de la CLI |
Pasos siguientes
- Configuración predeterminada (CLI agrupada): use la CLI integrada del SDK (recomendado para la mayoría de los casos de uso)
- Crea tu primera aplicación con tecnología Copilot: Creación de una aplicación interactiva completa
- Autenticación: todos los métodos de autenticación en detalle