From dede4089a6beb78c22be43c89634ddd8bbfde0ce Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 27 Feb 2026 16:21:08 +0000
Subject: [PATCH] docs(openai): add clear server compaction toggle examples

---
 docs/providers/openai.md | 45 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/docs/providers/openai.md b/docs/providers/openai.md
index a06d5dee79d..8b26072f1a6 100644
--- a/docs/providers/openai.md
+++ b/docs/providers/openai.md
@@ -95,7 +95,28 @@ compaction payload hints:
 By default, `compact_threshold` is `70%` of model `contextWindow` (or `80000`
 when unavailable).
 
-You can override per model:
+### Enable server-side compaction explicitly
+
+Use this when you want to force `context_management` injection on compatible
+Responses models (for example Azure OpenAI Responses):
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "azure-openai-responses/gpt-4o": {
+          params: {
+            responsesServerCompaction: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Enable with a custom threshold
 
 ```json5
 {
@@ -114,7 +135,27 @@ You can override per model:
 }
 ```
 
-Set `responsesServerCompaction: false` to disable this injection for a model.
+### Disable server-side compaction
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5": {
+          params: {
+            responsesServerCompaction: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`responsesServerCompaction` only controls `context_management` injection.
+Direct OpenAI Responses models still force `store: true` unless compat sets
+`supportsStore: false`.
 
 ## Notes