Make Agentic API the execution owner for typed Responses tools

[franciscojavierarceo]

Context

Agentic API already has typed ResponsesTool declarations, request-scoped tool routing, and a gateway execution loop. Draft PR #34 also demonstrates the intended file_search flow with OGX: normalize the built-in tool into a model-visible function, execute search in the gateway, inject the result, and continue inference.

The remaining architectural gap is to make that ownership model explicit and general across Responses tool types. Related vLLM work in vllm-project/vllm#34487 currently includes both typed Harmony handling and OGX execution; external tool execution should instead live in Agentic API.

Desired ownership boundary

• vLLM/inference providers: render tool definitions, generate tokens, and parse model output into tool-call shapes.
• Agentic API: validate declarations, choose the upstream representation, route calls, execute gateway-owned tools, emit canonical typed Responses items/events, and continue the agent loop.
• Clients: execute client-owned function/custom/namespace calls.
• External backends such as OGX: remain behind Agentic API executors; credentials and network access never enter vLLM core.

Provider capability must not change execution ownership. A backend may support a native typed file_search declaration/call, but Agentic API still performs the search.

Proposed design

Extend the existing tool framework so each supported Responses tool type defines:

1. Public declaration validation.
2. Upstream representation:
   • default: normalize to a function declaration;
   • optional: forward a native declaration when the configured upstream advertises support.
3. Call recognition and normalization into one internal invocation type.
4. Ownership and executor selection.
5. Canonical output-item, streaming-event, and continuation-input encoding.

Keep executor configuration separate from upstream capabilities. For example:

• executor mapping: file_search -> ogx
• upstream capability: native file_search declarations/calls supported or unsupported

The request-scoped registry must retain the original tool type and configuration so a generic upstream function_call can be restored to file_search_call. Ambiguous name collisions, including a custom function named file_search alongside the built-in, must fail validation rather than route heuristically.

First implementation slice: file_search + OGX

Adapt/rebase the useful pieces of #34 onto the current ToolHandler / GatewayExecutor framework:

• Complete FileSearchToolParam validation, including OpenAI-compatible search options.
• Normalize file_search to a model-visible function for generic vLLM backends.
• Add a file-search executor slot and OGX implementation in Agentic API.
• Add canonical file_search_call output types and streaming lifecycle events.
• Execute OGX, inject the tool result, and continue the existing gateway loop.
• Surface missing configuration, backend failures, malformed payloads, and incomplete calls explicitly.
• Do not add OGX clients, credentials, or execution loops to vLLM core.

Native typed calls can be added as a compatible upstream representation later without changing execution ownership.

Acceptance criteria

• A standard Responses file_search declaration works through a generic function-only vLLM backend.
• Agentic API executes OGX and returns canonical file_search_call items/results.
• Streaming emits the expected searching/completed or failure lifecycle.
• OGX configuration and credentials exist only in Agentic API.
• tool_choice: "none" prevents declaration and execution.
• Custom functions named file_search are not misclassified; ambiguous declarations are rejected.
• Truncated/incomplete calls are not executed or reported as completed.
• Backend failures are distinguishable from successful zero-result searches.
• Tests cover generic function normalization, routing, execution, continuation, typed output restoration, streaming, and failures.
• The design leaves a capability seam for native typed upstream calls without requiring it in the first slice.

Related

• feat: agentic loop with OGX vector search and conversation persistence #34
• [Chore] Improve Harmony file_search tool and showcase demo vllm#34487