feat(api)!: deprecate toolgroup and tool_runtime apis (#4249)

# What does this PR do?
marks `toolgroup` and `tool_runtime` APIs for deprecation 

<!-- If resolving an issue, uncomment and update the line below -->
Closes #4233 and #4061 (partially)

How long do we wait before we remove deprecated APIs?

## 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.* -->

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

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:

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:

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:

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:

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,