feat(api): deprecate toolgroup and tool_runtime apis

Closes #4233 and #4061 (partially) Signed-off-by: Jaideep Rao <jrao@redhat.com>
2025-12-03 01:48:05 +00:00 · 2025-11-27 22:16:28 +05:30 · 2025-11-27 22:16:28 +05:30 · b54df67589
commit b54df67589
parent 618c03405c
5 changed files with 175 additions and 234 deletions
--- a/client-sdks/stainless/openapi.yml
+++ b/client-sdks/stainless/openapi.yml
@ -2091,6 +2091,7 @@ paths:
            schema:
              $ref: '#/components/schemas/InvokeToolRequest'
        required: true
+      deprecated: true
  /v1/tool-runtime/list-tools:
    get:
      responses:
@ -2142,6 +2143,7 @@ paths:
          - $ref: '#/components/schemas/URL'
          - type: 'null'
          title: Mcp Endpoint
+      deprecated: true
  /v1/toolgroups:
    get:
      responses:
@ -2168,6 +2170,7 @@ paths:
      summary: List Tool Groups
      description: List tool groups with optional provider.
      operationId: list_tool_groups_v1_toolgroups_get
+      deprecated: true
    post:
      responses:
        '400':
@ -2229,6 +2232,7 @@ paths:
        schema:
          type: string
        description: 'Path parameter: toolgroup_id'
+      deprecated: true
    delete:
      responses:
        '400':
@ -2293,6 +2297,7 @@ paths:
          - type: string
          - type: 'null'
          title: Toolgroup Id
+      deprecated: true
  /v1/tools/{tool_name}:
    get:
      responses:
@ -2326,6 +2331,7 @@ paths:
        schema:
          type: string
        description: 'Path parameter: tool_name'
+      deprecated: true
  /v1/vector-io/insert:
    post:
      responses:
--- a/docs/static/deprecated-llama-stack-spec.yaml
+++ b/docs/static/deprecated-llama-stack-spec.yaml
@ -378,6 +378,91 @@ paths:
          type: string
        description: 'Path parameter: identifier'
      deprecated: true
+  /v1/tool-runtime/invoke:
+    post:
+      responses:
+        '200':
+          description: A ToolInvocationResult.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolInvocationResult'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Tool Runtime
+      summary: Invoke Tool
+      description: Run a tool with the given arguments.
+      operationId: invoke_tool_v1_tool_runtime_invoke_post
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InvokeToolRequest'
+        required: true
+      deprecated: true
+  /v1/tool-runtime/list-tools:
+    get:
+      responses:
+        '200':
+          description: A ListToolDefsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListToolDefsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Tool Runtime
+      summary: List Runtime Tools
+      description: List all tools in the runtime.
+      operationId: list_runtime_tools_v1_tool_runtime_list_tools_get
+      parameters:
+      - name: authorization
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Authorization
+      - name: tool_group_id
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Tool Group Id
+      - name: mcp_endpoint
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+          - type: 'null'
+          title: Mcp Endpoint
+      deprecated: true
  /v1/toolgroups:
    get:
      responses:
@ -404,6 +489,7 @@ paths:
      summary: List Tool Groups
      description: List tool groups with optional provider.
      operationId: list_tool_groups_v1_toolgroups_get
+      deprecated: true
    post:
      responses:
        '400':
@ -465,6 +551,7 @@ paths:
        schema:
          type: string
        description: 'Path parameter: toolgroup_id'
+      deprecated: true
    delete:
      responses:
        '400':
@ -494,6 +581,76 @@ paths:
          type: string
        description: 'Path parameter: toolgroup_id'
      deprecated: true
+  /v1/tools:
+    get:
+      responses:
+        '200':
+          description: A ListToolDefsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListToolDefsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Tool Groups
+      summary: List Tools
+      description: List tools with optional tool group.
+      operationId: list_tools_v1_tools_get
+      parameters:
+      - name: toolgroup_id
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Toolgroup Id
+      deprecated: true
+  /v1/tools/{tool_name}:
+    get:
+      responses:
+        '200':
+          description: A ToolDef.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolDef'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Tool Groups
+      summary: Get Tool
+      description: Get a tool by its name.
+      operationId: get_tool_v1_tools__tool_name__get
+      parameters:
+      - name: tool_name
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: tool_name'
+      deprecated: true
  /v1beta/datasets:
    get:
      responses:
--- a/docs/static/llama-stack-spec.yaml
+++ b/docs/static/llama-stack-spec.yaml
@ -1872,216 +1872,6 @@ paths:
        schema:
          type: string
        description: 'Path parameter: identifier'
-  /v1/tool-runtime/invoke:
-    post:
-      responses:
-        '200':
-          description: A ToolInvocationResult.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ToolInvocationResult'
-        '400':
-          description: Bad Request
-          $ref: '#/components/responses/BadRequest400'
-        '429':
-          description: Too Many Requests
-          $ref: '#/components/responses/TooManyRequests429'
-        '500':
-          description: Internal Server Error
-          $ref: '#/components/responses/InternalServerError500'
-        default:
-          description: Default Response
-          $ref: '#/components/responses/DefaultError'
-      tags:
-      - Tool Runtime
-      summary: Invoke Tool
-      description: Run a tool with the given arguments.
-      operationId: invoke_tool_v1_tool_runtime_invoke_post
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/InvokeToolRequest'
-        required: true
-  /v1/tool-runtime/list-tools:
-    get:
-      responses:
-        '200':
-          description: A ListToolDefsResponse.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ListToolDefsResponse'
-        '400':
-          $ref: '#/components/responses/BadRequest400'
-          description: Bad Request
-        '429':
-          $ref: '#/components/responses/TooManyRequests429'
-          description: Too Many Requests
-        '500':
-          $ref: '#/components/responses/InternalServerError500'
-          description: Internal Server Error
-        default:
-          $ref: '#/components/responses/DefaultError'
-          description: Default Response
-      tags:
-      - Tool Runtime
-      summary: List Runtime Tools
-      description: List all tools in the runtime.
-      operationId: list_runtime_tools_v1_tool_runtime_list_tools_get
-      parameters:
-      - name: authorization
-        in: query
-        required: false
-        schema:
-          anyOf:
-          - type: string
-          - type: 'null'
-          title: Authorization
-      - name: tool_group_id
-        in: query
-        required: false
-        schema:
-          anyOf:
-          - type: string
-          - type: 'null'
-          title: Tool Group Id
-      - name: mcp_endpoint
-        in: query
-        required: false
-        schema:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-          - type: 'null'
-          title: Mcp Endpoint
-  /v1/toolgroups:
-    get:
-      responses:
-        '200':
-          description: A ListToolGroupsResponse.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ListToolGroupsResponse'
-        '400':
-          description: Bad Request
-          $ref: '#/components/responses/BadRequest400'
-        '429':
-          description: Too Many Requests
-          $ref: '#/components/responses/TooManyRequests429'
-        '500':
-          description: Internal Server Error
-          $ref: '#/components/responses/InternalServerError500'
-        default:
-          description: Default Response
-          $ref: '#/components/responses/DefaultError'
-      tags:
-      - Tool Groups
-      summary: List Tool Groups
-      description: List tool groups with optional provider.
-      operationId: list_tool_groups_v1_toolgroups_get
-  /v1/toolgroups/{toolgroup_id}:
-    get:
-      responses:
-        '200':
-          description: A ToolGroup.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ToolGroup'
-        '400':
-          description: Bad Request
-          $ref: '#/components/responses/BadRequest400'
-        '429':
-          description: Too Many Requests
-          $ref: '#/components/responses/TooManyRequests429'
-        '500':
-          description: Internal Server Error
-          $ref: '#/components/responses/InternalServerError500'
-        default:
-          description: Default Response
-          $ref: '#/components/responses/DefaultError'
-      tags:
-      - Tool Groups
-      summary: Get Tool Group
-      description: Get a tool group by its ID.
-      operationId: get_tool_group_v1_toolgroups__toolgroup_id__get
-      parameters:
-      - name: toolgroup_id
-        in: path
-        required: true
-        schema:
-          type: string
-        description: 'Path parameter: toolgroup_id'
-  /v1/tools:
-    get:
-      responses:
-        '200':
-          description: A ListToolDefsResponse.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ListToolDefsResponse'
-        '400':
-          $ref: '#/components/responses/BadRequest400'
-          description: Bad Request
-        '429':
-          $ref: '#/components/responses/TooManyRequests429'
-          description: Too Many Requests
-        '500':
-          $ref: '#/components/responses/InternalServerError500'
-          description: Internal Server Error
-        default:
-          $ref: '#/components/responses/DefaultError'
-          description: Default Response
-      tags:
-      - Tool Groups
-      summary: List Tools
-      description: List tools with optional tool group.
-      operationId: list_tools_v1_tools_get
-      parameters:
-      - name: toolgroup_id
-        in: query
-        required: false
-        schema:
-          anyOf:
-          - type: string
-          - type: 'null'
-          title: Toolgroup Id
-  /v1/tools/{tool_name}:
-    get:
-      responses:
-        '200':
-          description: A ToolDef.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ToolDef'
-        '400':
-          description: Bad Request
-          $ref: '#/components/responses/BadRequest400'
-        '429':
-          description: Too Many Requests
-          $ref: '#/components/responses/TooManyRequests429'
-        '500':
-          description: Internal Server Error
-          $ref: '#/components/responses/InternalServerError500'
-        default:
-          description: Default Response
-          $ref: '#/components/responses/DefaultError'
-      tags:
-      - Tool Groups
-      summary: Get Tool
-      description: Get a tool by its name.
-      operationId: get_tool_v1_tools__tool_name__get
-      parameters:
-      - name: tool_name
-        in: path
-        required: true
-        schema:
-          type: string
-        description: 'Path parameter: tool_name'
  /v1/vector-io/insert:
    post:
      responses:
@ -8133,24 +7923,6 @@ components:
      required:
      - data
      title: ListShieldsResponse
-    InvokeToolRequest:
-      properties:
-        tool_name:
-          type: string
-          title: Tool Name
-        kwargs:
-          additionalProperties: true
-          type: object
-          title: Kwargs
-        authorization:
-          anyOf:
-          - type: string
-          - type: 'null'
-      type: object
-      required:
-      - tool_name
-      - kwargs
-      title: InvokeToolRequest
    ImageContentItem:
      description: A image content item
      properties:
--- a/docs/static/stainless-llama-stack-spec.yaml
+++ b/docs/static/stainless-llama-stack-spec.yaml
@ -2091,6 +2091,7 @@ paths:
            schema:
              $ref: '#/components/schemas/InvokeToolRequest'
        required: true
+      deprecated: true
  /v1/tool-runtime/list-tools:
    get:
      responses:
@ -2142,6 +2143,7 @@ paths:
          - $ref: '#/components/schemas/URL'
          - type: 'null'
          title: Mcp Endpoint
+      deprecated: true
  /v1/toolgroups:
    get:
      responses:
@ -2168,6 +2170,7 @@ paths:
      summary: List Tool Groups
      description: List tool groups with optional provider.
      operationId: list_tool_groups_v1_toolgroups_get
+      deprecated: true
    post:
      responses:
        '400':
@ -2229,6 +2232,7 @@ paths:
        schema:
          type: string
        description: 'Path parameter: toolgroup_id'
+      deprecated: true
    delete:
      responses:
        '400':
@ -2293,6 +2297,7 @@ paths:
          - type: string
          - type: 'null'
          title: Toolgroup Id
+      deprecated: true
  /v1/tools/{tool_name}:
    get:
      responses:
@ -2326,6 +2331,7 @@ paths:
        schema:
          type: string
        description: 'Path parameter: tool_name'
+      deprecated: true
  /v1/vector-io/insert:
    post:
      responses:
--- a/src/llama_stack_api/tools.py
+++ b/src/llama_stack_api/tools.py
@ -126,7 +126,7 @@ class ToolGroups(Protocol):
        """
        ...

-    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
    async def get_tool_group(
        self,
        toolgroup_id: str,
@ -138,7 +138,7 @@ class ToolGroups(Protocol):
        """
        ...

-    @webmethod(route="/toolgroups", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/toolgroups", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
    async def list_tool_groups(self) -> ListToolGroupsResponse:
        """List tool groups with optional provider.

@ -146,7 +146,7 @@ class ToolGroups(Protocol):
        """
        ...

-    @webmethod(route="/tools", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/tools", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
    async def list_tools(self, toolgroup_id: str | None = None) -> ListToolDefsResponse:
        """List tools with optional tool group.

@ -155,7 +155,7 @@ class ToolGroups(Protocol):
        """
        ...

-    @webmethod(route="/tools/{tool_name:path}", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/tools/{tool_name:path}", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
    async def get_tool(
        self,
        tool_name: str,
@ -193,7 +193,7 @@ class ToolRuntime(Protocol):
    tool_store: ToolStore | None = None

    # TODO: This needs to be renamed once OPEN API generator name conflict issue is fixed.
-    @webmethod(route="/tool-runtime/list-tools", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/tool-runtime/list-tools", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
    async def list_runtime_tools(
        self,
        tool_group_id: str | None = None,
@ -209,7 +209,7 @@ class ToolRuntime(Protocol):
        """
        ...

-    @webmethod(route="/tool-runtime/invoke", method="POST", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/tool-runtime/invoke", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
    async def invoke_tool(
        self,
        tool_name: str,