Agentic UI: Add Anthropic API key form to AI settings by sejas · Pull Request #4503 · Automattic/studio

sejas · 2026-08-11T11:21:07Z

Related issues

Closes STU-2246
Builds on the validation helper from Validate Anthropic API key in api-key and provider commands in Studio Code CLI #4504 (validateAnthropicApiKey), now merged.

How AI was used in this PR

AI helped to build the code and tests.

Proposed Changes

Studio's agentic UI always routes chat through the WordPress.com AI service. This PR lets users bring their own Anthropic API key instead:

The AI settings page gains a "Use your Anthropic API key" section, in both the browser UI (studio ui) and the desktop app's agentic UI. A toggle picks the provider and a field below it holds the key. The key is write-only: the renderer only ever receives a truncated preview (sk-ant-api03-6Ic...lgAA), never the key itself.
Settings live in ~/.studio/shared.json (the Desktop↔CLI shared config, next to the WordPress.com auth token), so the CLI, browser UI, and desktop stay in sync. Reads fall back to the legacy cli.json location, and a new CLI migration (apps/cli/migrations/08-move-ai-settings-to-shared.ts) moves aiProvider/anthropicApiKey over and strips them from cli.json on first run.
The key is validated and saved as you type (debounced): it is checked against Anthropic and a rejected key is not stored — the section shows why, and the field gets a matching error border. The toggle stays disabled until a key has been saved, and switching it on re-checks the key so one revoked since it was saved is caught too. Fail-open throughout: if Anthropic is unreachable (offline, outage), the key is accepted.
Clearing the field removes the key and falls back to the WordPress.com provider.
With the Anthropic provider active, the model picker only offers Anthropic models (Sonnet 5, Opus 5) — the provider can't serve other families.
Resumed conversations keep the provider they started with; only new conversations pick up the switch.
A new Tracks event, studio_setting_ai_provider_change, is emitted from the desktop settings handlers when the provider or key presence actually changes (provider, has_anthropic_api_key, surface — the key itself is never sent). Documented in docs/design-docs/analytics-tracks.md.
The shared store (packages/common/ai/settings-store.ts) tolerates unknown aiProvider values by falling back to WordPress.com instead of failing, and preserves unrelated config fields untouched.

Scope notes for reviewers:

The hosted connector reports the capability as unavailable and hides the section.
The key is stored in plaintext, matching the existing precedent for the WordPress.com OAuth token. There is no keychain integration in the repo today.
Browser-hosted studio ui writes these settings through apps/local, which has no Tracks emitter, so those changes go uncounted for now (STU-2247).
Whether a personal key should bypass the WordPress.com-login gate for agentic features (agenticRequiresAuth) is a product decision and intentionally untouched.

Testing Instructions

Browser UI

npm start, open the Agentic UI
Open Settings → AI. Below "Agentic features" there is a "Use your Anthropic API key" section: description and toggle on the top line, key field underneath. With no key saved, the toggle is disabled.
Type a made-up key (e.g. 1234). Shortly after you stop typing, "Anthropic rejected this API key. Check the key and try again." appears with a red border on the field, nothing is written to ~/.studio/shared.json, and the toggle stays disabled.
Replace it with a real key: it saves and the toggle becomes available.
Switch it on — it stays on and ~/.studio/shared.json has "aiProvider": "anthropic-api-key" plus the key. Reload the page — the field shows the truncated key as its placeholder.
Open a chat composer and check the model picker only lists Sonnet 5 and Opus 5.
Switch the toggle off: shared.json resets to "aiProvider": "wpcom" and the picker offers all models again. Clear the key field: the key is removed from shared.json.
API-level checks: PUT /api/ai-settings stores the key; PUT /api/ai-settings/provider with anthropic-api-key answers 400 when the key is rejected.

Tracks Desktop

npm start (full restart required — new main-process IPC handlers).
Switch to the agentic UI, open Settings → AI, and repeat the browser steps 2–7. The same ~/.studio/shared.json is used, so a key saved in the desktop app is also active for studio ui and the CLI.
Tracks: with STUDIO_DEBUG_TRACKS=1, changing the provider or key logs a studio_setting_ai_provider_change event carrying only provider, has_anthropic_api_key, and surface.

Migration from an earlier build

With Studio stopped, add "aiProvider": "anthropic-api-key" and an "anthropicApiKey" to ~/.studio/cli.json and remove both from ~/.studio/shared.json.
Run any CLI command (e.g. node apps/cli/dist/cli/main.mjs site list): both fields move to shared.json and disappear from cli.json. Values already present in shared.json are kept.

add-antrhopic-api-key.mp4

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

…key-settings

sejas · 2026-08-11T12:39:58Z

We can consider adding a dropdown next to the model when an API key exists, but I prefer to add and discuss that as a follow up.

wpmobilebot · 2026-08-11T13:47:03Z

📊 Performance Test Results

Comparing a5f9498 vs trunk

app-size

Metric	trunk	`a5f9498`	Diff	Change
App Size (Mac)	1406.71 MB	1406.75 MB	+0.04 MB	⚪ 0.0%

site-editor

Metric	trunk	`a5f9498`	Diff	Change
load	1058 ms	1069 ms	+11 ms	⚪ 0.0%

site-startup

Metric	trunk	`a5f9498`	Diff	Change
siteCreation	7540 ms	7541 ms	+1 ms	⚪ 0.0%
siteStartup	2868 ms	2872 ms	+4 ms	⚪ 0.0%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

bcotrim

Some initial thoughts after a first review and tests:

The app shouldn't write to cli.json. Let's either move anthropicApiKey and aiProvider to shared.json, or add getters and setters as CLI operations. I'd say shared.json is the easiest for now — it's already the layer for Desktop↔CLI state, and it's where the auth token lives.
Let's make the error layout consistent with the rest of the app. (example from the create site form)

… Code CLI (#4504) This PR validates the key at entry time, in both `/api-key` and `/provider` (both funnel through the provider's `prepare` step), and displays an error if the key is not valid. It only affects CLI. The UI is being implemented in #4503

…y-settings # Conflicts: # apps/cli/ai/providers.ts # packages/common/ai/anthropic-key.ts

sejas · 2026-08-12T15:48:03Z

Thanks for the feedback. I changed the code to save the anthropic API key in shared.json and the error style to match existing inputs.

@bcotrim , I would appreciate another review. Thanks!

change-error-color.mp4

wojtekn · 2026-08-13T09:06:27Z

@sejas could you please add a Tracks bump? I will merge #4506, and you could use studio_setting_instructions_change as an example.

bcotrim · 2026-08-13T09:08:52Z

+	};
+
+	// AI provider settings live in shared.json (they used to target cli.json).
+	if ( typeof oldData.aiProvider === 'string' ) {


I don't think we should change this migration. It's the move from the old appdata-v1.json to the split configs, so it only runs for pre-split users — it would miss every user already on `cli.json.

Let's add a new migration under apps/cli/migrations/ instead that copies aiProvider and anthropicApiKey into shared.json and then removes them from cli.json.

thanks for the suggestion!

…y-settings # Conflicts: # apps/cli/lib/cli-config/core.ts

…y-settings # Conflicts: # apps/cli/commands/ai/index.ts # apps/studio/src/modules/user-settings/lib/ipc-handlers.ts # apps/studio/src/modules/user-settings/lib/tests/settings-tracks.test.ts # apps/studio/src/preload.ts # apps/ui/src/components/settings-view/studio-code-panel.tsx # docs/design-docs/analytics-tracks.md # packages/common/lib/record-tracks-event.ts

…y-settings # Conflicts: # apps/local/src/index.ts # apps/ui/src/ui-classic/components/session-view/composer/index.tsx

…y-settings

sejas · 2026-08-13T13:51:42Z

@sejas could you please add a Tracks bump? I will merge #4506, and you could use studio_setting_instructions_change as an example.

I added the tracks event when the toggle is enabled/disabled here. b26ecb3 The UI version doesn't have any tracking yet.

tracks-event-toggle-key.mp4

sejas · 2026-08-13T13:53:34Z

@bcotrim , @wojtekn , I added tracks and added the migration for aiProvider and anthropicApiKey in the right place. 75312ff#diff-cf956473de32305a64e2d8b454483a4178cadcf7a68e6c70d1cee0795ba631e1

Could you review it again? Thx!

bcotrim

After running some more tests I noticed another behavior:

Switching the Anthropic API key on/off only affects new sessions — existing ones keep the provider they were already using. That makes sense to me, but there's no way to tell which provider a chat is on.

It's not only a missing indicator either: the model dropdown filters by the global setting rather than the session's, so an existing WordPress.com session shows only Anthropic models and hides GPT 5.6 Sol, which it can still use.

We can start with something simple, like a label next to the model dropdown, and revisit later. What do you think?

cc @shaunandrews

bcotrim

After running some more tests I noticed another behavior:

Switching the Anthropic API key on/off only affects new sessions — existing ones keep the provider they were already using. That makes sense to me, but there's no way to tell which provider a chat is on.

It's not only a missing indicator either: the model dropdown filters by the global setting rather than the session's, so an existing WordPress.com session shows only Anthropic models and hides GPT 5.6 Sol, which it can still use.

We can start with something simple, like a label next to the model dropdown, and revisit later. What do you think?

cc @shaunandrews

bcotrim

After running some more tests I noticed another behavior:

Switching the Anthropic API key on/off only affects new sessions — existing ones keep the provider they were already using. That makes sense to me, but there's no way to tell which provider a chat is on.

It's not only a missing indicator either: the model dropdown filters by the global setting rather than the session's, so an existing WordPress.com session shows only Anthropic models and hides GPT 5.6 Sol, which it can still use.

We can start with something simple, like a label next to the model dropdown, and revisit later. What do you think?

cc @shaunandrews

sejas · 2026-08-13T15:11:12Z

Thanks for pointing that out @bcotrim . Initially I wanted to keep that out of scope of this PR, but I agree that we need some visual indicator. I think we could add the dropdown for users to pick the provider if the API key is saved so they can choose per conversation, I'll create a separate PR for that.

provider-dropdown.mp4

sejas · 2026-08-13T16:01:36Z

@bcotrim , I've created this separate PR so we can decide one or the other #4534

shaunandrews · 2026-08-13T16:31:41Z

Can we move the provider to the same menu as the model picker? Something like this maybe:

shaunandrews · 2026-08-13T16:32:40Z

And then maybe adjust the display of the menu trigger when using an API key.

sejas · 2026-08-13T16:52:25Z

I'll add the provider in the same dropdown as a follow-up. Great suggestion!

feat: add Anthropic API key form to agentic UI AI settings

2f57a91

sejas self-assigned this Aug 11, 2026

sejas added 2 commits August 11, 2026 13:31

feat: support Anthropic API key settings in desktop agentic UI

3ceed62

feat: validate Anthropic API key in CLI api-key and provider commands

bd2b7e8

sejas mentioned this pull request Aug 11, 2026

Validate Anthropic API key in api-key and provider commands in Studio Code CLI #4504

Merged

1 task

sejas added 4 commits August 11, 2026 13:38

Merge branch 'validate-anthropic-api-key-cli' into add-anthropic-api-…

92af746

…key-settings

feat: validate Anthropic key on save; move input below description

94ab5f2

feat: switch Anthropic key UI to a provider toggle with autosaved key

d275ea5

feat: validate the Anthropic key before saving it in AI settings

918790b

sejas marked this pull request as ready for review August 11, 2026 12:38

sejas requested a review from bcotrim August 11, 2026 12:40

sejas added 2 commits August 11, 2026 15:16

refactor: dedupe cli.json primitives, debounce hook, error handling

4fb0064

update: clarify Anthropic billing in AI settings copy

3213240

bcotrim reviewed Aug 11, 2026

View reviewed changes

update: shorten Anthropic key description

81e3211

sejas added 3 commits August 11, 2026 22:50

refactor: move AI provider settings from cli.json to shared.json

464e3cb

Merge remote-tracking branch 'origin/trunk' into add-anthropic-api-ke…

7c2ac48

…y-settings # Conflicts: # apps/cli/ai/providers.ts # packages/common/ai/anthropic-key.ts

fix: keep provider model ids narrowed to AiModelId

859d500

sejas requested review from bcotrim, katinthehatsite and nightnei August 12, 2026 15:48

fix: show a red border on the Anthropic API key field when saving fails

bfca7df

bcotrim reviewed Aug 13, 2026

View reviewed changes

sejas added 2 commits August 13, 2026 12:57

Merge remote-tracking branch 'origin/trunk' into add-anthropic-api-ke…

8425c52

…y-settings # Conflicts: # apps/cli/lib/cli-config/core.ts

test: remove a duplicate AiPanel case and rename a misleading one

ef9b3ca

sejas added 6 commits August 13, 2026 12:57

fix: move AI settings from cli.json to shared.json in a CLI migration

75312ff

add: studio_setting_ai_provider_change Tracks event

b26ecb3

Merge remote-tracking branch 'origin/trunk' into add-anthropic-api-ke…

2fd553f

…y-settings # Conflicts: # apps/local/src/index.ts # apps/ui/src/ui-classic/components/session-view/composer/index.tsx

Merge remote-tracking branch 'origin/trunk' into add-anthropic-api-ke…

eaab3b8

…y-settings

fix: preview short Anthropic keys by tail only and tighten comments

a5f9498

sejas requested a review from bcotrim August 13, 2026 13:50

bcotrim reviewed Aug 13, 2026

View reviewed changes

sejas mentioned this pull request Aug 13, 2026

Agentic UI: Pick the AI provider per conversation #4534

Closed

1 task

bcotrim approved these changes Aug 13, 2026

View reviewed changes

sejas merged commit 9def1b2 into trunk Aug 13, 2026
15 checks passed

sejas deleted the add-anthropic-api-key-settings branch August 13, 2026 16:54

Uh oh!

Conversation

sejas commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

How AI was used in this PR

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

sejas commented Aug 11, 2026

Uh oh!

wpmobilebot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

app-size

site-editor

site-startup

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

sejas commented Aug 12, 2026

Uh oh!

wojtekn commented Aug 13, 2026

Uh oh!

bcotrim Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

sejas Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

sejas commented Aug 13, 2026

Uh oh!

sejas commented Aug 13, 2026

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

sejas commented Aug 13, 2026

Uh oh!

sejas commented Aug 13, 2026

Uh oh!

shaunandrews commented Aug 13, 2026

Uh oh!

shaunandrews commented Aug 13, 2026

Uh oh!

sejas commented Aug 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sejas commented Aug 11, 2026 •

edited

Loading

wpmobilebot commented Aug 11, 2026 •

edited

Loading