From 98b5ae21988454dcfecd7f1b6445443815b439d9 Mon Sep 17 00:00:00 2001 From: vritant24 Date: Thu, 9 Jul 2026 15:03:14 -0700 Subject: [PATCH] enhance Custom Endpoint provider documentation with detailed configuration properties and usage examples --- docs/agent-customization/language-models.md | 75 ++++++++++++++++++++- 1 file changed, 73 insertions(+), 2 deletions(-) diff --git a/docs/agent-customization/language-models.md b/docs/agent-customization/language-models.md index 7df5c7954b8..f6d3ebb93eb 100644 --- a/docs/agent-customization/language-models.md +++ b/docs/agent-customization/language-models.md @@ -205,7 +205,7 @@ To add a model provider extension: > [!NOTE] > It replaces the deprecated OpenAI Compatible provider and supports additional API types. The `setting(github.copilot.chat.customOAIModels)` setting is deprecated. -The Custom Endpoint provider lets you connect any compatible API endpoint to chat in VS Code. It supports three API types, which you can select per model: Chat Completions, Responses, and Messages. +The Custom Endpoint provider lets you connect any compatible API endpoint to chat in VS Code. It supports three API types, which you can select per provider or per model: Chat Completions, Responses, and Messages. This makes it a good fit for self-hosted models, enterprise gateways, and providers that aren't available as a built-in provider. To add a model with the Custom Endpoint provider: @@ -221,7 +221,7 @@ To add a model with the Custom Endpoint provider: 1. Select the API type: **Chat Completions**, **Responses**, or **Messages**. Make sure the model supports this API type. -1. VS Code opens a `chatLanguageModels.json` file where you can configure the model details. Update the model properties and save the file. See the [Model configuration reference](#model-configuration-reference) for details on the configuration properties. +1. VS Code opens a `chatLanguageModels.json` file where you can configure the model details. Update the model properties and save the file. See the [Custom Endpoint configuration reference](#custom-endpoint-configuration-reference) for details on the configuration properties. The following example shows a Messages API configuration for an Anthropic endpoint: @@ -252,6 +252,77 @@ To add a model with the Custom Endpoint provider: > [!TIP] > If the model you added does not immediately appear in the model picker, restart VS Code. +#### Custom Endpoint configuration reference + +The Custom Endpoint provider supports all of the [common model configuration properties](#model-configuration-reference), plus additional provider-level and model-level properties described in this section. The provider-level properties are set on the provider object, and the model-level properties are set on each entry of the `models` array. When a property is set on both levels, the model-level value takes precedence. + +Provider-level properties (in addition to the [common provider properties](#model-configuration-reference)): + +| Property | Description | +|----------|-------------| +| `vendor` | Must be `customendpoint` to use the Custom Endpoint provider. | +| `apiKey` | The API key used to authenticate requests. Store the key securely by using an input variable, for example `"apiKey": "${input:myApiKey}"`, instead of committing a raw key. | +| `apiType` | _(Optional)_ Default API type for all models in the provider: `chat-completions` (default), `responses`, or `messages`. Override it per model with the model-level `apiType`. | +| `url` | _(Optional)_ Base URL used to discover models automatically. When set, VS Code queries the endpoint for the list of available models instead of using the `models` array. Omit it to configure models explicitly with the `models` array. | + +In addition to the [common model properties](#model-configuration-reference) the Custom Endpoint provider supports the following model-level properties: + +| Property | Description | +|----------|-------------| +| `apiType` | _(Optional)_ Override the API type for this model (`chat-completions`, `responses`, or `messages`). Defaults to the provider-level `apiType`, or is inferred from the `url` when neither is set. | +| `contextWindow` | _(Optional)_ The model's full context window (input + output) in tokens, for example `1000000` for a 1M-token model. When set, you can omit `maxInputTokens` and VS Code derives it as `contextWindow - maxOutputTokens`. | +| `modelOptions` | _(Optional)_ An object of request parameters sent with every request to the model, such as `temperature` and `top_p`. For example, `"modelOptions": { "temperature": 0.2 }`. | +| `requestHeaders` | _(Optional)_ An object of additional HTTP headers to include with requests to this model, for example to authenticate through a gateway or vanity domain. See [Custom authentication headers](#custom-authentication-headers). | + +##### Endpoint URL resolution + +The `url` you provide for a model is resolved based on its API type: + +* If the URL already contains an explicit API path (`/chat/completions`, `/responses`, or `/messages`), it is used as-is. +* Otherwise, VS Code appends the path for the model's API type. If the URL doesn't already end in a version segment such as `/v1`, VS Code inserts `/v1` first. For example, with the Responses API type, `https://my-host.example.com` resolves to `https://my-host.example.com/v1/responses`. + +To avoid ambiguity, provide the full endpoint URL including the API path, as shown in the examples. + +##### Custom authentication headers + +By default, the Custom Endpoint provider infers the authentication header from the API type and URL: it sends `x-api-key` for the Messages API, `api-key` for Azure OpenAI URLs, and `Authorization: Bearer ` otherwise. + +You can override the authentication header with `requestHeaders`. When you supply a well-known auth header (such as `Authorization`, `api-key`, `x-api-key`, `x-goog-api-key`, or `apikey`), VS Code does not also send the default inferred auth header, so the endpoint doesn't receive conflicting credentials. + +To keep your API key in secret storage while still using it in a custom header, use the `${apiKey}` token in the header value. VS Code replaces it with the configured `apiKey` at request time: + +```json +[ + { + "name": "Gateway", + "vendor": "customendpoint", + "apiKey": "${input:myApiKey}", + "models": [ + { + "id": "my-model", + "name": "My Model", + "url": "https://gateway.example.com/v1/chat/completions", + "toolCalling": true, + "vision": false, + "maxInputTokens": 128000, + "maxOutputTokens": 16000, + "thinking": true, + "supportsReasoningEffort": ["low", "medium", "high"], + "reasoningEffortFormat": "chat-completions", + "modelOptions": { + "temperature": 0.2, + "top_p": 0.9 + }, + "requestHeaders": { + "Authorization": "Bearer ${apiKey}", + "Ocp-Apim-Subscription-Key": "my-subscription-key" + } + } + ] + } +] +``` + ## Update model provider details To update the details of a model provider you configured previously: