feat: add parallel tool calling support

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to Agentic API are documented here.
 
 ## [Unreleased]
 
+### Changed
+
+- Forwarded `parallel_tool_calls` as the model-generation preference for typed
+  Responses requests, including built-in-only and mixed tool declarations (#181).
+- Added bounded, configurable parallel execution for Responses gateway rounds,
+  preserving model call order and applying per-handler same-tool safety.
+- Preserved MCP list-tools records in continuation history for registry lifecycle
+  decisions while excluding them from model input, preventing repeated public
+  list-tools emission on later turns.
+
 ### Added
 
 - Documented running Agentic API in front of NVIDIA Dynamo and recorded Dynamo cassettes for stateful and

README.md

@@ -186,16 +186,21 @@ api_key_env = "YOU_API_KEY"
 [mcp]
 allowed_hosts = ["mcp.example.com"]
 
+[tools]
+# Upper bound for gateway-owned calls running at once within one Responses round.
+max_concurrent_gateway_calls = 5
+
 [mcp_servers.counter]
 url = "https://mcp.example.com/mcp"
 allowed_tools = ["tool_1_name", "tool_2_name"]
 require_approval = "never"
 ```
 
 `api_key_env` names the process environment variable containing the web-search credential; it does not contain the
-credential itself. `YOU_API_BASE_URL` and `AGENTIC_MCP_ALLOWED_HOSTS` can override their typed file settings. The MCP
-allowlist is used only for request-declared remote MCP URLs; configured `[mcp_servers]` entries are trusted operator
-configuration.
+credential itself. `YOU_API_BASE_URL`, `AGENTIC_MCP_ALLOWED_HOSTS`, and
+`AGENTIC_MAX_CONCURRENT_GATEWAY_CALLS` can override their typed file settings. The concurrency value is a sliding-window
+upper bound; handlers may further serialize calls to the same tool name. The MCP allowlist is used only for
+request-declared remote MCP URLs; configured `[mcp_servers]` entries are trusted operator configuration.
 
 With that file in place, inject only the secret when starting the server:
 

ROADMAP.md

@@ -71,15 +71,14 @@ the tool type. vLLM Agentic API should only execute tools that resolve to a
 configured gateway-owned handler. Unknown, unsupported, or ambiguous tool shapes
 are preserved and returned or passed through; they are never executed by default.
 
-Core work:
-
-- Support true parallel tool calling for gateway-owned built-in tools: a single
-  turn should be able to invoke the same built-in tool more than once (for
-  example, two simultaneous web searches) and have every invocation execute
-  concurrently, with all results appended before continuing the agentic loop.
-  The executor's dispatch path already bounds concurrent execution internally,
-  but requests cannot yet exercise it this way end to end. Not yet implemented;
-  tracked by [#181](https://github.com/vllm-project/agentic-api/issues/181).
+Requests may opt into parallel tool calling for gateway-owned built-in tools: a
+single turn can invoke the same built-in tool more than once (for example, two
+web searches). Agentic API forwards that model-generation preference upstream,
+then executes emitted gateway calls through a bounded, configurable window.
+Calls to different tool names can overlap; calls to the same name overlap only
+when that handler declares it safe. Results retain model call order and are all
+appended before continuing the agentic loop
+([#181](https://github.com/vllm-project/agentic-api/issues/181)).
 
 Initial and expected tool areas include:
 

TERMINOLOGY.md

@@ -223,7 +223,9 @@ user-visible unit of interaction.
 ### tool registry
 
 The project-specific request-scoped mapping from model-visible tool names to their original type, configuration, and
-available executor. It routes calls after inference; it is not part of the Responses wire format.
+explicit ownership. Gateway-owned entries may contain a `GatewayBinding` with an executor and same-tool concurrency
+policy. The registry routes calls after inference and also retains MCP discovery-history metadata; it is not part of
+the Responses wire format.
 
 ### tool normalization
 

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

@@ -19,6 +19,7 @@ pub const DEFAULT_POSTGRES_STATEMENT_TIMEOUT_SECONDS: u64 = 30;
 pub const DEFAULT_SQLITE_MAX_CONNECTIONS: u32 = 4;
 pub const DEFAULT_SQLITE_JOURNAL_SIZE_LIMIT_BYTES: u64 = 6_144_000;
 pub const DEFAULT_SQLITE_MMAP_SIZE_BYTES: u64 = 268_435_456;
+pub const DEFAULT_MAX_CONCURRENT_GATEWAY_CALLS: usize = 5;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PostgresConfig {
@@ -89,12 +90,28 @@ pub struct WebSearchProviderConfig {
     pub base_url: Option<String>,
 }
 
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct ToolRuntimeConfig {
     pub web_search: WebSearchProviderConfig,
     pub mcp_servers: HashMap<String, McpServerEntry>,
     pub mcp_allowed_hosts: Vec<String>,
     pub messages_gateway_tool_aliases: Option<String>,
+    /// Upper bound on gateway-owned tool calls executing concurrently within one
+    /// round. A sliding window admits another call as one finishes. Individual
+    /// handlers may further serialize calls to the same tool name.
+    pub max_concurrent_gateway_calls: usize,
+}
+
+impl Default for ToolRuntimeConfig {
+    fn default() -> Self {
+        Self {
+            web_search: WebSearchProviderConfig::default(),
+            mcp_servers: HashMap::default(),
+            mcp_allowed_hosts: Vec::default(),
+            messages_gateway_tool_aliases: None,
+            max_concurrent_gateway_calls: DEFAULT_MAX_CONCURRENT_GATEWAY_CALLS,
+        }
+    }
 }
 
 #[derive(Debug, Clone)]

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

@@ -95,7 +95,7 @@ fn item_has_meaningful_context(item: &InputItem) -> bool {
                 || reasoning.encrypted_content.as_ref().is_some_and(value_has_content)
         }
         InputItem::Compaction(compaction) => !compaction.encrypted_content.trim().is_empty(),
-        InputItem::CompactionTrigger | InputItem::Unknown => false,
+        InputItem::McpListTools(_) | InputItem::CompactionTrigger | InputItem::Unknown => false,
     }
 }