Skip to content

Your lightweight open-source personal agent.

docs: focus API configuration on user workflows

chengyongru9aff0787ff37
diff --git a/docs/configuration.md b/docs/configuration.md
index 31533d05a..bac91bd9b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -329,13 +329,9 @@ Without an API declaration, direct OpenAI calls Chat Completions normally and ro
}
```
-For OpenAI, the connection declaration is a default: explicit model presets can select any API supported by the adapter. Use only `chat_completions` and/or `responses`. Omit `api` or set it to `null` for automatic routing. A Responses-only declaration prevents Chat compatibility fallback; include both APIs to permit that fallback.
+Use only `chat_completions` and/or `responses` for OpenAI. The connection declaration sets a default; an explicit preset declaration overrides it. Omit `api` or set it to `null` for Auto. A Responses-only declaration prevents Chat fallback; include both APIs to permit it.
-`extraBody` follows the selected OpenAI API surface. With Chat Completions, nanobot passes
-ordinary fields through as the SDK `extra_body` value; list-valued `extraBody.tools` is handled
-specially and appended after generated function tools. With Responses, configure it in Responses
-API body shape; nanobot merges ordinary top-level fields into the Responses request body, appends
-`extraBody.tools` after generated function tools, and merges `extraBody.include` without duplicates:
+Use fields accepted by the selected API in `extraBody`. Set `extraBody.tools` to add provider-hosted tools alongside nanobot's function tools. Responses also accepts `extraBody.include` to request additional output fields:
```json
{
@@ -352,9 +348,7 @@ API body shape; nanobot merges ordinary top-level fields into the Responses requ
}
```
-The WebUI's OpenAI web-search switch writes a Responses-only `api` declaration and `extraBody.tools`
-fields. A hosted search tool replaces nanobot's same-name local `web_search` function for that
-request, while other tools such as `web_fetch` remain available.
+The WebUI's OpenAI web-search switch selects Responses without Chat fallback. Provider-hosted search replaces nanobot's local `web_search` for those requests; other tools such as `web_fetch` remain available.
</details>
@@ -1439,7 +1433,9 @@ Set `agents.defaults.modelPreset` to choose the preset followed by sessions that
### Custom connection APIs
-For the built-in `custom` connection or any named custom provider, declare the protocols accepted by the endpoint under `providers.<name>.api`:
+Custom providers use Chat Completions by default. If your service requires another protocol, open its WebUI connection editor and expand **Advanced options**. Use **Supported APIs** to select the protocols the service accepts and **Default API** to choose the default for Auto presets. Existing connections without a declaration retain their previous Auto behavior; use **Set supported APIs** to add one.
+
+In `config.json`, set `providers.<name>.api` for the built-in `custom` provider or a named custom provider:
```json
{
@@ -1456,27 +1452,23 @@ For the built-in `custom` connection or any named custom provider, declare the p
}
```
-`supportedApis` is a nonempty list of `chat_completions`, `responses`, and/or `anthropic_messages`. `preferredApi` must belong to that list and defaults to its first entry. A model preset using Auto inherits this default. A preset's explicit API list must be a subset of the connection's list. A connection can accept both Anthropic and OpenAI formats; automatic fallback stays within the selected API family.
-
-The WebUI custom provider creation and editing forms expose **Supported APIs** and **Default API** under **Advanced options**, collapsed by default. New connections start with Chat Completions; select the protocols your endpoint accepts. Existing connections without an `api` declaration retain their previous automatic routing. Use **Set supported APIs** to add a declaration. Removing a protocol used by an existing explicit model configuration is rejected; update the model configuration first.
+`supportedApis` must contain at least one of `chat_completions`, `responses`, or `anthropic_messages`. `preferredApi` must belong to that list and defaults to its first entry. Auto presets inherit this default; explicit presets can only use protocols in the connection's list. Before removing a protocol used by an explicit preset, update that preset first.
### Legacy OpenAI API selector migration
-`providers.openai.apiType` (or `api_type`) is accepted only as temporary input compatibility.
-`chat_completions` and `responses` convert to a single-API connection declaration; `auto`
-leaves automatic routing enabled. If `api` is also present, it wins, including `api: null`.
-Saving configuration writes only the current declaration. Runtime adapters and the WebUI
-use `api`; the OpenAI connection default remains overridable by explicit model presets.
+If your configuration uses `providers.openai.apiType` (or `api_type`), save it with a version that supports the migration before upgrading further. Saving replaces the old field with `api`: `chat_completions` or `responses` becomes a single-API declaration, while `auto` keeps automatic selection. If both fields are present, `api` takes precedence, including `api: null`.
-The conversion is supported for the first release containing this migration and the immediately
-following release. It will be removed before the third release. During this window, older clients'
-OpenAI settings mutations using `apiType` are converted at the settings input boundary as well.
-Save the configuration with a supported release to migrate it before upgrading beyond this window.
-See the [release removal checklist](./releasing.md#openai-api-selector-compatibility-window).
+The old field is accepted in the first release containing this migration and the immediately following release. The third release will require the current `api` format.
### Preset request API
-Leave API selection on **Auto** unless your provider requires a specific endpoint. For OpenAI-compatible providers and GitHub Copilot, a preset can choose Responses or Chat Completions. Custom gateways also allow Anthropic Messages. Credentials and endpoint URLs stay in the provider. Two presets sharing a provider can select different APIs.
+Leave API selection on **Auto** unless your service requires a specific protocol. To change it, open **Settings → Models → a preset → Advanced options → API connection**. Choose **Responses**, **Chat Completions**, or **Anthropic Messages** from the available options. Credentials and endpoint URLs stay in the provider; two presets sharing a provider can select different APIs.
+
+**Auto (Responses)**, for example, shows the default API for the current provider, model, and reasoning settings. Auto uses a configured connection default when present. Otherwise, custom providers use Chat Completions, built-in providers use their known model defaults, and GitHub Copilot uses available account model information. Auto does not test whether a third-party service supports an API. If no preview is available, the label shows **Auto**.
+
+Selecting Responses also offers **Try Chat Completions if Responses is unsupported**, off by default. Enable it only if the service supports the same model through both APIs. The Auto label shows the default preference; permitted Chat fallback can still change the API used for a request.
+
+To configure presets in `config.json`:
```json
{
@@ -1502,17 +1494,15 @@ Leave API selection on **Auto** unless your provider requires a specific endpoin
}
```
-`supportedApis` is a nonempty list of APIs this preset is allowed to use: `chat_completions`, `responses`, or `anthropic_messages`. `preferredApi` must belong to that list; when omitted, it defaults to the first entry. A Responses-only preset never falls back to Chat Completions. Declare both OpenAI APIs with `preferredApi: "responses"` to allow Chat fallback for classified Responses compatibility errors, when the endpoint serves that model through both APIs. Anthropic Messages must be declared alone; automatic fallback across Anthropic and OpenAI protocols is not supported. Separate fallback presets can use different protocols. Other failures retain their normal error handling. Native hosted search uses Responses when it is allowed by the preset.
-
-A custom preset declaring `anthropic_messages` uses the Anthropic adapter for message history, tools, thinking, and streaming. Its connection retains the provider's key, base URL, headers, query parameters, body additions, and explicit proxy. Anthropic requests target `/v1/messages`; a trailing `/v1` in the configured base is normalized by the adapter. Model names use the connection's existing prefix rules. Selecting this protocol does not change other presets sharing the connection.
+`supportedApis` must contain at least one of `chat_completions`, `responses`, or `anthropic_messages`. `preferredApi` must belong to that list and defaults to its first entry. Omit `api` or set it to `null` for Auto. An explicit preset declaration overrides the OpenAI connection default; for custom connections, it must stay within the connection's supported APIs.
-Omit `api` or set it to `null` for automatic routing. An explicit model declaration overrides the OpenAI connection default. Automatic Copilot routing uses the account's last successfully discovered `supported_endpoints` when available; other automatic routes use registry defaults. Custom gateways use their connection API default when declared, otherwise Chat Completions. A preset can override that default only within the connection's declared supported APIs. Protocol behavior such as reasoning replay and native compaction remains provider-owned; declaring Responses support does not enable OpenAI-native compaction on a custom gateway.
+A Responses-only preset never falls back to Chat Completions. To allow Chat fallback for Responses compatibility errors, include both `responses` and `chat_completions` with `preferredApi: "responses"`. Other errors do not trigger this API fallback. Provider-hosted search uses Responses when the preset allows it.
-In the WebUI, open **Settings → Models → a preset → Advanced options → API connection**. Advanced options is collapsed by default; opening or closing it preserves the preset's API declaration. Choose **Auto**, **Responses**, **Chat Completions**, or **Anthropic Messages**, according to the host's declared adapter support. Auto shows the default API in parentheses, such as **Auto (Responses)**, and updates when the provider, model, or reasoning setting changes while Advanced options is open. The gateway resolves this default using the same rules as model requests, without probing remote endpoints. The label describes the default preference; compatibility failures can still activate permitted Chat fallback. Hosts that do not advertise API resolution show **Auto** without a resolved label. Selecting Responses also reveals **Try Chat Completions if Responses is unsupported**, which starts off when selecting Responses and requires the same model to support both endpoints.
+Declare `anthropic_messages` alone in a preset. Requests use the same provider connection settings and go to `/v1/messages`; `apiBase` may include a trailing `/v1`. Automatic API fallback between Anthropic Messages and OpenAI formats is not supported; use separate [fallback presets](#model-fallbacks) when needed.
-Every provider adapter declares its request formats in `nanobot/providers/registry.py`. OpenAI Codex, xAI Grok subscriptions, and the Azure OpenAI adapter use Responses; Anthropic uses Messages, and Bedrock uses Converse. The WebUI shows the protocol name for these fixed connections instead of an editable selector. Preset declarations cannot enable a format the adapter does not implement. An OpenAI-compatible adapter implementing both formats does not guarantee that a particular remote model supports both.
+OpenAI Codex, xAI Grok subscriptions, and Azure OpenAI use Responses; Anthropic uses Messages, and Bedrock uses Converse. These connections show their protocol name instead of an editable selector. Selecting Responses for a custom service does not enable OpenAI-native [context compaction](#responses-state-and-compaction).
-Changing a preset's model or provider resets its API declaration to automatic unless the same update supplies a new declaration. Each fallback preset retains its own declaration. Legacy direct `agents.defaults.api` and inline fallback `api` values are preserved when converting to named presets.
+Advanced options is collapsed by default; opening or closing it preserves API settings. Changing a preset's model or provider resets its API selection to Auto unless the same update supplies a new declaration. Each fallback preset keeps its own API settings. Existing `agents.defaults.api` and inline fallback `api` values are preserved when converting to named presets.
### Model Fallbacks
diff --git a/docs/development.md b/docs/development.md
index b10779930..ab6d4f77f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -46,6 +46,14 @@ Useful `ProviderSpec` options:
| `responses` | `ResponsesCapabilities` with automatic model rules, reasoning replay, and fallback policy. |
| `is_transcription_only` | Provider has credentials but cannot serve chat completions. |
+### Request API routing
+
+`resolve_provider_route` in `nanobot/providers/routing.py` validates connection and preset declarations and selects the adapter. Built-in OpenAI connection declarations set an overridable default; custom connection declarations also limit the preset's allowed APIs.
+
+`ProviderSpec.default_model_api` resolves automatic model rules from the registry. Copilot uses the account's last successfully discovered `supported_endpoints` when available. The WebUI preview calls `resolve_automatic_model_api` without probing endpoints or consulting circuit-breaker state; it reports a preference, not a guarantee of remote support.
+
+Custom presets selecting `anthropic_messages` use the Anthropic adapter for history, tools, thinking, and streaming. They retain the connection's credentials, base URL, headers, query parameters, body additions, proxy, and model-prefix rules. Reasoning replay and native compaction remain provider-owned; a Responses declaration alone does not enable OpenAI-native compaction on a custom gateway.
+
### Python API migration
Provider integrations must supply `ProviderSpec.request_apis`. Replace the former `responses_models` argument with `responses=ResponsesCapabilities(models=(...))`. Use `models` for rules shared by an endpoint and its proxies. For a rule tied to a specific endpoint, use `endpoint_models`:
diff --git a/docs/guides/configure-openai-compatible-provider.md b/docs/guides/configure-openai-compatible-provider.md
index e735378c2..f0a11cd2c 100644
--- a/docs/guides/configure-openai-compatible-provider.md
+++ b/docs/guides/configure-openai-compatible-provider.md
@@ -69,9 +69,8 @@ nanobot agent -m "Hello!"
- Use separate provider names for separate endpoints.
- Use a placeholder key such as `EMPTY` only when the endpoint requires a
non-empty key but does not validate it.
-- Declare the endpoint's supported protocols and default with [`providers.<name>.api`](../configuration.md#custom-connection-apis), or use Supported APIs and Default API in the WebUI connection editor. Auto model presets inherit this default.
-- For models requiring Responses, declare `api.supportedApis: ["responses"]` in their [model preset](../configuration.md#preset-request-api), or select Responses in the WebUI preset editor.
-- Custom gateways serving Anthropic Messages can use `api.supportedApis: ["anthropic_messages"]` in the preset, or select Anthropic Messages in the editor. This uses `/v1/messages` with the same provider connection.
+- Leave the preset's API selection on Auto for ordinary Chat Completions services.
+- If the service requires Responses or Anthropic Messages, set its supported APIs and default in the connection's **Advanced options**. To choose an API for an individual model, use **Settings → Models → a preset → Advanced options → API connection**. See [connection settings](../configuration.md#custom-connection-apis) and [preset settings](../configuration.md#preset-request-api) for JSON examples.
## Security notes
diff --git a/docs/provider-cookbook.md b/docs/provider-cookbook.md
index 1940e8238..909bde074 100644
--- a/docs/provider-cookbook.md
+++ b/docs/provider-cookbook.md
@@ -200,7 +200,7 @@ Verify:
OPENAI_API_KEY="sk-..." nanobot agent -m "Hello!"
```
-If your shell cannot use inline environment variables, set `OPENAI_API_KEY` first and then run `nanobot agent -m "Hello!"`. Use `providers.openai.api` for the connection default or a [preset API declaration](./configuration.md#preset-request-api) for an individual model. Existing `apiType` inputs follow the [two-release migration window](./configuration.md#legacy-openai-api-selector-migration).
+If your shell cannot use inline environment variables, set `OPENAI_API_KEY` first and then run `nanobot agent -m "Hello!"`. Leave API selection on Auto unless you need a specific API in the preset's **Advanced options**; see [preset API settings](./configuration.md#preset-request-api). If your configuration still uses `apiType`, follow the [migration instructions](./configuration.md#legacy-openai-api-selector-migration).
## Recipe: Anthropic Direct
diff --git a/docs/providers.md b/docs/providers.md
index 26ebc433d..62ff6c20c 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -84,7 +84,7 @@ These fields answer different questions:
You usually omit `apiBase` for hosted built-in providers such as OpenRouter, Anthropic direct, OpenAI direct, Groq, or Bedrock because nanobot knows their default endpoints. Set `apiBase` for `custom`, local OpenAI-compatible servers, provider proxies, regional endpoints, or subscription endpoints. Include the API version path when the endpoint requires it, for example `https://api.example.com/v1` or `http://localhost:11434/v1`.
-Use `proxy` when one provider must send HTTP traffic through a proxy without changing process-wide `HTTP_PROXY` / `HTTPS_PROXY`. This is supported for providers that use nanobot's OpenAI-compatible client, including `openai`, `custom`, named custom providers, OpenRouter-style gateways, local OpenAI-compatible servers, and similar registry entries. It is also supported for Anthropic Messages, `openai_codex`, and `xai_grok`, including OAuth token exchange/refresh and model requests. Native `bedrock`, `azure_openai`, and `github_copilot` backends reject `proxy`; use their endpoint-specific configuration instead.
+Use `proxy` when one provider must send HTTP traffic through a proxy without changing process-wide `HTTP_PROXY` / `HTTPS_PROXY`. Supported providers include `openai`, `custom`, named custom providers, OpenRouter-style gateways, local OpenAI-compatible servers, Anthropic Messages, `openai_codex`, and `xai_grok`. For OAuth providers, this also covers exchanging and refreshing tokens. `bedrock`, `azure_openai`, and `github_copilot` reject `proxy`; use their endpoint-specific configuration instead.
## Inline Image Requests
@@ -326,7 +326,7 @@ If you use an Anthropic-compatible proxy, keep the provider as `anthropic` and o
}
```
-Named custom providers can also serve Anthropic Messages: declare `providers.<name>.api.supportedApis: ["anthropic_messages"]`. Auto presets then use the Anthropic adapter with that connection's credentials and endpoint.
+For a named custom provider serving Anthropic Messages, set `providers.<name>.api.supportedApis` to `["anthropic_messages"]`. Auto presets then use Messages with that connection's credentials and endpoint.
### OpenAI Direct
@@ -353,7 +353,9 @@ Named custom providers can also serve Anthropic Messages: declare `providers.<na
}
```
-Use [preset API declarations](./configuration.md#preset-request-api) to choose Chat Completions or Responses for each model and endpoint. Set `providers.openai.api` for the connection default; explicit presets override it. The old `apiType` input is converted during the [two-release compatibility window](./configuration.md#legacy-openai-api-selector-migration). Replace the model with a model ID available to your account. Direct OpenAI Responses, OpenAI Codex, Azure OpenAI Responses, and eligible GitHub Copilot models share [opaque Responses state retention](./configuration.md#responses-state-and-compaction); native compaction is enabled only where the backend supports it. The WebUI exposes provider-native switches for OpenAI web search, Codex Fast mode, DeepSeek web search, and Grok X Search. These switches write the corresponding raw provider request fields under `extraBody`.
+Replace the model with a model ID available to your account. Leave API selection on Auto unless you need to choose Chat Completions or Responses in the preset's **Advanced options**. See [preset API settings](./configuration.md#preset-request-api) for WebUI and JSON configuration. `providers.openai.api` sets the connection default; explicit presets override it. If your configuration still uses `apiType`, follow the [migration instructions](./configuration.md#legacy-openai-api-selector-migration).
+
+Direct OpenAI Responses, OpenAI Codex, Azure OpenAI Responses, and eligible GitHub Copilot models can retain server-provided conversation state; [native context compaction](./configuration.md#responses-state-and-compaction) depends on provider support. The WebUI offers switches for OpenAI web search, Codex Fast mode, DeepSeek web search, and Grok X Search.
DeepSeek's `deepseek-v4-flash`, `deepseek-v4-pro`, and `deepseek-v4-flash-vision-exp` automatically use its native Responses API. Its native `web_search` tool is enabled by default and shows its lifecycle in WebUI chat activity; set `providers.deepseek.extraBody.tools` to `[]` to disable it. OpenCode Go's `muse-spark-1.2-contributor` and `muse-spark-1.3-contributor` also use Responses by default.
@@ -428,8 +430,6 @@ Custom provider keys define direct connections. Without an API declaration, they
If your custom endpoint documents a nonstandard thinking toggle, set `providers.<name>.thinkingStyle` to `thinking_type`, `enable_thinking`, or `reasoning_split`; nanobot then maps `reasoningEffort` onto that provider-specific request body. Leave it unset for ordinary OpenAI-compatible endpoints.
-Set `providers.<name>.api` to declare the connection's accepted protocols and default protocol. It accepts `chat_completions`, `responses`, and `anthropic_messages`; see [custom connection APIs](configuration.md#custom-connection-apis).
-
### ModelScope
ModelScope (魔搭社区) exposes an OpenAI-compatible LLM endpoint plus a separate async image generation API. Both are covered by the built-in `modelscope` provider.