BYOK (Bring Your Own Key - traga sua própria chave)

Provedores com suporte

Início rápido: Microsoft Foundry

Microsoft Foundry é um destino de implantação BYOK comum para empresas. Aqui está um exemplo completo:

import asyncio
import os
from copilot import CopilotClient
from copilot.session import PermissionHandler

FOUNDRY_MODEL_URL = "https://<resource-name>.openai.azure.com/openai/v1/"
# Set FOUNDRY_API_KEY environment variable

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", provider={
        "type": "openai",
        "base_url": FOUNDRY_MODEL_URL,
        "wire_api": "responses",  # Use "completions" for older models
        "api_key": os.environ["FOUNDRY_API_KEY"],
    })

    done = asyncio.Event()

    def on_event(event):
        if event.type.value == "assistant.message":
            print(event.data.content)
        elif event.type.value == "session.idle":
            done.set()

    session.on(on_event)
    await session.send("What is 2+2?")
    await done.wait()

    await session.disconnect()
    await client.stop()

asyncio.run(main())

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

const FOUNDRY_MODEL_URL = "https://<resource-name>.openai.azure.com/openai/v1/";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.2-codex",  // Your deployment name
    provider: {
        type: "openai",
        baseUrl: FOUNDRY_MODEL_URL,
        wireApi: "responses",  // Use "completions" for older models
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});

session.on("assistant.message", (event) => {
    console.log(event.data.content);
});

await session.sendAndWait({ prompt: "What is 2+2?" });
await client.stop();

package main

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

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        panic(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-5.2-codex",  // Your deployment name
        Provider: &copilot.ProviderConfig{
            Type:    "openai",
            BaseURL: "https://<resource-name>.openai.azure.com/openai/v1/",
            WireAPI: "responses",  // Use "completions" for older models
            APIKey:  os.Getenv("FOUNDRY_API_KEY"),
        },
    })
    if err != nil {
        panic(err)
    }

    response, err := session.SendAndWait(ctx, copilot.MessageOptions{
        Prompt: "What is 2+2?",
    })
    if err != nil {
        panic(err)
    }

    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
        fmt.Println(d.Content)
    }
}

using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5.2-codex",  // Your deployment name
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = "https://<resource-name>.openai.azure.com/openai/v1/",
        WireApi = "responses",  // Use "completions" for older models
        ApiKey = Environment.GetEnvironmentVariable("FOUNDRY_API_KEY"),
    },
});

var response = await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "What is 2+2?",
});
Console.WriteLine(response?.Data.Content);

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient();
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-5.2-codex")  // Your deployment name
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setProvider(new ProviderConfig()
        .setType("openai")
        .setBaseUrl("https://<resource-name>.openai.azure.com/openai/v1/")
        .setWireApi("responses")  // Use "completions" for older models
        .setApiKey(System.getenv("FOUNDRY_API_KEY")))
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("What is 2+2?")).get();
System.out.println(response.getData().content());

client.stop().get();

Referência de configuração do provedor

Campos ProviderConfig

Formato da API do Wire

A wireApi configuração determina qual formato de API OpenAI usar:

• "completions" (padrão) – API de Conclusões de Chat (/chat/completions) para ampla compatibilidade de modelo.
• "responses" - API Responses para gerenciamento de estado multiturno, uso de namespaces para ferramentas e suporte ao raciocínio.

Os modelos da Anthropic sempre usam a API Messages da Anthropic, independentemente dessa configuração.

Notas específicas do tipo

OpenAI (type: "openai")

• Funciona com a API da OpenAI e qualquer endpoint compatível com a OpenAI
• baseUrl deve incluir o caminho completo (por exemplo, https://api.openai.com/v1)

Azure (type: "azure")

• Usar para pontos de extremidade nativos do OpenAI do Azure
• baseUrl deve ser apenas o host (por exemplo, https://my-resource.openai.azure.com)
• NÃO inclua /openai/v1 na URL – o SDK manipula a construção do caminho

Anthropic (type: "anthropic")

• Para acesso direto à API da Anthropic
• Usa o formato de API específico de Claude

Configurações de exemplo

OpenAI direto

provider: {
    type: "openai",
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY,
}

Azure OpenAI (ponto de extremidade nativo do Azure)

Utilize type: "azure" para os endpoints em *.openai.azure.com:

provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",  // Just the host
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: {
        apiVersion: "2024-10-21",
    },
}

Microsoft Foundry (ponto de extremidade compatível com OpenAI)

Para implantações do Microsoft Foundry com /openai/v1/ pontos de extremidade, usetype: "openai":

provider: {
    type: "openai",
    baseUrl: "https://<resource-name>.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // For GPT-5 series models
}

Ollama (local)

provider: {
    type: "openai",
    baseUrl: "http://localhost:11434/v1",
    // No apiKey needed for local Ollama
}

Microsoft Foundry Local

Microsoft Foundry Local permite executar modelos de IA localmente em seu próprio dispositivo com uma API compatível com OpenAI. Instale através do Foundry Local CLI e direcione o SDK para o endpoint local.

provider: {
    type: "openai",
    baseUrl: "http://localhost:<PORT>/v1",
    // No apiKey needed for local Foundry Local
}

Para começar a usar o Foundry Local:

# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# macOS / Linux: see https://foundrylocal.ai for installation instructions
# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status

Anthropic

provider: {
    type: "anthropic",
    baseUrl: "https://api.anthropic.com",
    apiKey: process.env.ANTHROPIC_API_KEY,
}

Autenticação com Bearer Token

Alguns provedores exigem autenticação de token de portador em vez de chaves de API. Forneça um token estático com bearerTokenou forneça um bearerTokenProvider retorno de chamada que o runtime do SDK GitHub Copilot invoca antes das solicitações do provedor de saída. O callback ou a biblioteca de identidade que ele encapsula gerencia o cache e a renovação de tokens.

Use bearerToken quando seu aplicativo já tiver um token:

provider: {
    type: "openai",
    baseUrl: "https://<resource-name>.openai.azure.com/openai/v1/",
    bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
}

Use bearerTokenProvider para adquirir tokens sob demanda:

provider: {
    type: "openai",
    baseUrl: "https://my-custom-endpoint.example.com/v1",
    bearerTokenProvider: async () => {
        return await acquireBearerToken();
    },
}

Para obter mais detalhes sobre como adquirir e renovar tokens de portador do Microsoft Entra, consulte Identidade gerenciada do Azure com BYOK.

Listagem de modelo personalizado

Ao usar BYOK, o servidor da CLI pode não saber quais modelos seu provedor dá suporte. Você pode fornecer um manipulador personalizado onListModels no nível do cliente para que client.listModels() retorne os modelos do provedor no formato padrão ModelInfo . Isso permite que os consumidores downstream descubram modelos disponíveis sem consultar a CLI.

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

const client = new CopilotClient({
    onListModels: () => [
        {
            id: "my-custom-model",
            name: "My Custom Model",
            capabilities: {
                supports: { vision: false, reasoningEffort: false },
                limits: { max_context_window_tokens: 128000 },
            },
        },
    ],
});

from copilot import CopilotClient
from copilot.client import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits

client = CopilotClient(
    on_list_models=lambda: [
        ModelInfo(
            id="my-custom-model",
            name="My Custom Model",
            capabilities=ModelCapabilities(
                supports=ModelSupports(vision=False, reasoning_effort=False),
                limits=ModelLimits(max_context_window_tokens=128000),
            ),
        )
    ],
)

package main

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

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) {
            return []copilot.ModelInfo{
                {
                    ID:   "my-custom-model",
                    Name: "My Custom Model",
                    Capabilities: copilot.ModelCapabilities{
                        Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false},
                        Limits:   copilot.ModelLimits{MaxContextWindowTokens: copilot.Int(128000)},
                    },
                },
            }, nil
        },
    })
    _ = client
}

using GitHub.Copilot;

var client = new CopilotClient(new CopilotClientOptions
{
    OnListModels = (ct) => Task.FromResult<IList<ModelInfo>>(new List<ModelInfo>
    {
        new()
        {
            Id = "my-custom-model",
            Name = "My Custom Model",
            Capabilities = new ModelCapabilities
            {
                Supports = new ModelSupports { Vision = false, ReasoningEffort = false },
                Limits = new ModelLimits { MaxContextWindowTokens = 128000 }
            }
        }
    })
});

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;
import java.util.concurrent.CompletableFuture;

var client = new CopilotClient(new CopilotClientOptions()
    .setOnListModels(() -> CompletableFuture.completedFuture(List.of(
        new ModelInfo()
            .setId("my-custom-model")
            .setName("My Custom Model")
            .setCapabilities(new ModelCapabilities()
                .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))
                .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))
    )))
);

Os resultados são armazenados em cache após a primeira chamada, assim como o comportamento padrão. O manipulador substitui completamente o RPC models.list da CLI — não ocorre nenhum fallback para o servidor.

Limitações

Limitações de funcionalidades

Alguns recursos de Copilot podem se comportar de forma diferente com BYOK:

• Disponibilidade do modelo – somente os modelos compatíveis com seu provedor estão disponíveis
• Limitação de taxa - Sujeito aos limites de taxa do seu provedor, não aos do Copilot
• Usage tracking - O uso é acompanhado pelo seu provedor, não GitHub Copilot
• Solicitações premium - Não são contabilizadas nas cotas de solicitações premium do Copilot

Limitações específicas do provedor

Troubleshooting

Erro "Modelo não especificado"

Ao usar BYOK, o model parâmetro é necessário:

// ❌ Error: Model required with custom provider
const session = await client.createSession({
    provider: { type: "openai", baseUrl: "..." },
});

// ✅ Correct: Model specified
const session = await client.createSession({
    model: "gpt-4",  // Required!
    provider: { type: "openai", baseUrl: "..." },
});

Confusão quanto ao tipo de ponto de extremidade no Azure

Para pontos de extremidade do OpenAI do Azure (*.openai.azure.com), use o tipo correto:

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

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.4",
    provider: {
        type: "azure",
        baseUrl: "https://my-resource.openai.azure.com",
    },
});

// ❌ Wrong: Using "openai" type with native Azure endpoint
provider: {
    type: "openai",  // This won't work correctly
    baseUrl: "https://my-resource.openai.azure.com",
}

// ✅ Correct: Using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",
}

No entanto, se a implantação do Microsoft Foundry fornecer um caminho de ponto de extremidade compatível com OpenAI (por exemplo, /openai/v1/), usetype: "openai":

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

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.4",
    provider: {
        type: "openai",
        baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    },
});

// ✅ Correct: OpenAI-compatible Microsoft Foundry endpoint
provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
}

Conexão recusada (Ollama)

Verifique se o Ollama está em execução e acessível:

# Check Ollama is running
curl http://localhost:11434/v1/models

# Start Ollama if not running
ollama serve

Conexão recusada (Foundry Local)

O Foundry Local usa uma porta dinâmica que pode mudar entre reinicializações. Confirme a porta ativa:

# Check the service status and port
foundry service status

Atualize-o baseUrl para corresponder à porta mostrada na saída. Se o serviço não estiver em execução, inicie um modelo para iniciá-lo:

foundry model run phi-4-mini

Falha na autenticação

1. Verifique se a chave de API está correta e não expirou
2. Verifique se o baseUrl corresponde ao formato esperado pelo seu provedor
3. Para tokens de portador, verifique se o token completo é fornecido (não apenas um prefixo)

Próximas Etapas 

• Autenticação – Saiba mais sobre todos os métodos de autenticação
• Crie seu primeiro aplicativo com tecnologia do Copilot - Crie seu primeiro aplicativo com tecnologia do Copilot