diff --git a/CHANGELOG.md b/CHANGELOG.md index 3cb728001..b3f214197 100644 --- a/CHANGELOG.md +++ b/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)) diff --git a/spec/namespaces/ml.yaml b/spec/namespaces/ml.yaml index a5775127b..5e0b21eac 100644 --- a/spec/namespaces/ml.yaml +++ b/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 diff --git a/spec/schemas/ml._common.yaml b/spec/schemas/ml._common.yaml index edc648e60..68d36da76 100644 --- a/spec/schemas/ml._common.yaml +++ b/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: diff --git a/tests/plugins/ml/ml/agents/get.yaml b/tests/plugins/ml/ml/agents/get.yaml new file mode 100644 index 000000000..99d41c390 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/plugins/ml/ml/agents/search.yaml b/tests/plugins/ml/ml/agents/search.yaml new file mode 100644 index 000000000..333c34039 --- /dev/null +++ b/tests/plugins/ml/ml/agents/search.yaml @@ -0,0 +1,56 @@ +$schema: ../../../../../json_schemas/test_story.schema.yaml + +description: Test the search of agents. +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: Search agent. + path: /_plugins/_ml/agents/_search + method: GET + request: + payload: + query: + match_all: {} + size: 1000 + response: + status: 200 + - synopsis: Search agent by type. + path: /_plugins/_ml/agents/_search + method: POST + request: + payload: + query: + term: + type: + value: flow + response: + status: 200 \ No newline at end of file