{"meta":{"title":"BYOK (traiga su propia clave)","intro":"BYOK te permite usar el SDK de Copilot con tus propias claves API de proveedores de modelos, sin pasar por la autenticación de GitHub Copilot. Esto es útil para las implementaciones empresariales, el hospedaje de modelos personalizados o cuando quiera facturar directamente con el proveedor de modelos.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/copilot","title":"GitHub Copilot"},{"href":"/es/copilot/how-tos","title":"Procedimientos"},{"href":"/es/copilot/how-tos/copilot-sdk","title":"SDK de Copilot"},{"href":"/es/copilot/how-tos/copilot-sdk/auth","title":"Autenticación"},{"href":"/es/copilot/how-tos/copilot-sdk/auth/byok","title":"BYOK (Bring Your Own Key - Trae Tu Propia Clave)"}],"documentType":"article"},"body":"# BYOK (traiga su propia clave)\n\nBYOK te permite usar el SDK de Copilot con tus propias claves API de proveedores de modelos, sin pasar por la autenticación de GitHub Copilot. Esto es útil para las implementaciones empresariales, el hospedaje de modelos personalizados o cuando quiera facturar directamente con el proveedor de modelos.\n\n\n\n\n\n## Proveedores compatibles\n\n| Provider | Tipo de valor | Notas |\n| ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| OpenAI | `\"openai\"` | Api de OpenAI y puntos de conexión compatibles con OpenAI |\n| Microsoft Foundry/Azure OpenAI | | |\n| `\"openai\"` o `\"azure\"` | Use `\"openai\"` para `\"azure\"`; use `/openai/v1/` para puntos de conexión nativos de Azure | |\n| Anthropic | `\"anthropic\"` | Modelos de Claude |\n| Ollama | `\"openai\"` | Modelos locales a través de la API compatible con OpenAI |\n| Microsoft Foundry local | `\"openai\"` | Ejecución de modelos de IA localmente en el dispositivo a través de la API compatible con OpenAI |\n| Otros compatibles con OpenAI | `\"openai\"` | vLLM, LiteLLM, etc. |\n\n## Inicio rápido: Microsoft Foundry\n\nMicrosoft Foundry es un destino de implementación BYOK común para empresas. Este es un ejemplo 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## Referencia de configuración del proveedor\n\n### Campos ProviderConfig\n\n| Campo | Tipo | Description |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | | |\n| `\"openai\"` | | |\n| \\| | | |\n| `\"azure\"` | | |\n| \\| | | |\n| `\"anthropic\"` | | |\n| Tipo de proveedor (valor predeterminado: `\"openai\"`) | | |\n| `baseUrl` / `base_url` | string | |\n| **Obligatorio.** Dirección URL del punto de conexión de API | | |\n| `apiKey` / `api_key` | string | Clave de API (opcional para proveedores locales como Ollama) |\n| `bearerToken` / `bearer_token` | string | Autenticación de token de portador (tiene prioridad sobre apiKey) |\n| `bearerTokenProvider` / `bearer_token_provider` | callback | Devuelve un token de portador a petición (tiene prioridad sobre `apiKey` y `bearerToken`) |\n| `wireApi` / `wire_api` | | |\n| `\"completions\"` | | |\n| \\| | | |\n| `\"responses\"` | | |\n| Seleccione `\"completions\"` para una amplia compatibilidad de modelos (la API de finalizaciones de chat); seleccione `\"responses\"` para la administración del estado en varios turnos, el espacio de nombres de las herramientas y la compatibilidad con razonamiento (la API de respuestas). Anthropic modelos siempre usan la API Messages independientemente de esta configuración. | | |\n| `azure.apiVersion` / `azure.api_version` | string | Versión de la API de Azure. Cuando se establece, el entorno de ejecución usa la ruta de implementación con versión; cuando se omite, usa la ruta `v1` sin versión de disponibilidad general. |\n\n### Formato de WIRE API\n\nLa `wireApi` configuración determina qué formato de API de OpenAI se va a usar:\n\n* **`\"completions\"`** (valor predeterminado): API de finalizaciones de chat (`/chat/completions`) para una amplia compatibilidad del modelo.\n* **`\"responses\"`** - API de respuestas para la administración del estado en varios turnos, los espacios de nombres para herramientas y el soporte para razonamiento.\n\nAnthropic modelos usan siempre la API de mensajes de Anthropic independientemente de esta configuración.\n\n### Notas específicas del tipo\n\n**OpenAI (`type: \"openai\"`)**\n\n* Funciona con la API de OpenAI y cualquier punto de conexión compatible con OpenAI\n* `baseUrl` debe incluir la ruta de acceso completa (por ejemplo, `https://api.openai.com/v1`)\n\n**Azure (`type: \"azure\"`)**\n\n* Usar para puntos de conexión nativos de Azure OpenAI\n* `baseUrl` debe ser solo el host (por ejemplo, `https://my-resource.openai.azure.com`)\n* No incluir `/openai/v1` en la dirección URL: el SDK controla la construcción de la ruta de acceso.\n\n**Antrópica (`type: \"anthropic\"`)**\n\n* Para el acceso directo a la API de Anthropic\n* Usa el formato de API específico de Claude\n\n## Configuraciones de ejemplo\n\n### OpenAI canal directo\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 (punto de conexión nativo de Azure)\n\nUse `type: \"azure\"` para puntos de conexión en `*.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 (punto de conexión compatible con OpenAI)\n\nPara las implementaciones de Microsoft Foundry con puntos de conexión `/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 ejecutar modelos de INTELIGENCIA ARTIFICIAL localmente en su propio dispositivo con una API compatible con OpenAI. Instálelo a través de la CLI local de Foundry y, a continuación, apunte el SDK en el punto de conexión 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 se inicia en un **puerto dinámico**; el puerto no es fijo. Use `foundry service status` para confirmar el puerto en el que el servicio está escuchando actualmente y, a continuación, use ese puerto en `baseUrl`.\n\nPara empezar a trabajar con 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### Autenticación por token de portador\n\nAlgunos proveedores requieren autenticación de token de portador en lugar de claves de API. Proporcione un token estático con `bearerToken` o un `bearerTokenProvider` callback que el tiempo de ejecución del SDK de GitHub Copilot invoque antes de las solicitudes salientes al proveedor. El callback o la biblioteca de identidades que este envuelve administra el almacenamiento en caché y la actualización de los tokens.\n\nUse `bearerToken` cuando la aplicación ya tenga un 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> La `bearerToken` opción solo acepta una **cadena de token estática** . El SDK no actualiza este token automáticamente. Si el token expira, se producirá un error en las solicitudes y deberá crear una nueva sesión con un token nuevo.\n\nUtilice `bearerTokenProvider` para obtener tokens bajo 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 obtener más información sobre cómo adquirir y actualizar tokens de portador de Microsoft Entra, consulte [Identidad administrada de Azure con BYOK](/es/copilot/how-tos/copilot-sdk/setup/azure-managed-identity).\n\n## Lista de modelos personalizados\n\nAl usar BYOK, es posible que el servidor de la CLI no sepa qué modelos admite el proveedor. Puede proporcionar un controlador personalizado `onListModels` en el nivel de cliente para que `client.listModels()` devuelva los modelos del proveedor en el formato estándar `ModelInfo` . Esto permite a los consumidores de nivel inferior detectar modelos disponibles sin consultar la 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\nLos resultados se almacenan en caché después de la primera llamada, al igual que el comportamiento predeterminado. El controlador reemplaza completamente la RPC de `models.list` la CLI; no ocurre ningún mecanismo de respaldo al servidor.\n\n## Limitaciones\n\n### Limitaciones de características\n\nAlgunas características de Copilot pueden comportarse de forma diferente con BYOK:\n\n* **Disponibilidad del modelo** : solo están disponibles los modelos admitidos por el proveedor.\n* **Limitación de tasa** - Sujeto a los límites de tasa de tu proveedor, no a los de Copilot\n* **Usage tracking**: el proveedor realiza un seguimiento del uso, no GitHub Copilot\n* **Solicitudes premium** - No cuentan para las cuotas de solicitudes premium de Copilot\n\n### Limitaciones específicas del proveedor\n\n| Provider | Limitaciones |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| [Microsoft Foundry Local](https://foundrylocal.ai) | Solo local; la disponibilidad del modelo depende del hardware del dispositivo; no se requiere ninguna clave de API |\n| Ollama | Sin clave de API; solo local; La compatibilidad del modelo varía |\n| OpenAI | Sujeto a límites y cuotas de tasa de OpenAI |\n\n## Solución de problemas\n\n### Error \"No se ha especificado el modelo\"\n\nCuando se usa BYOK, se `model` el \\*\\*\\*\\* parámetro :\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### Confusión del tipo de punto de conexión de Azure\n\nPara los puntos de conexión de Azure OpenAI (`*.openai.azure.com`), use el tipo correcto:\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\nSin embargo, si la implementación de Microsoft Foundry proporciona una ruta de acceso de un punto de conexión compatible con OpenAI (por ejemplo, `/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### Conexión rechazada (Ollama)\n\nAsegúrese de que Ollama está en ejecución y accesible:\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### Conexión rechazada (Fundición Local)\n\nFoundry Local usa un puerto dinámico que puede cambiar entre reinicios. Confirme el puerto activo:\n\n```bash\n# Check the service status and port\nfoundry service status\n```\n\nActualiza tu `baseUrl` para que coincida con el puerto que se muestra en la salida. Si el servicio no se está ejecutando, inicie un modelo para iniciarlo:\n\n```bash\nfoundry model run phi-4-mini\n```\n\n### Error de autenticación\n\n1. Compruebe que la clave de API es correcta y no ha expirado\n2. Compruebe que coincide con el `baseUrl` formato esperado del proveedor\n3. Para los tokens de portador, asegúrese de que se proporciona el token completo (no solo un prefijo).\n\n## Pasos siguientes\n\n* [Autenticación](/es/copilot/how-tos/copilot-sdk/auth) : obtenga información sobre todos los métodos de autenticación.\n* [Crea tu primera aplicación con tecnología Copilot](/es/copilot/how-tos/copilot-sdk/getting-started): compile la primera aplicación con tecnología de Copilot"}