fix: forward Responses reasoning configuration (vllm-project#225)

Author: StevenWang-CY

crates/agentic-server-core/benches/executor_throughput.rs

@@ -140,6 +140,7 @@ fn make_request(input: &str, stream: bool, prev_id: Option<String>) -> RequestPa
         stream,
         store: true,
         include: None,
+        reasoning: None,
         temperature: None,
         top_p: None,
         max_output_tokens: None,

crates/agentic-server-core/src/executor/compaction.rs

@@ -146,6 +146,7 @@ fn request_payload(model: String, input: ResponsesInput, instructions: Option<St
         stream: false,
         store: false,
         include: None,
+        reasoning: None,
         temperature: None,
         top_p: None,
         max_output_tokens: None,

crates/agentic-server-core/src/executor/modes/conversation.rs

@@ -160,6 +160,7 @@ mod tests {
             stream: false,
             store: true,
             include: None,
+            reasoning: None,
             temperature: None,
             top_p: None,
             max_output_tokens: None,

crates/agentic-server-core/src/executor/modes/response.rs

@@ -116,6 +116,7 @@ mod tests {
             stream: false,
             store: true,
             include: None,
+            reasoning: None,
             temperature: None,
             top_p: None,
             max_output_tokens: None,

crates/agentic-server-core/src/executor/rehydrate.rs

@@ -336,6 +336,7 @@ mod tests {
             stream: false,
             store: true,
             include: None,
+            reasoning: None,
             temperature: None,
             top_p: None,
             max_output_tokens: None,

crates/agentic-server-core/src/executor/upstream.rs

@@ -314,6 +314,7 @@ mod tests {
             stream: true,
             store: false,
             include: None,
+            reasoning: None,
             temperature: None,
             top_p: None,
             max_output_tokens: None,

crates/agentic-server-core/src/lib.rs

@@ -25,10 +25,10 @@ pub use types::{
     FunctionToolResultMessage, GatewayCallStatus, IncompleteDetails, InputContent, InputFileContent,
     InputFunctionToolCall, InputImageContent, InputItem, InputMessage, InputMessageContent, InputTextContent,
     InputTokenDetails, McpCall, McpCallStatus, McpToolParam, NonEmptyToolName, OutputItem, OutputMessage,
-    OutputTextContent, OutputTokenDetails, ReasoningOutput, ReasoningTextContent, RequestPayload, ResponsePayload,
-    ResponseUsage, ResponsesInput, ResponsesTool, ToolCallOutput, ToolChoice, ToolOutputContent, UpstreamRequest,
-    UpstreamTool, WebSearchAction, WebSearchActionFindInPage, WebSearchActionOpenPage, WebSearchActionSearch,
-    WebSearchCall, WebSearchCallStatus, WebSearchContextSize, WebSearchFilters, WebSearchSource, WebSearchToolParam,
-    WebSearchUserLocation,
+    OutputTextContent, OutputTokenDetails, ReasoningConfig, ReasoningOutput, ReasoningTextContent, RequestPayload,
+    ResponsePayload, ResponseUsage, ResponsesInput, ResponsesTool, ToolCallOutput, ToolChoice, ToolOutputContent,
+    UpstreamRequest, UpstreamTool, WebSearchAction, WebSearchActionFindInPage, WebSearchActionOpenPage,
+    WebSearchActionSearch, WebSearchCall, WebSearchCallStatus, WebSearchContextSize, WebSearchFilters, WebSearchSource,
+    WebSearchToolParam, WebSearchUserLocation,
 };
 pub use utils::{utcnow_str, uuid7_str};

crates/agentic-server-core/src/types/mod.rs

@@ -15,8 +15,8 @@ pub use io::{
     WebSearchSource,
 };
 pub use request_response::{
-    CompactRequest, CompactedResponse, ContextManagement, IncompleteDetails, RequestPayload, ResponsePayload,
-    UpstreamRequest, UpstreamTool,
+    CompactRequest, CompactedResponse, ContextManagement, IncompleteDetails, ReasoningConfig, RequestPayload,
+    ResponsePayload, UpstreamRequest, UpstreamTool,
 };
 pub use tools::{
     CodeInterpreterToolParam, CodexNamespaceMember, CodexNamespaceToolParam, CustomToolParam, EmptyToolNameError,

crates/agentic-server-core/src/types/request_response.rs

@@ -11,6 +11,21 @@ use super::tools::ResponsesTool;
 use crate::tool::{CodexNamespaceHandler, CustomHandler, ToolError};
 use crate::utils::common::serialize_to_string;
 
+/// Standard Responses API reasoning generation settings.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReasoningConfig {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub context: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effort: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub generate_summary: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub summary: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RequestPayload {
     pub model: String,
@@ -26,6 +41,8 @@ pub struct RequestPayload {
     #[serde(default = "default_true")]
     pub store: bool,
     pub include: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning: Option<Box<ReasoningConfig>>,
     pub temperature: Option<f64>,
     pub top_p: Option<f64>,
     pub max_output_tokens: Option<u32>,
@@ -62,6 +79,8 @@ pub struct UpstreamRequest<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub include: Option<&'a Vec<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub reasoning: Option<&'a ReasoningConfig>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub temperature: Option<f64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub top_p: Option<f64>,
@@ -73,6 +92,7 @@ pub struct UpstreamRequest<'a> {
     pub metadata: Option<&'a Value>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub parallel_tool_calls: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub cache_salt: Option<&'a str>,
 }
 
@@ -155,6 +175,7 @@ impl RequestPayload {
             tools,
             tool_choice: Some(tool_choice),
             include: self.include.as_ref(),
+            reasoning: self.reasoning.as_deref(),
             temperature: self.temperature,
             top_p: self.top_p,
             max_output_tokens: self.max_output_tokens,
@@ -329,7 +350,18 @@ mod tests {
     }
 
     #[test]
-    fn request_payload_forwards_cache_salt_upstream() {
+    fn request_payload_omits_absent_and_forwards_present_cache_salt_upstream() {
+        let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+            "model": "test-model",
+            "input": "hello"
+        }))
+        .expect("request should deserialize");
+
+        let upstream = serde_json::to_value(payload.to_upstream_request(false).expect("request should normalize"))
+            .expect("upstream request should serialize");
+
+        assert!(upstream.get("cache_salt").is_none());
+
         let payload: RequestPayload = serde_json::from_value(serde_json::json!({
             "model": "test-model",
             "input": "hello",
@@ -343,6 +375,72 @@ mod tests {
         assert_eq!(upstream["cache_salt"], "tenant-a");
     }
 
+    #[test]
+    fn request_payload_forwards_reasoning_configuration_upstream() {
+        let reasoning = serde_json::json!({
+            "context": "all_turns",
+            "effort": "high",
+            "generate_summary": "concise",
+            "mode": "pro",
+            "summary": "detailed"
+        });
+        let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+            "model": "test-model",
+            "input": "hello",
+            "reasoning": reasoning
+        }))
+        .expect("request should deserialize");
+
+        for stream in [false, true] {
+            let upstream = serde_json::to_value(payload.to_upstream_request(stream).expect("request should normalize"))
+                .expect("upstream request should serialize");
+
+            assert_eq!(upstream["reasoning"], reasoning);
+            assert_eq!(upstream["stream"], stream);
+        }
+    }
+
+    #[test]
+    fn request_payload_handles_reasoning_boundaries() {
+        for reasoning in [serde_json::json!({}), serde_json::json!({"effort": "minimal"})] {
+            let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+                "model": "test-model",
+                "input": "hello",
+                "reasoning": reasoning
+            }))
+            .expect("valid reasoning object should deserialize");
+            let upstream = serde_json::to_value(payload.to_upstream_request(false).expect("request should normalize"))
+                .expect("upstream request should serialize");
+
+            assert_eq!(upstream["reasoning"], reasoning);
+        }
+
+        for reasoning in [
+            serde_json::Value::Null,
+            serde_json::json!("high"),
+            serde_json::json!({"effort": 3}),
+        ] {
+            let parsed = serde_json::from_value::<RequestPayload>(serde_json::json!({
+                "model": "test-model",
+                "input": "hello",
+                "reasoning": reasoning
+            }));
+
+            if reasoning.is_null() {
+                let upstream = serde_json::to_value(
+                    parsed
+                        .expect("null should be treated as absent")
+                        .to_upstream_request(false)
+                        .expect("request should normalize"),
+                )
+                .expect("upstream request should serialize");
+                assert!(upstream.get("reasoning").is_none());
+            } else {
+                assert!(parsed.is_err(), "non-object reasoning configuration should be rejected");
+            }
+        }
+    }
+
     #[test]
     fn request_payload_uses_option_tool_choice_for_missing_vs_explicit() {
         let absent: RequestPayload = serde_json::from_value(serde_json::json!({

crates/agentic-server-core/tests/cassettes/README.md

@@ -83,6 +83,7 @@ model requested by Codex 0.149.1.
 --openai URL           OpenAI upstream (default https://api.openai.com)
 --tools FILE           JSON file containing a tools array (responses mode only)
 --tool-choice VALUE    "auto", "none", "required", or JSON e.g. '{"type":"function","name":"foo"}'
+--reasoning JSON       JSON object containing Responses reasoning settings
 --input-file FILE       JSON string or item array for one HTTP Responses turn
 --max-output-tokens N  max_output_tokens for Responses requests (default 1024; use 0 to omit)
 --proxy-port PORT      Local proxy port (default 7070)
@@ -192,7 +193,7 @@ turns:
 | Script | Cassettes | Backend |
 |--------|-----------|---------|
 | `record_text_only_cassettes.sh` | 10 text-only cassettes (responses + conv modes, streaming + non-streaming) | OpenAI (`OPENAI_API_KEY`) |
-| `record_reasoning_cassettes.sh` | 2 reasoning cassettes (single turn, streaming + non-streaming) | vLLM |
+| `record_reasoning_cassettes.sh` | Matching explicit-reasoning cassettes (streaming + non-streaming) | gateway and OpenAI reference; optional direct vLLM |
 | `record_tool_call_cassettes.sh` | 8 tool-call cassettes (4 tool_choice modes x streaming + non-streaming) | vLLM |
 | `record_codex_cli_tool_call_cassettes.sh` | Codex function/namespace/custom-tool matrix | gateway, vLLM, and OpenAI |
 | `record_custom_tool_cassettes.sh` | Matching two-turn custom-tool flows (streaming + non-streaming) | gateway and OpenAI reference |
@@ -207,12 +208,44 @@ OPENAI_API_KEY=sk-... bash tests/cassettes/record_text_only_cassettes.sh
 MODEL=gpt-4o-mini OPENAI_API_KEY=sk-... bash tests/cassettes/record_text_only_cassettes.sh
 ```
 
-### Reasoning (vLLM)
+### Reasoning (gateway and OpenAI)
+
+The default records the same explicit `reasoning` object against OpenAI and the
+gateway for both response modes. The gateway fixture uses the same OpenAI model
+as its reference so the comparison isolates gateway request and response
+handling from model differences. Use `REASONING_RECORD_SET=gateway`,
+`REASONING_RECORD_SET=openai`, or `REASONING_RECORD_SET=vllm` to record one
+provider. The gateway recording requires a running gateway and reasoning-capable
+upstream; the optional direct-vLLM set retains the legacy accumulator workflow.
+Every selected recording is staged and validated before any final fixture is
+replaced, so a failed provider or response cannot leave a partially refreshed
+comparison set.
 
 ```bash
-vllm serve Qwen/Qwen3-30B-A3B-FP8 --reasoning-parser deepseek_r1 --port 5050 > server.log 2>&1
+# Start the gateway against the same OpenAI ground-truth model in one terminal.
+OPENAI_API_KEY=sk-... \
+cargo run -p agentic-server -- \
+  --llm-api-base https://api.openai.com \
+  --skip-llm-ready-check
 
-VLLM_URL=http://0.0.0.0:5050 MODEL=Qwen/Qwen3-30B-A3B-FP8 bash tests/cassettes/record_reasoning_cassettes.sh
+# Record the OpenAI-reference and gateway pairs from another terminal.
+OPENAI_API_KEY=sk-... \
+GATEWAY_URL=http://localhost:9000 \
+MODEL=gpt-5.6 \
+bash crates/agentic-server-core/tests/cassettes/record_reasoning_cassettes.sh
+
+# To refresh only the gateway-facing pair instead:
+REASONING_RECORD_SET=gateway \
+GATEWAY_URL=http://localhost:9000 \
+MODEL=gpt-5.6 \
+bash crates/agentic-server-core/tests/cassettes/record_reasoning_cassettes.sh
+
+vllm serve Qwen/Qwen3-30B-A3B-FP8 --reasoning-parser qwen3 --port 5050 > server.log 2>&1
+
+REASONING_RECORD_SET=vllm \
+VLLM_URL=http://0.0.0.0:5050 \
+MODEL=Qwen/Qwen3-30B-A3B-FP8 \
+bash crates/agentic-server-core/tests/cassettes/record_reasoning_cassettes.sh
 ```
 
 ### Tool calls (vLLM)