[github-actions]

[agentgateway/agentgateway#4050, #4072, #4080](agentgateway/agentgateway#4050, agentgateway/agentgateway#4072, agentgateway/agentgateway#4080) — llm: account for Anthropic usage iterations

Docs versions: standalone/main, kubernetes/main

No code-path rule covers 3 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/parse/websocket.rs
• crates/llm/src/lib.rs
• crates/llm/src/types/detect.rs

What changes for users: Anthropic Messages responses can include usage.iterations when Anthropic runs more than one sampling iteration for one request. Agentgateway now preserves that array, sums the iteration entries for normalized usage, telemetry, costs, and converted Chat Completions responses, and prices an iteration by its own model when that model has an exact catalog match. The deprecated AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS override is removed, so Messages requests prefer Responses when a provider supports both Responses and Chat Completions.

What the docs now say: The Anthropic provider, standalone Messages API-type page, Kubernetes custom-provider page, and both mode-specific Model costs pages now state how usage.iterations affects client responses, normalized usage, and model-cost calculations. The Bedrock and Messages preference candidates were checked, but the main-tree pages already describe the final fixed Responses preference without the removed override.

Not verified: No cluster or proxy was run; the documented behavior is unrun.

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

• Code PR: llm: account for Anthropic usage iterations agentgateway#4050, Drop deprecated AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS agentgateway#4072, llm: revert Bedrock changes and drop messages preference env agentgateway#4080
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main
• Category: cluster c12: new-feature (#4050, #4072) and scoped-edit (#4080) / pr

Plan, and what changed it

• Planned: Document Anthropic usage.iterations accounting and the Messages preference env-var removal on the LLM usage, cost, and provider-format pages.
• Learned: #4080 reverts the unintended Bedrock native-Runtime changes from #4072, and the main-tree Messages/custom-provider pages already state the final fixed Responses preference.
• Did: Documented usage.iterations on the Anthropic provider, Messages conversion, custom provider, and Model costs pages; wrote no Bedrock behavior edit.

Why a documentation change is necessary

The #4050 dossier adds the usage.iterations field to Anthropic usage parsing and shows tests where top-level usage reports only the final message iteration. The same diff sums every iteration for normalized token counts, keeps the per-iteration array in Messages responses, and prices each iteration separately when a model cost catalog contains a matching model. The existing pages described Anthropic cache-token conventions and model cost fields, but did not say that multi-iteration Anthropic usage replaces the top-level totals for accounting. The #4080 dossier removes AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS; the current main docs already say the Responses preference is fixed, so no page needed that part.

What changed on disk

• assets/agw-docs/pages/agentgateway/llm/providers/anthropic.md — Adds a main-only note that usage.iterations is preserved and summed for telemetry, costs, and converted Chat Completions responses.
• assets/agw-docs/standalone/cost-catalog.md — Adds a main-only Model costs note for pricing each Anthropic iteration by its own model when the model has an exact catalog match.
• content/docs/kubernetes/main/documentation/llm/cost-controls/costs.md — Adds the same Model costs behavior for Kubernetes mode.
• content/docs/kubernetes/main/integrations/llm/providers/custom.md — Adds usage.iterations behavior to the converted replies and errors list.
• content/docs/standalone/main/documentation/llm/api-types/messages.md — Adds usage.iterations behavior to the Messages conversion list.

How to verify this change

1. Configure an Anthropic provider and send a /v1/messages request that returns an Anthropic response with usage.iterations.
2. Check the Messages response body. jq '.usage.iterations' shows the per-iteration array, and the normalized telemetry uses the sum of the entries.
3. Send the same upstream response through a /v1/chat/completions route. jq '.usage.prompt_tokens, .usage.completion_tokens' shows counts from the summed iterations, including cache tokens.
4. Configure a model cost catalog with entries for the response model and for any usage.iterations[].model value, then check the access log or cost fields. The request cost is the sum of the iteration costs, with exact per-iteration model matches priced from their own catalog entries.

What was not verified

No cluster, local proxy, or Anthropic upstream was run; the configuration and requests are unrun.
No live response with usage.iterations was generated.
Release note placement was not run.

How the pages were chosen (triage report)

Feature clusters

These pull requests document one feature between them:

Cluster	Pull requests	Product	Why grouped
c12	agentgateway/agentgateway#4050, agentgateway/agentgateway#4072, agentgateway/agentgateway#4080	agentgateway	the same author merged both within 24 hours, they change the same source file, and both are drafted into assets/agw-docs/pages/agentgateway/llm/providers/bedrock.md, so this looks like one change split across pull requests and separate drafts would conflict

Draft a documentation change

agentgateway/agentgateway#4080 — llm: revert Bedrock changes and drop messages preference env

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Revert the unintended Bedrock changes from f2259ff642 while removing the deprecated AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS behavior that PR intended to do (2 commits got swapped)
• Not tested: no cluster was available, so every command in this diff is unrun

New configuration: no page mentions it yet

agentgateway/agentgateway#4050 — llm: account for Anthropic usage iterations

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): When Anthropic runs more than one sampling iteration for a single request (for example, server-side compaction), the response's top-level usage only covers the final message iteration. Every iteration, including compaction, is reported separately in usage.iterations, and the billed total is the sum of those entries:
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 3 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/parse/websocket.rs
  • crates/llm/src/lib.rs
  • crates/llm/src/types/detect.rs

agentgateway/agentgateway#4072 — Drop deprecated AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (the title; the body has no description): Drop deprecated AGENTGATEWAY_MESSAGES_PREFER_COMPLETIONS
• Not tested: no cluster was available, so every command in this diff is unrun

A surface this change does not reach

them again: they describe a field on a deployment mode the code change
never reached, so a reader following them would configure something that
does not exist yet. The rest of the draft is untouched.

• content/docs/kubernetes/main/documentation/llm/cost-controls/costs.md
• content/docs/kubernetes/main/integrations/llm/providers/custom.md

Either the control-plane work for that mode is still owed, or the topic
belongs only to the other mode. The run summary names which surface and
which identifiers.

Release notes

This pull request also adds its release-note entries:

• content/docs/standalone/main/release-notes/release-notes.md: llm: account for Anthropic usage iterations (fix, under LLM)

Release notes kept out of a tree. Check that each change really does not reach the trees named here:

• llm: account for Anthropic usage iterations agentgateway#4050: not placed for kubernetes/main, because the draft edited no page there. If the change also reaches that tree, add the note there.

Draft branch: pr-tracker-draft-agentgateway-4050-plus2

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	a7ca0a5
Status:	✅  Deploy successful!
Preview URL:	https://5538ac11.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-0ynu.agentproxy.pages.dev

View logs