{"meta":{"title":"BYOK (Bring Your Own Key - traga sua própria chave)","intro":"O BYOK permite que você use o SDK do Copilot com suas próprias chaves de API de provedores de modelos, sem passar pela autenticação do GitHub Copilot. Isso é útil para implantações empresariais, hospedagem de modelo personalizado ou quando você deseja cobrança direta com seu provedor de modelo.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/auth","title":"Autenticação"},{"href":"/pt/copilot/how-tos/copilot-sdk/auth/byok","title":"BYOK"}],"documentType":"article"},"body":"# BYOK (Bring Your Own Key - traga sua própria chave)\n\nO BYOK permite que você use o SDK do Copilot com suas próprias chaves de API de provedores de modelos, sem passar pela autenticação do GitHub Copilot. Isso é útil para implantações empresariais, hospedagem de modelo personalizado ou quando você deseja cobrança direta com seu provedor de modelo.\n\n\n\n\n\n## Provedores com suporte\n\n| Fornecedor | Digite um valor | Observações |\n| ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| OpenAI | `\"openai\"` | API OpenAI e endpoints compatíveis com OpenAI |\n| Microsoft Foundry/Azure OpenAI | | |\n| `\"openai\"` ou `\"azure\"` | Usar `\"openai\"` para `/openai/v1/`; usar `\"azure\"` para endpoints nativos do Azure | |\n| Anthropic | `\"anthropic\"` | Modelos de Claude |\n| Ollama | `\"openai\"` | Modelos locais por meio da API compatível com OpenAI |\n| Microsoft Foundry Local | `\"openai\"` | Executar modelos de IA localmente em seu dispositivo por meio da API compatível com OpenAI |\n| Outros compatíveis com OpenAI | `\"openai\"` | vLLM, LiteLLM, etc. |\n\n## Início rápido: Microsoft Foundry\n\nMicrosoft Foundry é um destino comum de implantação BYOK para empresas. Aqui está um exemplo completo:\n\n
\n
Python
\n\n```python\nimport asyncio\nimport os\nfrom copilot import CopilotClient\nfrom copilot.session import PermissionHandler\n\nFOUNDRY_MODEL_URL = \"https://.openai.azure.com/openai/v1/\"\n# Set FOUNDRY_API_KEY environment variable\n\nasync def main():\n client = CopilotClient()\n await client.start()\n\n session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5.2-codex\", provider={\n \"type\": \"openai\",\n \"base_url\": FOUNDRY_MODEL_URL,\n \"wire_api\": \"responses\", # Use \"completions\" for older models\n \"api_key\": os.environ[\"FOUNDRY_API_KEY\"],\n })\n\n done = asyncio.Event()\n\n def on_event(event):\n if event.type.value == \"assistant.message\":\n print(event.data.content)\n elif event.type.value == \"session.idle\":\n done.set()\n\n session.on(on_event)\n await session.send(\"What is 2+2?\")\n await done.wait()\n\n await session.disconnect()\n await client.stop()\n\nasyncio.run(main())\n```\n\n
\n\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst FOUNDRY_MODEL_URL = \"https://.openai.azure.com/openai/v1/\";\n\nconst client = new CopilotClient();\nconst session = await client.createSession({\n model: \"gpt-5.2-codex\", // Your deployment name\n provider: {\n type: \"openai\",\n baseUrl: FOUNDRY_MODEL_URL,\n wireApi: \"responses\", // Use \"completions\" for older models\n apiKey: process.env.FOUNDRY_API_KEY,\n },\n});\n\nsession.on(\"assistant.message\", (event) => {\n console.log(event.data.content);\n});\n\nawait session.sendAndWait({ prompt: \"What is 2+2?\" });\nawait client.stop();\n```\n\n
\n\n
Go
\n\n```golang\npackage main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n copilot \"github.com/github/copilot-sdk/go\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := copilot.NewClient(nil)\n if err := client.Start(ctx); err != nil {\n panic(err)\n }\n defer client.Stop()\n\n session, err := client.CreateSession(ctx, &copilot.SessionConfig{\n Model: \"gpt-5.2-codex\", // Your deployment name\n Provider: &copilot.ProviderConfig{\n Type: \"openai\",\n BaseURL: \"https://.openai.azure.com/openai/v1/\",\n WireAPI: \"responses\", // Use \"completions\" for older models\n APIKey: os.Getenv(\"FOUNDRY_API_KEY\"),\n },\n })\n if err != nil {\n panic(err)\n }\n\n response, err := session.SendAndWait(ctx, copilot.MessageOptions{\n Prompt: \"What is 2+2?\",\n })\n if err != nil {\n panic(err)\n }\n\n if d, ok := response.Data.(*copilot.AssistantMessageData); ok {\n fmt.Println(d.Content)\n }\n}\n```\n\n
\n\n
.NET
\n\n```csharp\nusing GitHub.Copilot;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n Model = \"gpt-5.2-codex\", // Your deployment name\n Provider = new ProviderConfig\n {\n Type = \"openai\",\n BaseUrl = \"https://.openai.azure.com/openai/v1/\",\n WireApi = \"responses\", // Use \"completions\" for older models\n ApiKey = Environment.GetEnvironmentVariable(\"FOUNDRY_API_KEY\"),\n },\n});\n\nvar response = await session.SendAndWaitAsync(new MessageOptions\n{\n Prompt = \"What is 2+2?\",\n});\nConsole.WriteLine(response?.Data.Content);\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient();\nclient.start().get();\n\nvar session = client.createSession(new SessionConfig()\n .setModel(\"gpt-5.2-codex\") // Your deployment name\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n .setProvider(new ProviderConfig()\n .setType(\"openai\")\n .setBaseUrl(\"https://.openai.azure.com/openai/v1/\")\n .setWireApi(\"responses\") // Use \"completions\" for older models\n .setApiKey(System.getenv(\"FOUNDRY_API_KEY\")))\n).get();\n\nvar response = session.sendAndWait(new MessageOptions()\n .setPrompt(\"What is 2+2?\")).get();\nSystem.out.println(response.getData().content());\n\nclient.stop().get();\n```\n\n
\n\n
\n\n## Referência de configuração do provedor\n\n### Campos ProviderConfig\n\n| Campo | Tipo | Description |\n| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | | |\n| `\"openai\"` | | |\n| \\| | | |\n| `\"azure\"` | | |\n| \\| | | |\n| `\"anthropic\"` | | |\n| Tipo de provedor (padrão: `\"openai\"`) | | |\n| `baseUrl` / `base_url` | cadeia | |\n| **Obrigatório**. URL do endpoint da API | | |\n| `apiKey` / `api_key` | cadeia | Chave de API (opcional para provedores locais como o Ollama) |\n| `bearerToken` / `bearer_token` | cadeia | Autenticação de token de portador (tem precedência sobre a apiKey) |\n| `bearerTokenProvider` / `bearer_token_provider` | retorno de chamada | Retorna um token de portador sob demanda (tem precedência sobre `apiKey` e `bearerToken`) |\n| `wireApi` / `wire_api` | | |\n| `\"completions\"` | | |\n| \\| | | |\n| `\"responses\"` | | |\n| Selecione `\"completions\"` para ampla compatibilidade com modelos (a API Chat Completions); selecione `\"responses\"` para gerenciamento de estado em vários turnos, namespace de ferramentas e suporte a raciocínio (a API Responses). Anthropic modelos sempre usam a API de Mensagens independentemente dessa configuração. | | |\n| `azure.apiVersion` / `azure.api_version` | cadeia | Versão da API do Azure. Quando definido, o tempo de execução usa a rota de implantação com controle de versão; quando omitido, usa a rota `v1` sem versão de disponibilidade geral. |\n\n### Formato da API do Wire\n\nA `wireApi` configuração determina qual formato de API OpenAI usar:\n\n* **`\"completions\"`** (padrão) – API de Conclusões de Chat (`/chat/completions`) para ampla compatibilidade de modelo.\n* **`\"responses\"`** - API Responses para gerenciamento de estado multiturno, uso de namespaces para ferramentas e suporte ao raciocínio.\n\nOs modelos da Anthropic sempre usam a API Messages da Anthropic, independentemente dessa configuração.\n\n### Notas específicas do tipo\n\n**OpenAI (`type: \"openai\"`)**\n\n* Funciona com a API da OpenAI e qualquer endpoint compatível com a OpenAI\n* `baseUrl` deve incluir o caminho completo (por exemplo, `https://api.openai.com/v1`)\n\n**Azure (`type: \"azure\"`)**\n\n* Usar para pontos de extremidade nativos do OpenAI do Azure\n* `baseUrl` deve ser apenas o host (por exemplo, `https://my-resource.openai.azure.com`)\n* NÃO inclua `/openai/v1` na URL – o SDK manipula a construção do caminho\n\n**Anthropic (`type: \"anthropic\"`)**\n\n* Para acesso direto à API da Anthropic\n* Usa o formato de API específico de Claude\n\n## Configurações de exemplo\n\n### OpenAI direto\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"https://api.openai.com/v1\",\n apiKey: process.env.OPENAI_API_KEY,\n}\n```\n\n### Azure OpenAI (ponto de extremidade nativo do Azure)\n\nUtilize `type: \"azure\"` para os endpoints em `*.openai.azure.com`:\n\n```typescript\nprovider: {\n type: \"azure\",\n baseUrl: \"https://my-resource.openai.azure.com\", // Just the host\n apiKey: process.env.AZURE_OPENAI_KEY,\n azure: {\n apiVersion: \"2024-10-21\",\n },\n}\n```\n\n### Microsoft Foundry (endpoint compatível com OpenAI)\n\nPara implantações do Microsoft Foundry com pontos de extremidade `/openai/v1/`, use `type: \"openai\"`:\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"https://.openai.azure.com/openai/v1/\",\n apiKey: process.env.FOUNDRY_API_KEY,\n wireApi: \"responses\", // For GPT-5 series models\n}\n```\n\n### Ollama (local)\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"http://localhost:11434/v1\",\n // No apiKey needed for local Ollama\n}\n```\n\n### Microsoft Foundry Local\n\n[Microsoft Foundry Local](https://foundrylocal.ai) 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.\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"http://localhost:/v1\",\n // No apiKey needed for local Foundry Local\n}\n```\n\n> \\[!NOTE]\n> Foundry Local inicia em uma **porta dinâmica**– a porta não é fixa. Use `foundry service status` para confirmar a porta em que o serviço está escutando no momento e use essa porta em sua `baseUrl`.\n\nPara começar a usar o Foundry Local:\n\n```bash\n# Windows: Install Foundry Local CLI (requires winget)\nwinget install Microsoft.FoundryLocal\n\n# macOS / Linux: see https://foundrylocal.ai for installation instructions\n# List available models\nfoundry model list\n\n# Run a model (starts the local server automatically)\nfoundry model run phi-4-mini\n\n# Check the port the service is running on\nfoundry service status\n```\n\n### Anthropic\n\n```typescript\nprovider: {\n type: \"anthropic\",\n baseUrl: \"https://api.anthropic.com\",\n apiKey: process.env.ANTHROPIC_API_KEY,\n}\n```\n\n### Autenticação com Bearer Token\n\nAlguns provedores exigem autenticação de token de portador em vez de chaves de API. Forneça um token estático com `bearerToken`ou forneça um retorno de chamada `bearerTokenProvider` que o tempo de execução do SDK GitHub Copilot invoca antes das solicitações do provedor de saída. O retorno de chamada ou a biblioteca de identidade incluído gerencia o armazenamento em cache e a renovação de tokens.\n\nUse `bearerToken` quando seu aplicativo já tiver um token:\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"https://.openai.azure.com/openai/v1/\",\n bearerToken: process.env.MY_BEARER_TOKEN, // Sets Authorization header\n}\n```\n\n> \\[!NOTE]\n> A opção `bearerToken` aceita apenas uma **string de token estático**. O SDK não atualiza esse token automaticamente. Se o token expirar, as solicitações falharão e você precisará criar uma nova sessão com um novo token.\n\nUse `bearerTokenProvider` para adquirir tokens sob demanda:\n\n\n\n```typescript\nprovider: {\n type: \"openai\",\n baseUrl: \"https://my-custom-endpoint.example.com/v1\",\n bearerTokenProvider: async () => {\n return await acquireBearerToken();\n },\n}\n```\n\nPara obter mais detalhes sobre como adquirir e renovar tokens de portador do Microsoft Entra, consulte [Identidade gerenciada do Azure com BYOK](/pt/copilot/how-tos/copilot-sdk/setup/azure-managed-identity).\n\n## Listagem de modelo personalizado\n\nAo 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.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\nimport type { ModelInfo } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n onListModels: () => [\n {\n id: \"my-custom-model\",\n name: \"My Custom Model\",\n capabilities: {\n supports: { vision: false, reasoningEffort: false },\n limits: { max_context_window_tokens: 128000 },\n },\n },\n ],\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient\nfrom copilot.client import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits\n\nclient = CopilotClient(\n on_list_models=lambda: [\n ModelInfo(\n id=\"my-custom-model\",\n name=\"My Custom Model\",\n capabilities=ModelCapabilities(\n supports=ModelSupports(vision=False, reasoning_effort=False),\n limits=ModelLimits(max_context_window_tokens=128000),\n ),\n )\n ],\n)\n```\n\n
\n\n
Go
\n\n```golang\npackage main\n\nimport (\n \"context\"\n copilot \"github.com/github/copilot-sdk/go\"\n)\n\nfunc main() {\n client := copilot.NewClient(&copilot.ClientOptions{\n OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) {\n return []copilot.ModelInfo{\n {\n ID: \"my-custom-model\",\n Name: \"My Custom Model\",\n Capabilities: copilot.ModelCapabilities{\n Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false},\n Limits: copilot.ModelLimits{MaxContextWindowTokens: copilot.Int(128000)},\n },\n },\n }, nil\n },\n })\n _ = client\n}\n```\n\n
\n\n
.NET
\n\n```csharp\nusing GitHub.Copilot;\n\nvar client = new CopilotClient(new CopilotClientOptions\n{\n OnListModels = (ct) => Task.FromResult>(new List\n {\n new()\n {\n Id = \"my-custom-model\",\n Name = \"My Custom Model\",\n Capabilities = new ModelCapabilities\n {\n Supports = new ModelSupports { Vision = false, ReasoningEffort = false },\n Limits = new ModelLimits { MaxContextWindowTokens = 128000 }\n }\n }\n })\n});\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\nimport java.util.concurrent.CompletableFuture;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n .setOnListModels(() -> CompletableFuture.completedFuture(List.of(\n new ModelInfo()\n .setId(\"my-custom-model\")\n .setName(\"My Custom Model\")\n .setCapabilities(new ModelCapabilities()\n .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))\n .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))\n )))\n);\n```\n\n
\n\n
\n\nOs 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.\n\n## Limitações\n\n### Limitações de funcionalidades\n\nAlguns recursos de Copilot podem se comportar de forma diferente com BYOK:\n\n* **Disponibilidade do modelo** – somente os modelos compatíveis com seu provedor estão disponíveis\n* **Limitação de taxa** - Sujeito aos limites de taxa do seu provedor, não aos do Copilot\n* **Usage tracking** - O uso é acompanhado pelo seu provedor, não GitHub Copilot\n* **Solicitações premium** - Não são contabilizadas nas cotas de solicitações premium do Copilot\n\n### Limitações específicas do provedor\n\n| Fornecedor | Limitações |\n| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| [Microsoft Foundry Local](https://foundrylocal.ai) | Somente local; A disponibilidade do modelo depende do hardware do dispositivo; nenhuma chave de API necessária |\n| Ollama | Nenhuma chave de API; somente local; O suporte ao modelo varia |\n| OpenAI | Sujeito a limites de taxa e cotas do OpenAI |\n\n## Troubleshooting\n\n### Erro \"Modelo não especificado\"\n\nAo usar BYOK, o `model` parâmetro é **necessário**:\n\n```typescript\n// ❌ Error: Model required with custom provider\nconst session = await client.createSession({\n provider: { type: \"openai\", baseUrl: \"...\" },\n});\n\n// ✅ Correct: Model specified\nconst session = await client.createSession({\n model: \"gpt-4\", // Required!\n provider: { type: \"openai\", baseUrl: \"...\" },\n});\n```\n\n### Confusão quanto ao tipo de ponto de extremidade no Azure\n\nPara pontos de extremidade do OpenAI do Azure (`*.openai.azure.com`), use o tipo correto:\n\n```typescript\n// ❌ Wrong: Using \"openai\" type with native Azure endpoint\nprovider: {\n type: \"openai\", // This won't work correctly\n baseUrl: \"https://my-resource.openai.azure.com\",\n}\n\n// ✅ Correct: Using \"azure\" type\nprovider: {\n type: \"azure\",\n baseUrl: \"https://my-resource.openai.azure.com\",\n}\n```\n\nNo entanto, se a implantação do Microsoft Foundry fornecer um caminho de ponto de extremidade compatível com OpenAI (por exemplo, `/openai/v1/`), use `type: \"openai\"`:\n\n```typescript\n// ✅ Correct: OpenAI-compatible Microsoft Foundry endpoint\nprovider: {\n type: \"openai\",\n baseUrl: \"https://your-resource.openai.azure.com/openai/v1/\",\n}\n```\n\n### Conexão recusada (Ollama)\n\nVerifique se o Ollama está em execução e acessível:\n\n```bash\n# Check Ollama is running\ncurl http://localhost:11434/v1/models\n\n# Start Ollama if not running\nollama serve\n```\n\n### Conexão recusada (Foundry Local)\n\nO Foundry Local usa uma porta dinâmica que pode mudar entre reinicializações. Confirme a porta ativa:\n\n```bash\n# Check the service status and port\nfoundry service status\n```\n\nAtualize-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:\n\n```bash\nfoundry model run phi-4-mini\n```\n\n### Falha na autenticação\n\n1. Verifique se a chave de API está correta e não expirou\n2. Verifique se o `baseUrl` corresponde ao formato esperado pelo seu provedor\n3. Para tokens de portador, verifique se o token completo é fornecido (não apenas um prefixo)\n\n## Próximas Etapas \n\n* [Autenticação](/pt/copilot/how-tos/copilot-sdk/auth) – Saiba mais sobre todos os métodos de autenticação\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started) - Crie seu primeiro aplicativo com tecnologia do Copilot"}