Added ML execute, get, search agent APIs.

Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com>

CHANGELOG.md

@@ -52,6 +52,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `GET /_plugins/_ml/profile`, `GET /_plugins/_ml/profile/models`, `models/{model_id}`, `tasks`, `tasks/{task_id}` ([#787](https://github.com/opensearch-project/opensearch-api-specification/pull/787))
 - Added `GET /_plugins/_ml/stats/`, `stats/{stat}`, `{nodeId}/stats/`, `{nodeId}/stats/{stat}` ([#794](https://github.com/opensearch-project/opensearch-api-specification/pull/794))
 - Added `GET`, `POST /_plugins/_ml/tasks/_search`, `GET /_plugins/_ml/tools`, `tools/{tool_name}` ([#797](https://github.com/opensearch-project/opensearch-api-specification/pull/797))
+- Added `POST /_plugins/_ml/agents/{agent_id}/_execute`, `GET /_plugins/_ml/agents/{agent_id}`, `GET`, `POST /_plugins/_ml/agents/_search` ([#798](https://github.com/opensearch-project/opensearch-api-specification/pull/798))
 
 ### Removed
 - Removed unsupported `_common.mapping:SourceField`'s `mode` field and associated `_common.mapping:SourceFieldMode` enum ([#652](https://github.com/opensearch-project/opensearch-api-specification/pull/652))

spec/namespaces/ml.yaml

@@ -433,22 +433,68 @@ paths:
     post:
       operationId: ml.register_agents.0
       x-operation-group: ml.register_agents
+      x-version-added: '2.13'
       description: Register an agent.
       requestBody:
         $ref: '#/components/requestBodies/ml.register_agents'
       responses:
         '200':
           $ref: '#/components/responses/ml.register_agents@200'
+  /_plugins/_ml/agents/{agent_id}/_execute:
+    post:
+      operationId: ml.execute_agent.0
+      x-operation-group: ml.execute_agent
+      x-version-added: '2.13'
+      description: Execute an agent.
+      parameters:
+        - $ref: '#/components/parameters/ml.execute_agent::path.agent_id'
+      requestBody:
+        $ref: '#/components/requestBodies/ml.execute_agent'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.execute_agent@200'
   /_plugins/_ml/agents/{agent_id}:
+    get:
+      operationId: ml.get_agent.0
+      x-operation-group: ml.get_agent
+      x-version-added: '2.13'
+      description: Get an agent.
+      parameters:
+        - $ref: '#/components/parameters/ml.get_agent::path.agent_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.get_agent@200'
     delete:
       operationId: ml.delete_agent.0
       x-operation-group: ml.delete_agent
+      x-version-added: '2.13'
       description: Delete an agent.
       parameters:
         - $ref: '#/components/parameters/ml.delete_agent::path.agent_id'
       responses:
         '200':
           $ref: '#/components/responses/ml.delete_agent@200'
+  /_plugins/_ml/agents/_search:
+    get:
+      operationId: ml.search_agents.0
+      x-operation-group: ml.search_agents
+      x-version-added: '2.13'
+      description: Search agents.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.search_agents'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.search_agents@200'
+    post:
+      operationId: ml.search_agents.1
+      x-operation-group: ml.search_agents
+      description: Search agents.
+      x-version-added: '2.13'
+      requestBody:
+        $ref: '#/components/requestBodies/ml.search_agents'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.search_agents@200'
   /_plugins/_ml/memory:
     get:
       operationId: ml.get_all_memories.0
@@ -869,9 +915,14 @@ components:
                 description: The model description.
               model_group_id:
                 $ref: '../schemas/_common.yaml#/components/schemas/Id'
+              function_name:
+                type: string
+                description: The function name.
+              connector_id:
+                type: string
+                description: The connector ID.
             required:
               - name
-              - version
     ml.create_model_meta:
       content:
         application/json:
@@ -1273,6 +1324,35 @@ components:
             required:
               - name
               - type
+    ml.execute_agent:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              parameters:
+                $ref: '../schemas/ml._common.yaml#/components/schemas/Parameters'
+              parameters.verbose:
+                type: boolean
+                description: Whether to provide verbose output.
+            required:
+              - parameters
+    ml.search_agents:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              query:
+                $ref: '../schemas/ml._common.yaml#/components/schemas/Query'
+              size:
+                type: integer
+                description: The number of agents to return.
+              sort:
+                type: array
+                items:
+                  $ref: '../schemas/ml._common.yaml#/components/schemas/SortAgent'
+                description: The sort order.
     ml.create_memory:
       content:
         application/json:
@@ -1436,6 +1516,8 @@ components:
                 type: string
               task_id:
                 type: string
+              model_id:
+                type: string
             required:
               - status
               - task_id
@@ -1641,11 +1723,26 @@ components:
             properties:
               agent_id:
                 type: string
+    ml.execute_agent@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/PredictResponse'
+    ml.get_agent@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/GetAgentResponse'
     ml.delete_agent@200:
       content:
         application/json:
           schema:
             $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
+    ml.search_agents@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/SearchAgentsResponse'
     ml.get_memory@200:
       content:
         application/json:
@@ -1972,6 +2069,18 @@ components:
       required: true
       schema:
         type: string
+    ml.execute_agent::path.agent_id:
+      name: agent_id
+      in: path
+      required: true
+      schema:
+        type: string
+    ml.get_agent::path.agent_id:
+      name: agent_id
+      in: path
+      required: true
+      schema:
+        type: string
     ml.delete_agent::path.agent_id:
       name: agent_id
       in: path

spec/schemas/ml._common.yaml

@@ -68,8 +68,7 @@ components:
         _id:
           $ref: '_common.yaml#/components/schemas/Id'
         _score:
-          type: number
-          format: float
+          type: ['null', number]
           description: The score.
         _source:
           $ref: '#/components/schemas/Source'
@@ -251,6 +250,22 @@ components:
         prompt_template:
           type: ['null', string]
           description: The prompt template.
+        type:
+          type: string
+          description: The agent type
+          enum:
+            - conversational
+            - conversational_flow
+            - flow
+        tools:
+          type: array
+          items:
+            $ref: '#/components/schemas/ToolItems'
+        memory:
+          $ref: '#/components/schemas/Memory'
+        app_type:
+          type: string
+          description: The app type.
         is_async:
           type: boolean
           description: Whether the task is asynchronous.
@@ -365,6 +380,9 @@ components:
             description: The output data.
         byte_buffer:
           $ref: '#/components/schemas/ByteBuffer'
+        result:
+          type: string
+          description: The output result.
       required:
         - data
     ByteBuffer:
@@ -450,6 +468,7 @@ components:
           $ref: '#/components/schemas/MatchAllQuery'
         term:
           $ref: '#/components/schemas/Term'
+      additionalProperties: true
     MatchAllQuery:
       type: object
       description: The match all query.
@@ -536,6 +555,8 @@ components:
           $ref: '#/components/schemas/OwnerNameKeyword'
         owner.name.keyword:
           $ref: '#/components/schemas/OwnerNameKeyword'
+        type:
+          $ref: '#/components/schemas/Type'
     Algorithm:
       type: object
       description: The algorithm.
@@ -574,6 +595,17 @@ components:
         boost:
           type: number
           description: Adjust the relevance score of a match.
+    Type:
+      type: object
+      description: The type.
+      properties:
+        value:
+          type: string
+          description: The agent type.
+          enum:
+            - conversational
+            - conversational_flow
+            - flow
     Nested:
       type: object
       description: The nested filter.
@@ -651,6 +683,30 @@ components:
           $ref: '#/components/schemas/SortOrder'
         _score:
           $ref: '#/components/schemas/SortOrder'
+    SortAgent:
+      type: object
+      description: The sort agent query.
+      properties:
+        created_time:
+          $ref: '#/components/schemas/SortOrder'
+        is_hidden:
+          $ref: '#/components/schemas/SortOrder'
+        last_updated_time:
+          $ref: '#/components/schemas/SortOrder'
+        parameters:
+          $ref: '#/components/schemas/SortOrder'
+        tools:
+          $ref: '#/components/schemas/SortOrder'
+        type:
+          $ref: '#/components/schemas/SortOrder'
+        _id:
+          $ref: '#/components/schemas/SortOrder'
+        _index:
+          $ref: '#/components/schemas/SortOrder'
+        _score:
+          $ref: '#/components/schemas/SortOrder'
+        _seq_no:
+          $ref: '#/components/schemas/SortOrder'
     SortMemory:
       type: object
       description: The sort memory query.
@@ -1160,6 +1216,8 @@ components:
           type: string
         parameters:
           $ref: '#/components/schemas/Parameters'
+        include_output_in_agent_response:
+          type: boolean
       additionalProperties: true
     Headers:
       type: object
@@ -1199,6 +1257,38 @@ components:
           description: The last updated time.
     SearchConnectorsResponse:
       $ref: '#/components/schemas/SearchResponse'
+    GetAgentResponse:
+      type: object
+      properties:
+        name:
+          $ref: '_common.yaml#/components/schemas/Name'
+        type:
+          type: string
+          description: The agent type.
+          enum:
+            - conversational
+            - conversational_flow
+            - flow
+        description:
+          type: string
+          description: The agent description.
+        tools:
+          type: array
+          items:
+            $ref: '#/components/schemas/ToolItems'
+        created_time:
+          type: integer
+          format: int64
+          description: The created time.
+        last_updated_time:
+          type: integer
+          format: int64
+          description: The last updated time.
+        is_hidden:
+          type: boolean
+          description: Whether the agent is hidden.
+    SearchAgentsResponse:
+      $ref: '#/components/schemas/SearchResponse'
     SearchMemoryResponse:
       $ref: '#/components/schemas/SearchResponse'
     Message:

tests/plugins/ml/ml/agents/get.yaml

@@ -0,0 +1,42 @@
+$schema: ../../../../../json_schemas/test_story.schema.yaml
+
+description: Test the retrieval of agent information.
+version: '>= 2.13'
+prologues:
+  - path: /_plugins/_ml/agents/_register
+    id: register_agent
+    method: POST
+    request:
+      payload:
+        name: Test_Agent_For_RAG
+        type: flow
+        description: this is a test agent
+        tools:
+          - type: VectorDBTool
+            parameters:
+              model_id: YOUR_TEXT_EMBEDDING_MODEL_ID
+              index: my_test_data
+              embedding_field: embedding
+              source_field:
+                - text
+              input: test_question
+          - type: MLModelTool
+            description: A general tool to answer any question
+            parameters:
+              model_id: YOUR_LLM_MODEL_ID
+    output:
+      test_agent_id: payload.agent_id
+epilogues:
+  - path: /_plugins/_ml/agents/{agent_id}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      agent_id: ${register_agent.test_agent_id}
+chapters:
+  - synopsis: Get agent information.
+    method: GET
+    path: /_plugins/_ml/agents/{agent_id}
+    parameters:
+      agent_id: ${register_agent.test_agent_id}
+    response:
+      status: 200