fix: preserve parallel tool call setting (vllm-project#128)

## Summary
- parse `parallel_tool_calls` on `/v1/responses` requests
- forward the field through `RequestPayload::to_upstream_request` after
gateway tool normalization
- add unit and route-level regression coverage proving
`parallel_tool_calls: false` reaches the mock vLLM request

Closes vllm-project#127.

## Why
The gateway already preserves several Responses API generation/control
fields (`include`, `temperature`, `top_p`, `max_output_tokens`,
`truncation`, `metadata`) while normalizing tools for vLLM.
`parallel_tool_calls` was missing from the typed request model, so
clients that explicitly disabled parallel tool calls had that setting
silently dropped on the executor path.

## Validation
- `cargo test -p agentic-server-core`
- `cargo test -p agentic-server --test responses_test`
- `cargo test --workspace`
- `cargo clippy --workspace --all-targets -- -D warnings`
- `cargo fmt -- --check`

Focused tests were written first and failed before the implementation
because `parallel_tool_calls` serialized as absent/null instead of
`false`.

---------

Signed-off-by: harivilasp <harivilasp@gmail.com>

Author: harivilasp

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

@@ -145,6 +145,7 @@ fn make_request(input: &str, stream: bool, prev_id: Option<String>) -> RequestPa
         max_output_tokens: None,
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     }
 }

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

@@ -141,6 +141,7 @@ mod tests {
             max_output_tokens: None,
             truncation: None,
             metadata: None,
+            parallel_tool_calls: None,
             cache_salt: None,
         };
         RequestContext {

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

@@ -120,6 +120,7 @@ mod tests {
             max_output_tokens: None,
             truncation: None,
             metadata: None,
+            parallel_tool_calls: None,
             cache_salt: None,
         };
         RequestContext {

crates/agentic-server-core/src/tool/normalize.rs

@@ -6,10 +6,33 @@ use crate::utils::common::serialize_to_value_or_custom_default;
 use super::codex::CodexNamespaceHandler;
 use super::function::FunctionHandler;
 use super::handler::{ToolHandler, ToolOutput};
-use super::mcp::McpHandler;
+use super::mcp::{McpHandler, maybe_mcp_function};
+use super::registry::ToolType;
 use super::web_search::web_search_function_tool;
 
 impl ResponsesTool {
+    /// Return the gateway routing type this declaration would register as.
+    #[must_use]
+    pub fn tool_type(&self) -> Option<ToolType> {
+        match self {
+            Self::Function(p) => match maybe_mcp_function(p) {
+                Some(params) if !params.is_empty() => Some(ToolType::Mcp),
+                _ => Some(ToolType::Function),
+            },
+            Self::Mcp(_) => Some(ToolType::Mcp),
+            Self::WebSearch(_) => Some(ToolType::WebSearch),
+            Self::FileSearch(_) => Some(ToolType::FileSearch),
+            Self::CodeInterpreter(_) => Some(ToolType::CodeInterpreter),
+            Self::Namespace(_) => Some(ToolType::CodexNamespace),
+            Self::Custom(_) | Self::Unknown => None,
+        }
+    }
+
+    #[must_use]
+    pub fn is_gateway_owned(&self) -> bool {
+        self.tool_type().is_some_and(ToolType::is_gateway_owned)
+    }
+
     /// Normalise function-like tool declarations to the `FunctionTool` wire format that vLLM understands.
     ///
     /// - `Function` variants convert via [`From<&FunctionToolParam>`] for `FunctionTool`.

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

@@ -28,6 +28,7 @@ pub struct RequestPayload {
     pub max_output_tokens: Option<u32>,
     pub truncation: Option<String>,
     pub metadata: Option<Value>,
+    pub parallel_tool_calls: Option<bool>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cache_salt: Option<String>,
 }
@@ -64,6 +65,7 @@ pub struct UpstreamRequest<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub metadata: Option<&'a Value>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub parallel_tool_calls: Option<bool>,
     pub cache_salt: Option<&'a str>,
 }
 
@@ -128,6 +130,18 @@ impl RequestPayload {
     /// flat name collides with a top-level function tool or another namespace
     /// member.
     pub fn to_upstream_request(&self, stream: bool) -> Result<UpstreamRequest<'_>, ToolError> {
+        let has_built_in_tool = self.declares_built_in_tool();
+        if has_built_in_tool && self.parallel_tool_calls == Some(true) {
+            return Err(ToolError::Config(
+                "parallel_tool_calls must be false when using built-in tools".into(),
+            ));
+        }
+        let parallel_tool_calls = if has_built_in_tool {
+            Some(false)
+        } else {
+            self.parallel_tool_calls
+        };
+
         let renamed_tools = self
             .tools
             .as_deref()
@@ -151,9 +165,16 @@ impl RequestPayload {
             max_output_tokens: self.max_output_tokens,
             truncation: self.truncation.as_deref(),
             metadata: self.metadata.as_ref(),
+            parallel_tool_calls,
             cache_salt: self.cache_salt.as_deref(),
         })
     }
+
+    fn declares_built_in_tool(&self) -> bool {
+        self.tools
+            .as_deref()
+            .is_some_and(|tools| tools.iter().any(ResponsesTool::is_gateway_owned))
+    }
 }
 
 fn upstream_tools(tool: ResponsesTool) -> Vec<UpstreamTool> {
@@ -302,6 +323,144 @@ mod tests {
         assert_eq!(value["input"], "hi");
     }
 
+    #[test]
+    fn to_upstream_request_preserves_parallel_tool_calls() {
+        let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+            "model": "test",
+            "input": "hi",
+            "parallel_tool_calls": false
+        }))
+        .unwrap();
+
+        let upstream = payload.to_upstream_request(false).expect("valid upstream request");
+        let value = serde_json::to_value(upstream).unwrap();
+        assert_eq!(value["parallel_tool_calls"], false);
+    }
+
+    #[test]
+    fn to_upstream_request_allows_parallel_tool_calls_for_client_function_tools() {
+        let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+            "model": "test",
+            "input": "hi",
+            "parallel_tool_calls": true,
+            "tools": [{"type": "function", "name": "get_weather"}]
+        }))
+        .unwrap();
+
+        let upstream = payload
+            .to_upstream_request(false)
+            .expect("function tools allow parallel calls");
+        let value = serde_json::to_value(upstream).unwrap();
+        assert_eq!(value["parallel_tool_calls"], true);
+    }
+
+    #[test]
+    fn to_upstream_request_validates_parallel_tool_calls_for_mixed_tools() {
+        for built_in_tool in builtin_tool_declarations() {
+            for (parallel_tool_calls, should_reject) in [(false, false), (true, true)] {
+                let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+                    "model": "test",
+                    "input": "hi",
+                    "parallel_tool_calls": parallel_tool_calls,
+                    "tools": [
+                        {"type": "function", "name": "get_weather"},
+                        built_in_tool.clone()
+                    ]
+                }))
+                .unwrap();
+
+                let result = payload.to_upstream_request(false);
+                if should_reject {
+                    let err = result.expect_err("built-in tools should reject parallel tool calls");
+                    assert!(err.to_string().contains("parallel_tool_calls must be false"));
+                } else {
+                    let value =
+                        serde_json::to_value(result.expect("mixed built-in and function tools allow serial calls"))
+                            .unwrap();
+                    assert_eq!(value["parallel_tool_calls"], false);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn to_upstream_request_sets_serial_tool_calls_for_builtin_tools() {
+        for tool in builtin_tool_declarations() {
+            let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+                "model": "test",
+                "input": "hi",
+                "tools": [tool]
+            }))
+            .unwrap();
+
+            let upstream = payload
+                .to_upstream_request(false)
+                .expect("built-in tools default to serial tool calls");
+            let value = serde_json::to_value(upstream).unwrap();
+            assert_eq!(value["parallel_tool_calls"], false);
+        }
+    }
+
+    #[test]
+    fn to_upstream_request_rejects_parallel_tool_calls_for_builtin_tools() {
+        for tool in builtin_tool_declarations() {
+            let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+                "model": "test",
+                "input": "hi",
+                "parallel_tool_calls": true,
+                "tools": [tool]
+            }))
+            .unwrap();
+
+            let Err(err) = payload.to_upstream_request(false) else {
+                panic!("built-in tools should reject parallel_tool_calls=true");
+            };
+
+            assert!(err.to_string().contains("parallel_tool_calls must be false"));
+        }
+    }
+
+    #[test]
+    fn to_upstream_request_allows_builtin_tools_with_serial_tool_calls() {
+        for tool in builtin_tool_declarations() {
+            let payload: RequestPayload = serde_json::from_value(serde_json::json!({
+                "model": "test",
+                "input": "hi",
+                "parallel_tool_calls": false,
+                "tools": [tool]
+            }))
+            .unwrap();
+
+            let upstream = payload
+                .to_upstream_request(false)
+                .expect("serial built-in tool request is valid");
+            let value = serde_json::to_value(upstream).unwrap();
+            assert_eq!(value["parallel_tool_calls"], false);
+        }
+    }
+
+    fn builtin_tool_declarations() -> Vec<Value> {
+        vec![
+            serde_json::json!({
+                "type": "function",
+                "name": "read_mcp_resource",
+                "metadata": {
+                    "server_label": "repo",
+                    "server_url": "http://localhost:9001/mcp"
+                }
+            }),
+            serde_json::json!({
+                "type": "mcp",
+                "name": "read_mcp_resource",
+                "server_label": "repo",
+                "server_url": "http://localhost:9001/mcp"
+            }),
+            serde_json::json!({"type": "web_search_preview"}),
+            serde_json::json!({"type": "file_search", "vector_store_ids": ["vs_abc"]}),
+            serde_json::json!({"type": "code_interpreter"}),
+        ]
+    }
+
     #[test]
     fn to_upstream_request_flattens_namespace_and_skips_unknown_tools() {
         let payload: RequestPayload = serde_json::from_value(serde_json::json!({

crates/agentic-server-core/tests/dispatch_loop_cassette_test.rs

@@ -127,6 +127,7 @@ fn request(text: &str, tools: Option<Vec<ResponsesTool>>) -> RequestPayload {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     }
 }

crates/agentic-server-core/tests/support/mod.rs

@@ -369,6 +369,7 @@ pub fn make_request(
         max_output_tokens: None,
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     }
 }

crates/agentic-server-core/tests/web_search_tool_test.rs

@@ -584,6 +584,7 @@ async fn execute_runs_web_search_and_sends_tool_output_back_to_model() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -668,6 +669,7 @@ async fn execute_relaxes_forced_tool_choice_after_web_search_result() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -716,6 +718,7 @@ async fn execute_returns_mixed_client_tool_calls_without_followup_model_request(
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -763,6 +766,7 @@ async fn execute_returns_mixed_client_tool_calls_without_followup_model_request(
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
     let continuation = ExecuteRequest::new(continuation_payload, exec_ctx).run().await.unwrap();
@@ -833,6 +837,7 @@ async fn execute_accumulates_usage_across_web_search_model_rounds() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -876,6 +881,7 @@ async fn stream_emits_web_search_lifecycle_events_before_final_payload() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -958,6 +964,7 @@ async fn stream_hides_web_search_function_events_when_name_arrives_on_done() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1024,6 +1031,7 @@ async fn execute_runs_multiple_web_search_calls_concurrently() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1072,6 +1080,7 @@ async fn execute_feeds_web_search_execution_errors_back_to_model() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1122,6 +1131,7 @@ async fn execute_returns_incomplete_after_max_gateway_tool_rounds() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1172,6 +1182,7 @@ async fn execute_feeds_invalid_web_search_arguments_back_to_model() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1229,6 +1240,7 @@ async fn execute_runs_large_gateway_fanout_without_hard_cap() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1292,6 +1304,7 @@ async fn stream_error_events_escape_error_messages() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1367,6 +1380,7 @@ async fn incomplete_turn_persists_a_consistent_conversation_for_continuation() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
 
@@ -1393,6 +1407,7 @@ async fn incomplete_turn_persists_a_consistent_conversation_for_continuation() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };
     let _ = ExecuteRequest::new(continuation_payload, exec_ctx).run().await.unwrap();
@@ -1463,6 +1478,7 @@ async fn stream_returns_incomplete_after_max_gateway_tool_rounds() {
         max_output_tokens: Some(1024),
         truncation: None,
         metadata: None,
+        parallel_tool_calls: None,
         cache_salt: None,
     };