[Automated] Draft docs (agentgateway): fix(llm): translate context overflow errors for Claude Code recovery

[github-actions]

agentgateway/agentgateway#3581 — fix(llm): translate context overflow errors for Claude Code recovery

Docs versions: standalone/main, kubernetes/main

What changes for users: Messages clients that route through a Completions or Responses provider now receive capability_rejected: prompt_too_long on confirmed HTTP 400 context-overflow errors. Claude Code can use that marker to compact and retry. The original upstream message follows the marker, and unrelated codes, other statuses, and existing capability markers keep their current handling.

What the docs now say: The standalone Messages API type page plus the standalone and Kubernetes custom providers pages now describe the context-overflow marker, why Claude Code uses it, and the boundaries for when the marker is not added.

Not verified: No cluster or live gateway was reached in this sandbox; the documented behavior is unrun.

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

• Code PR: fix(llm): translate context overflow errors for Claude Code recovery agentgateway#3581
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main; documented in the development tree, which is where unreleased changes go.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the context-overflow recovery marker on the pages that already describe Messages conversions to Completions and Responses.
• Learned: the code diff and the target pages showed that the standalone Messages API type page owns the mode-level conversion behavior, and the custom provider pages in both modes are the provider-focused destination; cluster-facts.md is API surface only, not a test result.
• Did: Updated the relevant mode-specific main pages and wrote a proposed release note.

Why a documentation change is necessary

The pull request changes runtime error translation for Messages clients that reach OpenAI Chat Completions or OpenAI Responses providers. The existing pages described conversion order and conversion limits, but did not say that confirmed HTTP 400 context-overflow errors now get a capability_rejected: prompt_too_long marker for clients such as Claude Code. Without the update, readers troubleshooting converted provider errors would not know which errors trigger compaction and retry behavior.

What changed on disk

• content/docs/kubernetes/main/integrations/llm/providers/custom.md: Added the Kubernetes-mode note for converted Anthropic messages requests that hit context-overflow errors from Completions or Responses providers.
• content/docs/standalone/main/documentation/llm/api-types/messages.md: Added the standalone-mode note for converted Messages errors and the cases that keep the upstream message unchanged.
• content/docs/standalone/main/integrations/llm/providers/custom.md: Added the standalone custom-provider note so the release-note link resolves to a page that describes the behavior.

How to verify this change

1. Start agentgateway with a Messages route that selects a provider format of Completions or Responses, and use a mock upstream that returns HTTP 400 with {"error":{"code":"context_length_exceeded","message":"input rejected"}}.
2. Send a /v1/messages request through the route.
3. The response stays HTTP 400, and the converted Messages error message is capability_rejected: prompt_too_long input rejected. Repeat with an unrelated code, another HTTP status, or a message that already contains capability_rejected:; the upstream message stays unchanged.

Proposed release note

Wrote proposed-release-note.md because this fix changes observable client recovery behavior.

What was not verified

The configuration and behavior were not applied to a cluster, so every command in this diff is unrun. The live model-backed Claude Code compaction reproduction in body.md was not rerun for the current follow-up. No exact mock-upstream command was available in the dossier; the verification steps are derived from the regression cases in the code diff.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#3581 — fix(llm): translate context overflow errors for Claude Code recovery

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Claude Code gets stuck on Copilot context overflow errors. Translate confirmed overflows to capability_rejected: prompt_too_long in Responses and Chat Completions so it can compact and retry.
• Tested: a cluster was available — a kind cluster for agentgateway/upstream at kubernetes/main is provisioned in the drafting job, chosen automatically because the runnable-steps gate held this item
• 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/llm/tests.rs

Draft branch: pr-tracker-draft-agentgateway-3581

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	fb16b85
Status:	✅  Deploy successful!
Preview URL:	https://7789ada5.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-1qdp.agentproxy.pages.dev

View logs