Skip to content

Docs: Provider connections page + cross-links (preview, local-only) (#15492) - #717

Open
juanmichelini wants to merge 7 commits into
mainfrom
docs/provider-connections
Open

Docs: Provider connections page + cross-links (preview, local-only) (#15492)#717
juanmichelini wants to merge 7 commits into
mainfrom
docs/provider-connections

Conversation

@juanmichelini

@juanmichelini juanmichelini commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Docs: Provider connections (Agent Canvas)

Documents the Provider connections feature: save one API key (and optional base URL) once as a named connection, then link multiple LLM profiles to it so they share the key. Available on local agent-server backends only for now. Tracks OpenHands/OpenHands#15492.

Refreshed to match what actually shipped. An earlier revision of this PR described a provider-first UI that was never built (a dedicated "Model providers" page, a provider preset picker, wire-API selection, custom headers, nested per-provider models, a Test probe, and managed GitHub Copilot). The page and cross-links now describe the feature as it shipped in the merged PRs below.

Contents

  • New page openhands/usage/agent-canvas/provider-connections.mdx (renamed from model-providers.mdx to match the shipped section name):
    • Where to find it — the Provider connections section inside Settings > LLM, shown on local backends only (hidden on cloud).
    • Add a connection — the modal's four fields: Name, a free-text Provider (default custom), API key (required on create), and an optional Base URL. Key is encrypted at rest and never returned to the UI.
    • Link a profile to a connection — the Provider connection dropdown in the LLM profile form; linked profiles hide their inline key/base-URL inputs and read both from the connection. Choose None to unlink.
    • Edit / rotate key — blank key means "keep current"; every linked profile picks up the change.
    • Delete — blocked while profiles still reference it; the backend names them.
    • Provider connections vs. LLM profiles comparison and a "not in the preview" list (cloud, presets/wire-API/custom-headers, multiple keys per connection).
  • Cross-links restored to the correct location — the LLM settings page was not renamed, so llm-profiles.mdx, llm-settings.mdx, first-time-setup.mdx, and customize-and-settings.mdx again point at Settings > LLM and link to the provider-connections page.
  • docs.json nav slug updated to provider-connections.

Related PRs (shipped)

This PR was created by an AI agent (OpenHands) on behalf of the user.

@mintlify

mintlify Bot commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
all-hands-ai 🟢 Ready View Preview Aug 10, 2026, 9:27 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@juanmichelini
juanmichelini force-pushed the docs/provider-connections branch from 4982794 to b4bbb1a Compare August 10, 2026 22:50
@openhands-agent
docs: provider connections page + cross-links (preview, local-only)
101174b 
Documents the Connect-a-Provider flow from issue #15492. Scoped to stable
concepts; UI specifics marked provisional pending #16499 review.

- New page: agent-canvas/provider-connections.mdx
- Cross-links from llm-profiles, first-time-setup, customize-and-settings
- Added to docs.json nav after llm-profiles

Co-authored-by: openhands <openhands@all-hands.dev>
@juanmichelini
juanmichelini force-pushed the docs/provider-connections branch from b4bbb1a to 101174b Compare August 10, 2026 22:51
@juanmichelini juanmichelini changed the title [draft] Docs: Provider connections Docs: Connect a Provider (preview, local-only) Aug 10, 2026
@openhands-agent
docs: align disconnect copy with shipped UI (Delete + affected-profil…
f6fa992 
…e warning)

The connections section uses a Delete button with a confirm step, not a
Disconnect action, and now warns when a removed connection still has profiles
referencing its key. Update the page to match.

Co-authored-by: openhands <openhands@all-hands.dev>
@juanmichelini juanmichelini changed the title Docs: Connect a Provider (preview, local-only) Docs: Connect a Provider page + cross-links (preview, local-only) (#15492) Aug 11, 2026
@openhands-agent
docs: match Connect-a-Provider page to shipped wireframe UI
bf2297c 
- How-it-works now describes test-on-blur, the model picker (Recommended pre-selected, Select all, More from vendor), and that each selected model becomes a profile sharing the connection key.
- Section actions documented as Refresh, Rotate key, Disconnect (renamed from Delete/re-validate to match the issue wireframe labels).
- Removed bulk model selection from the not-in-preview list (now shipped); kept cloud, background refresh, and multiple-keys-per-provider.

Co-authored-by: openhands <openhands@all-hands.dev>
@juanmichelini
juanmichelini force-pushed the docs/provider-connections branch from e66bacf to 7227058 Compare August 12, 2026 21:28
@juanmichelini juanmichelini changed the title Docs: Connect a Provider page + cross-links (preview, local-only) (#15492) Docs: Model providers page + cross-links (preview, local-only) (#15492) Aug 12, 2026
@openhands-agent
Rewrite model providers docs for the provider-first flow
d66a66c 
Match the reworked provider-centric design (OpenHands/OpenHands#15492):

- Rename provider-connections.mdx -> model-providers.mdx (matches the route).
- Rewrite the page: add a provider once via the preset picker + form (display
  name, base URL, wire API, keychain-stored key, custom headers), then add /
  edit / remove the models nested under the provider — all sharing the
  provider's key, no per-model key re-entry. Document edit/rotate-key/delete and
  the optional Test probe (suggests catalog models, never mutates the curated
  list).
- Update the nav entry and cross-links to the new route.

Co-authored-by: openhands <openhands@all-hands.dev>
This was referenced Aug 14, 2026
Closed
Closed
@juanmichelini juanmichelini mentioned this pull request Aug 14, 2026
Draft
@openhands-agent
docs: align provider connections page with shipped feature
0198ed6 
The page described an unshipped provider-first UI (Model providers page,
preset picker, wire API, custom headers, nested models, Test probe, GitHub
Copilot). What shipped in software-agent-sdk#4492 + OpenHands#16616 is a
simpler 'Provider connections' section inside Settings > LLM (local backends
only): a named api_key + optional base_url that LLM profiles link to by id.

- Rename model-providers.mdx -> provider-connections.mdx and rewrite to match
  the shipped section, modal fields (name, free-text provider, key, optional
  base URL), profile linking dropdown, edit/rotate, delete-with-in-use guard,
  and encrypted-at-rest storage (not keychain).
- Revert the cross-link page rename: it's still Settings > LLM, not
  'Model providers'.
- Update docs.json nav slug.

Co-authored-by: openhands <openhands@all-hands.dev>
@juanmichelini juanmichelini changed the title Docs: Model providers page + cross-links (preview, local-only) (#15492) Docs: Provider connections page + cross-links (preview, local-only) (#15492) Aug 20, 2026
@juanmichelini

juanmichelini commented Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

Refreshed this PR to reflect what actually shipped rather than the earlier provider-first design.

What changed in the code since the first draft: the feature shipped as a Provider connections section inside Settings > LLM (local agent-server only), not a standalone "Model providers" page. A connection is just a named api_key + optional base_url; LLM profiles link to it via a Provider connection dropdown and then hide their inline key/base-URL fields.

Removed from the docs (described but never built): the "Model providers" page rename, the provider preset picker, wire-API selection, custom-headers JSON, nested per-provider model rows, the Test/catalog-suggestion probe, and managed GitHub Copilot.

Edits in this push:

  • Renamed model-providers.mdx → provider-connections.mdx and rewrote it against the shipped UI (modal fields, profile-linking dropdown, edit/rotate, delete-with-in-use guard, encrypted-at-rest storage — not OS keychain).
  • Reverted the cross-link page rename: the LLM settings page was never renamed, so the four cross-linking pages point at Settings > LLM again.
  • Updated the docs.json nav slug.
  • Fixed the "Related PRs" to the merged software-agent-sdk#4492 and OpenHands#16616.

Verified against the shipped source in both repos (provider_connection_store.py, provider-connection-modal.tsx, provider-connections-manager.tsx, and the shipped i18n strings).

This comment was posted by an AI agent (OpenHands) on behalf of the author.

@juanmichelini
juanmichelini marked this pull request as ready for review August 20, 2026 18:32
DevinVinson
DevinVinson requested changes Aug 21, 2026
View reviewed changes
Comment thread openhands/usage/agent-canvas/provider-connections.mdx
so.
- **API key** — the key issued by that provider or gateway (required when
creating a connection).
- **Base URL** — optional OpenAI-compatible endpoint, for example

@DevinVinson DevinVinson Aug 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This appears to be mandatory from testing and not optional.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@DevinVinson DevinVinson DevinVinson requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@juanmichelini @DevinVinson @openhands-agent