[Automated] Draft docs (agentgateway): config store: reject writes validated against a stale snapshot (+4 related)

[github-actions]

[agentgateway/agentgateway#3656 plus #3866, #3919, #3923, #3929](agentgateway/agentgateway#3656, agentgateway/agentgateway#3866, agentgateway/agentgateway#3919, agentgateway/agentgateway#3923, agentgateway/agentgateway#3929) — UI configuration and filtering updates

Docs versions: standalone/main. Not planned for kubernetes/main: no page found there. Check whether the change applies in that mode too

No code-path rule covers 1 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• crates/agentgateway/src/config_store.rs

What changes for users: The UI save path is safer for editable configuration: YAML saves fall back to rewriting a validated file when an in-place update cannot preserve formatting, and database-backed saves are checked against the latest stored configuration before they are written. The Logs page can narrow Users and Groups filter values that were already discovered from stored traffic, and generated virtual API keys can be regenerated while editing a key. The source-build change in #3929 does not change published releases.

What the docs now say: The Launch the UI guide now explains YAML rewrite fallback and database save conflict protection. The access-log viewing page now says that Users and Groups filters have search boxes that narrow discovered values. The virtual keys guide now explains how to rotate a UI-generated key with Regenerate.

Not verified: No cluster or UI instance was available; the UI workflows are unrun.

How agentgateway-3656 was drafted, and what was not verified

• Code PR: config store: reject writes validated against a stale snapshot agentgateway#3656, ui: fallback if we cannot gracefully edit the yaml agentgateway#3866, feat(ui): search the values offered by the user and group filters agentgateway#3919, feat: allow to auto-gen a key on replacing agentgateway#3923, build: always include UI, just make it optional agentgateway#3929
• Code issue: Concurrent config-store writes can commit changes validated against stale state agentgateway#3974, Feature Request: Allow free-text (substring) search of request-log user and group attributes agentgateway#3176
• Product: agentgateway (upstream) -> agentgateway/website
• Docs version: standalone/main
• Category: cluster of scoped-edit items plus one new-feature item / pr
• Possibly incomplete: feat: search request logs by user and group with free text agentgateway#3916 also worked issue #3176, which feat(ui): search the values offered by the user and group filters agentgateway#3919 closes.
• Possibly incomplete: feat: search request logs by a partial user or group agentgateway#3918 also worked issue #3176, which feat(ui): search the values offered by the user and group filters agentgateway#3919 closes.

Plan, and what changed it

• Planned: Update the UI setup pages that the work-list named for UI save and management behavior.
• Learned: the code diff and the existing docs showed two more specific pages, documentation/observability/access-logs/view.md and assets/agw-docs/standalone/virtual-keys.md, already own the Logs filters and virtual key workflows.
• Did: Edited the UI launch, access-log viewing, and virtual keys pages; wrote nothing for #3929 because its body says actual releases do not change.

Why a documentation change is necessary

The UI launch page already tells readers that the UI can save configuration changes, but it did not explain the new YAML fallback or the database-backed save protection that #3656 and #3866 add. The access-log viewing page already mentions filtering logs by users, so #3919 belongs there rather than on a UI overview page. The virtual keys guide already documents creating generated keys in the UI, so #3923 belongs beside that workflow. For #3929, the dossier says release artifacts do not change, and the diff changes how source builds handle absent ui/dist assets.

What changed on disk

• assets/agw-docs/standalone/setup/ui/launch.md: Added UI save behavior for YAML rewrite fallback and database storage conflict protection.
• content/docs/standalone/main/documentation/observability/access-logs/view.md: Added the Users and Groups filter search behavior to the Logs UI steps.
• assets/agw-docs/standalone/virtual-keys.md: Added the regenerate flow for rotating a UI-generated virtual API key.

How to verify this change

1. Start standalone agentgateway with a configuration file and open the UI. Save a configuration change from the UI. The file remains valid; when the YAML cannot be updated in place, the saved file is rewritten from the validated configuration.
2. With database-backed configuration storage, open two UI sessions, edit the same stored configuration from both, and save both changes. A save is checked against the latest stored configuration before agentgateway writes it.
3. Generate access logs that include users or groups, open Logs, type in the Users or Groups filter search box, and verify that the list narrows without changing the log query until a value is selected.
4. Create a virtual API key in the UI, edit the key, click Regenerate, save, and verify that the UI shows a new agw_sk_... value to copy.

What was not verified

• The configuration was not applied to a cluster, and no UI workflow was run.
• #3929 was not documented because the pull request body says there is no change to actual releases.

How the pages were chosen (triage report)

Feature clusters

These pull requests document one feature between them:

Cluster	Pull requests	Product	Why grouped
c2	agentgateway/agentgateway#3656, agentgateway/agentgateway#3866, agentgateway/agentgateway#3906, agentgateway/agentgateway#3910, agentgateway/agentgateway#3913, agentgateway/agentgateway#3914, agentgateway/agentgateway#3919, agentgateway/agentgateway#3923, agentgateway/agentgateway#3929, agentgateway/agentgateway#3939, agentgateway/agentgateway#3943, agentgateway/agentgateway#3950, agentgateway/agentgateway#3961, agentgateway/agentgateway#3969, agentgateway/agentgateway#3979, agentgateway/agentgateway#3988, agentgateway/agentgateway#3993, agentgateway/agentgateway#3994, agentgateway/agentgateway#3997, agentgateway/agentgateway#3998, agentgateway/agentgateway#4004, agentgateway/agentgateway#4005, agentgateway/agentgateway#4008, agentgateway/agentgateway#4013, agentgateway/agentgateway#4014, agentgateway/agentgateway#4021, agentgateway/agentgateway#4022, agentgateway/agentgateway#4028	agentgateway	both are drafted into content/docs/standalone/main/documentation/llm/playground.md, the only page a code-path rule names for one of them, so separate pull requests would conflict

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• config store: reject writes validated against a stale snapshot agentgateway#3656 and fix(ui): associate Field labels with their controls agentgateway#3915 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• config store: reject writes validated against a stale snapshot agentgateway#3656 and budget: allow budgets with no refresh agentgateway#3970 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• ui: fallback if we cannot gracefully edit the yaml agentgateway#3866 and fix(ui): associate Field labels with their controls agentgateway#3915 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• ui: fallback if we cannot gracefully edit the yaml agentgateway#3866 and budget: allow budgets with no refresh agentgateway#3970 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• fix(ui): remove useKeyWithClickEvents suppressions agentgateway#3906 and fix(ui): associate Field labels with their controls agentgateway#3915 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• fix(ui): remove useKeyWithClickEvents suppressions agentgateway#3906 and budget: allow budgets with no refresh agentgateway#3970 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• fix(ui): use a button for log turn help agentgateway#3913 and fix(ui): associate Field labels with their controls agentgateway#3915 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• fix(ui): use a button for log turn help agentgateway#3913 and budget: allow budgets with no refresh agentgateway#3970 both have content/docs/standalone/main/documentation/llm/playground.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• (46 more weaker link(s) not shown; the work-list JSON is complete)

These clusters look incomplete. Each names a pull request this run never saw, so documenting the cluster as it stands may describe half a feature — the classic failure is a guide telling a reader to set a field that a later change gave a default. Read the absent pull request before drafting:

Cluster	Missing	What it is	Why it matters
c2	agentgateway/agentgateway#3916	feat: search request logs by user and group with free text (closed)	also worked issue #3176, which agentgateway/agentgateway#3919 closes
c2	agentgateway/agentgateway#3918	feat: search request logs by a partial user or group (open)	also worked issue #3176, which agentgateway/agentgateway#3919 closes

Draft a documentation change

agentgateway/agentgateway#3656 — config store: reject writes validated against a stale snapshot

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main
• Code issue: Concurrent config-store writes can commit changes validated against stale state agentgateway#3974
• Summary (the title; the body has no description): config store: reject writes validated against a stale snapshot
• Not tested: standalone configuration needs no cluster; whole config files the draft adds are validated with --validate-only after drafting, and commands are unrun
• No rule covers 1 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • crates/agentgateway/src/config_store.rs

agentgateway/agentgateway#3866 — ui: fallback if we cannot gracefully edit the yaml

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main
• Summary (the title; the body has no description): ui: fallback if we cannot gracefully edit the yaml
• Not tested: standalone configuration needs no cluster; whole config files the draft adds are validated with --validate-only after drafting, and commands are unrun

agentgateway/agentgateway#3919 — feat(ui): search the values offered by the user and group filters

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main
• Code issue: Feature Request: Allow free-text (substring) search of request-log user and group attributes agentgateway#3176
• Summary (read from the body): The Users and Groups filters list every value discovered from past traffic, which stops being usable once an instance has many users. Both popovers now have a text box that narrows that list as it is typed, ranked so an exact value is read first, then the values that start with the text, then the ones that only contain it. Values that do not match are hidden, and the "Any …" option stays in place
• Not tested: standalone configuration needs no cluster; whole config files the draft adds are validated with --validate-only after drafting, and commands are unrun

agentgateway/agentgateway#3923 — feat: allow to auto-gen a key on replacing

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main
• Not tested: standalone configuration needs no cluster; whole config files the draft adds are validated with --validate-only after drafting, and commands are unrun

New configuration: no page mentions it yet

agentgateway/agentgateway#3929 — build: always include UI, just make it optional

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main
• Summary (read from the body): Before you had to pass 'ui' feature to get it. Now that the UI is more core to the product imo we should just always include it, with ability to fail-open if its not built to ease with dev ex.
• Not tested: standalone configuration needs no cluster; whole config files the draft adds are validated with --validate-only after drafting, and commands are unrun
• No rule covers 5 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • crates/agentgateway-app/build.rs
  • crates/agentgateway-app/src/commands/run.rs
  • crates/agentgateway-app/src/lib.rs
  • crates/agentgateway/src/app.rs
  • crates/agentgateway/src/management/admin.rs

Release notes

This pull request also adds its release-note entries:

• content/docs/standalone/main/release-notes/release-notes.md: Agentgateway UI management workflows are safer to use (feature)

Draft branch: pr-tracker-draft-agentgateway-3656-plus4

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. Doc tests, link checking and the static checks are held as action_required until somebody presses Approve and run on the Checks tab. Cloudflare Pages and DCO are GitHub Apps rather than Actions, so those two do run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	47520cb
Status:	✅  Deploy successful!
Preview URL:	https://0a7f33bb.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-gytl.agentproxy.pages.dev

View logs