diff --git a/docs.json b/docs.json index 77626b63..ea88ba75 100644 --- a/docs.json +++ b/docs.json @@ -262,6 +262,7 @@ "openhands/usage/agent-canvas/setup", "openhands/usage/agent-canvas/first-time-setup", "openhands/usage/agent-canvas/llm-profiles", + "openhands/usage/agent-canvas/provider-connections", "openhands/usage/agent-canvas/conversations", "openhands/usage/agent-canvas/agent-profiles", "openhands/usage/agent-canvas/plugins", diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx index cf50faa3..17e168b3 100644 --- a/openhands/usage/agent-canvas/customize-and-settings.mdx +++ b/openhands/usage/agent-canvas/customize-and-settings.mdx @@ -56,7 +56,7 @@ The `Settings` area currently includes the following sections: | `Application` | UI-level preferences and app behavior | | `Secrets` | Stored secrets used by the active backend | -On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles. +On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles, and a **Provider connections** section for saving one API key once and sharing it across several profiles (see [Provider connections](/openhands/usage/agent-canvas/provider-connections), preview). In `Settings > Application`, the **Conversation titles** setting selects the LLM profile used to generate conversation titles. **Automatic** uses the active local LLM profile; you can choose another saved profile, like a small, cheap LLM, when you want titles generated independently from the model selected for agent work. The same page shows the installed Agent Canvas version, update availability, and a **Check for updates** button. diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx index 151a7eaf..7c56afc6 100644 --- a/openhands/usage/agent-canvas/first-time-setup.mdx +++ b/openhands/usage/agent-canvas/first-time-setup.mdx @@ -53,6 +53,13 @@ The setup screen defaults to `OpenHands` as the provider and pre-selects a recom For OpenHands Agent Profiles, this LLM setup becomes the model profile the agent uses. ACP agents such as Claude Code, Codex, and Gemini CLI use their own authentication and model configuration. + +To reuse one API key across several profiles instead of pasting it into each +one, save it once as a provider connection from `Settings > LLM`. See +[Provider connections](/openhands/usage/agent-canvas/provider-connections) +(preview, local backends). + + ## Step 4: Start From a Proven Workflow ![Agent Canvas first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest](/openhands/static/img/agent-canvas-setup-step-4.png) diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx index 7fb327c9..6b613aed 100644 --- a/openhands/usage/agent-canvas/llm-profiles.mdx +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -5,6 +5,13 @@ description: Configure models in Agent Canvas and use saved LLM profiles during Agent Canvas supports configuring your LLM provider, model, and credentials from the UI. It also supports saved **LLM profiles**, which make it easier to switch models without re-entering provider settings each time. + +To reuse a single API key across several profiles instead of pasting it into +each one, save it once as a provider connection and link your profiles to it. +See [Provider connections](/openhands/usage/agent-canvas/provider-connections) +(preview, local backends). + + LLM profiles can also generate conversation titles. In `Settings > Application > Conversation titles`, leave the selection on **Automatic** to use the active local profile, or select a saved profile dedicated to title generation. ## Configure an LLM Profile diff --git a/openhands/usage/agent-canvas/provider-connections.mdx b/openhands/usage/agent-canvas/provider-connections.mdx new file mode 100644 index 00000000..6f90f613 --- /dev/null +++ b/openhands/usage/agent-canvas/provider-connections.mdx @@ -0,0 +1,99 @@ +--- +title: Provider connections +description: Store one API key (and optional base URL) as a named provider connection, then link multiple LLM profiles to it so they share the key. +--- + + + **Preview — local backends only.** Provider connections are available on + **local agent-server backends** only; the section does not appear on cloud + backends. Cloud support is planned. UI labels and the flow may still change + (see [OpenHands/OpenHands#15492](https://github.com/OpenHands/OpenHands/issues/15492)). + + +A **provider connection** is a small, named bundle of the credential material an +LLM profile would otherwise carry inline: an **API key** and an optional **base +URL**. Instead of pasting the same key into every profile that uses a provider, +you save it once as a connection and link your profiles to it. Rotating the key +is then a single edit that every linked profile picks up on its next run. + +## Where to find it + +Open `Settings > LLM`. On a local agent-server, the **Provider connections** +section appears below the list of LLM profiles. (On cloud backends the section is +hidden.) + +## Add a connection + +1. In the **Provider connections** section, choose **Add connection**. +2. Fill in the form: + - **Name** — the display name shown on the connection row (required). + - **Provider** — a free-text provider identifier. Defaults to `custom`; set + it to something like `openai` or `anthropic` when you want the row to say + so. + - **API key** — the key issued by that provider or gateway (required when + creating a connection). + - **Base URL** — optional OpenAI-compatible endpoint, for example + `https://api.openai.com`. Leave it blank to use the provider's default. +3. Save. The connection appears as a row showing its name, provider, the number + of profiles linked to it, and an indicator of whether a key is set. + +The API key is **encrypted at rest** on the backend (the same cipher machinery +LLM profiles use) and is **never returned to the UI** — the row only reports +whether a key is set. + +## Link a profile to a connection + +Provider connections are consumed from the LLM profile form. When you create or +edit a profile on a local backend, a **Provider connection** dropdown lets you +point the profile at a saved connection: + +- When a profile is linked, its inline **API key** and **Base URL** inputs are + hidden — the profile reads both from the connection at runtime. +- Choose **None** in the dropdown to unlink the profile and go back to entering + a key and base URL directly on the profile. + +Several profiles can link to the same connection, so a set of profiles that all +use one provider share a single key. + +## Edit a connection or rotate its key + +Use the **edit** (pencil) control on a connection row to change its name, +provider, or base URL, or to rotate the key. The key field follows the same +"blank means unchanged" convention as the profile form: leave it empty to keep +the stored key, or type a new value to rotate it. Every linked profile uses the +updated connection on its next run — there is nothing to re-enter per profile. + +## Delete a connection + +Use the **delete** (trash) control on a connection row and confirm. If any LLM +profiles still reference the connection, the backend refuses the delete and names +the profiles that must be unlinked first, so a key in use is never removed out +from under a profile. + +## Provider connections vs. LLM profiles + +| | Provider connection | LLM profile | +|---|---|---| +| Holds a key | Yes — one key (and optional base URL) shared by linked profiles | Yes — inline, unless linked to a connection | +| Scope | Reusable credential referenced by id | A single, selectable model configuration | +| Purpose | Store one key once and share it | Pick the exact model for a conversation | + +Provider connections do not replace profiles — a profile still selects the exact +model for a conversation. A connection just lets several profiles share one key +instead of each storing its own. + +## Not in the preview + +The following are **not** part of this preview: + +- **Cloud backends** — the section is local-agent-server only for now. +- **Provider presets, wire-API selection, and custom headers** — the form is a + name, a free-text provider, a key, and an optional base URL. +- **Multiple keys per connection** — a connection holds a single key. + +## Related + +- [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +- [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) +- [Secrets Settings](/openhands/usage/settings/secrets-settings) diff --git a/openhands/usage/settings/llm-settings.mdx b/openhands/usage/settings/llm-settings.mdx index 409e9faf..85e3aafc 100644 --- a/openhands/usage/settings/llm-settings.mdx +++ b/openhands/usage/settings/llm-settings.mdx @@ -50,6 +50,13 @@ LLM profiles allow you to save multiple LLM configurations and switch between th This is useful when you want to use different models for different tasks—for example, a faster model for simple tasks and a more powerful model for complex reasoning. + +To reuse a single API key across several profiles instead of pasting it into +each one, save it once as a provider connection and link your profiles to it. +See [Provider connections](/openhands/usage/agent-canvas/provider-connections) +(preview, local backends). + + ### Creating an LLM Profile Profiles are automatically created when you save a configuration on the LLM settings page. To create a new profile: