feat: add support for tool_choice to responses api (#4106)

# What does this PR do?
Adds support for enforcing tool usage via responses api. See
https://platform.openai.com/docs/api-reference/responses/create#responses_create-tool_choice
for details from official documentation.
Note: at present this PR only supports `file_search` and `web_search` as
options to enforce builtin tool usage

<!-- If resolving an issue, uncomment and update the line below -->
Closes #3548 

## Test Plan
<!-- Describe the tests you ran to verify your changes with result
summaries. *Provide clear instructions so the plan can be easily
re-executed.* -->
`./scripts/unit-tests.sh
tests/unit/providers/agents/meta_reference/test_response_tool_context.py
`

---------

Signed-off-by: Jaideep Rao <jrao@redhat.com>

docs/static/stainless-llama-stack-spec.yaml

@@ -6969,6 +6969,38 @@ components:
               title: OpenAIResponseInputToolWebSearch | ... (4 variants)
             type: array
           - type: 'null'
+        tool_choice:
+          anyOf:
+          - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMode'
+            title: OpenAIResponseInputToolChoiceMode
+          - oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+              title: OpenAIResponseInputToolChoiceAllowedTools
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+              title: OpenAIResponseInputToolChoiceFileSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+              title: OpenAIResponseInputToolChoiceWebSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+              title: OpenAIResponseInputToolChoiceFunctionTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+              title: OpenAIResponseInputToolChoiceMCPTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+              title: OpenAIResponseInputToolChoiceCustomTool
+            discriminator:
+              propertyName: type
+              mapping:
+                allowed_tools: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+                custom: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+                file_search: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+                function: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+                mcp: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+                web_search: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_2025_08_26: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview_2025_03_11: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            title: OpenAIResponseInputToolChoiceAllowedTools | ... (6 variants)
+          - type: 'null'
+          title: OpenAIResponseInputToolChoiceMode
         truncation:
           anyOf:
           - type: string
@@ -7356,6 +7388,38 @@ components:
             title: OpenAIResponseText
           - type: 'null'
           title: OpenAIResponseText
+        tool_choice:
+          anyOf:
+          - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMode'
+            title: OpenAIResponseInputToolChoiceMode
+          - oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+              title: OpenAIResponseInputToolChoiceAllowedTools
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+              title: OpenAIResponseInputToolChoiceFileSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+              title: OpenAIResponseInputToolChoiceWebSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+              title: OpenAIResponseInputToolChoiceFunctionTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+              title: OpenAIResponseInputToolChoiceMCPTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+              title: OpenAIResponseInputToolChoiceCustomTool
+            discriminator:
+              propertyName: type
+              mapping:
+                allowed_tools: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+                custom: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+                file_search: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+                function: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+                mcp: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+                web_search: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_2025_08_26: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview_2025_03_11: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            title: OpenAIResponseInputToolChoiceAllowedTools | ... (6 variants)
+          - type: 'null'
+          title: OpenAIResponseInputToolChoiceMode
         tools:
           anyOf:
           - items:
@@ -7515,6 +7579,38 @@ components:
               title: OpenAIResponseInputToolWebSearch | ... (4 variants)
             type: array
           - type: 'null'
+        tool_choice:
+          anyOf:
+          - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMode'
+            title: OpenAIResponseInputToolChoiceMode
+          - oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+              title: OpenAIResponseInputToolChoiceAllowedTools
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+              title: OpenAIResponseInputToolChoiceFileSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+              title: OpenAIResponseInputToolChoiceWebSearch
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+              title: OpenAIResponseInputToolChoiceFunctionTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+              title: OpenAIResponseInputToolChoiceMCPTool
+            - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+              title: OpenAIResponseInputToolChoiceCustomTool
+            discriminator:
+              propertyName: type
+              mapping:
+                allowed_tools: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+                custom: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+                file_search: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+                function: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+                mcp: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+                web_search: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_2025_08_26: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+                web_search_preview_2025_03_11: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            title: OpenAIResponseInputToolChoiceAllowedTools | ... (6 variants)
+          - type: 'null'
+          title: OpenAIResponseInputToolChoiceMode
         truncation:
           anyOf:
           - type: string
@@ -12090,6 +12186,112 @@ components:
       type: object
       title: OpenAIChatCompletionUsagePromptTokensDetails
       description: Token details for prompt tokens in OpenAI chat completion usage.
+    OpenAIResponseInputToolChoiceAllowedTools:
+      properties:
+        mode:
+          type: string
+          enum:
+          - auto
+          - required
+          title: Mode
+          default: auto
+        tools:
+          items:
+            additionalProperties:
+              type: string
+            type: object
+          type: array
+          title: Tools
+        type:
+          type: string
+          const: allowed_tools
+          title: Type
+          default: allowed_tools
+      type: object
+      required:
+      - tools
+      title: OpenAIResponseInputToolChoiceAllowedTools
+      description: Constrains the tools available to the model to a pre-defined set.
+    OpenAIResponseInputToolChoiceCustomTool:
+      properties:
+        type:
+          type: string
+          const: custom
+          title: Type
+          default: custom
+        name:
+          type: string
+          title: Name
+      type: object
+      required:
+      - name
+      title: OpenAIResponseInputToolChoiceCustomTool
+      description: Forces the model to call a custom tool.
+    OpenAIResponseInputToolChoiceFileSearch:
+      properties:
+        type:
+          type: string
+          const: file_search
+          title: Type
+          default: file_search
+      type: object
+      title: OpenAIResponseInputToolChoiceFileSearch
+      description: Indicates that the model should use file search to generate a response.
+    OpenAIResponseInputToolChoiceFunctionTool:
+      properties:
+        name:
+          type: string
+          title: Name
+        type:
+          type: string
+          const: function
+          title: Type
+          default: function
+      type: object
+      required:
+      - name
+      title: OpenAIResponseInputToolChoiceFunctionTool
+      description: Forces the model to call a specific function.
+    OpenAIResponseInputToolChoiceMCPTool:
+      properties:
+        server_label:
+          type: string
+          title: Server Label
+        type:
+          type: string
+          const: mcp
+          title: Type
+          default: mcp
+        name:
+          anyOf:
+          - type: string
+          - type: 'null'
+      type: object
+      required:
+      - server_label
+      title: OpenAIResponseInputToolChoiceMCPTool
+      description: Forces the model to call a specific tool on a remote MCP server
+    OpenAIResponseInputToolChoiceMode:
+      type: string
+      enum:
+      - auto
+      - required
+      - none
+      title: OpenAIResponseInputToolChoiceMode
+    OpenAIResponseInputToolChoiceWebSearch:
+      properties:
+        type:
+          title: Type
+          default: web_search
+          type: string
+          enum:
+          - web_search
+          - web_search_preview
+          - web_search_preview_2025_03_11
+          - web_search_2025_08_26
+      type: object
+      title: OpenAIResponseInputToolChoiceWebSearch
+      description: Indicates that the model should use web search to generate a response
     OpenAIResponseMessage-Input:
       properties:
         content:
@@ -12570,6 +12772,132 @@ components:
       - $ref: '#/components/schemas/GrammarResponseFormat'
         title: GrammarResponseFormat
       title: JsonSchemaResponseFormat | GrammarResponseFormat
+    AllowedToolsConfig:
+      properties:
+        tools:
+          items:
+            additionalProperties: true
+            type: object
+          title: Tools
+          type: array
+        mode:
+          enum:
+          - auto
+          - required
+          title: Mode
+          type: string
+      required:
+      - tools
+      - mode
+      title: AllowedToolsConfig
+      type: object
+    CustomToolConfig:
+      description: Custom tool configuration for OpenAI-compatible chat completion requests.
+      properties:
+        name:
+          title: Name
+          type: string
+      required:
+      - name
+      title: CustomToolConfig
+      type: object
+    FunctionToolConfig:
+      properties:
+        name:
+          title: Name
+          type: string
+      required:
+      - name
+      title: FunctionToolConfig
+      type: object
+    OpenAIChatCompletionToolChoiceAllowedTools:
+      description: Allowed tools response format for OpenAI-compatible chat completion requests.
+      properties:
+        type:
+          const: allowed_tools
+          default: allowed_tools
+          title: Type
+          type: string
+        allowed_tools:
+          $ref: '#/components/schemas/AllowedToolsConfig'
+      required:
+      - allowed_tools
+      title: OpenAIChatCompletionToolChoiceAllowedTools
+      type: object
+    OpenAIChatCompletionToolChoiceCustomTool:
+      description: Custom tool choice for OpenAI-compatible chat completion requests.
+      properties:
+        type:
+          const: custom
+          default: custom
+          title: Type
+          type: string
+        custom:
+          $ref: '#/components/schemas/CustomToolConfig'
+      required:
+      - custom
+      title: OpenAIChatCompletionToolChoiceCustomTool
+      type: object
+    OpenAIChatCompletionToolChoiceFunctionTool:
+      description: Function tool choice for OpenAI-compatible chat completion requests.
+      properties:
+        type:
+          const: function
+          default: function
+          title: Type
+          type: string
+        function:
+          $ref: '#/components/schemas/FunctionToolConfig'
+      required:
+      - function
+      title: OpenAIChatCompletionToolChoiceFunctionTool
+      type: object
+    OpenAIChatCompletionToolChoice:
+      discriminator:
+        mapping:
+          allowed_tools: '#/components/schemas/OpenAIChatCompletionToolChoiceAllowedTools'
+          custom: '#/components/schemas/OpenAIChatCompletionToolChoiceCustomTool'
+          function: '#/components/schemas/OpenAIChatCompletionToolChoiceFunctionTool'
+        propertyName: type
+      oneOf:
+      - $ref: '#/components/schemas/OpenAIChatCompletionToolChoiceAllowedTools'
+        title: OpenAIChatCompletionToolChoiceAllowedTools
+      - $ref: '#/components/schemas/OpenAIChatCompletionToolChoiceFunctionTool'
+        title: OpenAIChatCompletionToolChoiceFunctionTool
+      - $ref: '#/components/schemas/OpenAIChatCompletionToolChoiceCustomTool'
+        title: OpenAIChatCompletionToolChoiceCustomTool
+      title: OpenAIChatCompletionToolChoiceAllowedTools | OpenAIChatCompletionToolChoiceFunctionTool | OpenAIChatCompletionToolChoiceCustomTool
+    OpenAIResponseInputToolChoice:
+      anyOf:
+      - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMode'
+        title: OpenAIResponseInputToolChoiceMode
+      - discriminator:
+          mapping:
+            allowed_tools: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+            custom: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+            file_search: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+            function: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+            mcp: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+            web_search: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            web_search_2025_08_26: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            web_search_preview: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+            web_search_preview_2025_03_11: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+          propertyName: type
+        oneOf:
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceAllowedTools'
+          title: OpenAIResponseInputToolChoiceAllowedTools
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFileSearch'
+          title: OpenAIResponseInputToolChoiceFileSearch
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceWebSearch'
+          title: OpenAIResponseInputToolChoiceWebSearch
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceFunctionTool'
+          title: OpenAIResponseInputToolChoiceFunctionTool
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceMCPTool'
+          title: OpenAIResponseInputToolChoiceMCPTool
+        - $ref: '#/components/schemas/OpenAIResponseInputToolChoiceCustomTool'
+          title: OpenAIResponseInputToolChoiceCustomTool
+        title: OpenAIResponseInputToolChoiceAllowedTools | ... (6 variants)
+      title: OpenAIResponseInputToolChoiceMode
     OpenAIResponseContentPart:
       discriminator:
         mapping: