Register an agent

Introduced 2.12

This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated GitHub issue.

Use this API to register an agent.

Agents may be of the following types:

  • Flow agent
  • Conversational flow agent
  • Conversational agent

For more information about agents, see Agents and tools.

Path and HTTP methods

  1. POST /_plugins/_ml/agents/_register

copy

Request fields

The following table lists the available request fields.

FieldData typeRequired/OptionalAgent typeDescription
nameStringRequiredAllThe agent name.
typeStringRequiredAllThe agent type. Valid values are flow, conversational_flow, and conversational. For more information, see Agents.
descriptionStringOptionalAllA description of the agent.
toolsArrayOptionalAllA list of tools for the agent to execute.
app_typeStringOptionalAllSpecifies an optional agent category. You can then perform operations on all agents in the category. For example, you can delete all messages for RAG agents.
memory.typeStringOptionalconversational_flow, conversationalSpecifies where to store the conversational memory. Currently, the only supported type is conversation_index (store the memory in a conversational system index).
llm.model_idStringRequiredconversationalThe model ID of the LLM to which to send questions.
llm.parameters.response_filterStringRequiredconversationalThe pattern for parsing the LLM response. For each LLM, you need to provide the field where the response is located. For example, for the Anthropic Claude model, the response is located in the completion field, so the pattern is $.completion. For OpenAI models, the pattern is $.choices[0].message.content.
llm.parameters.max_iterationIntegerOptionalconversationalThe maximum number of messages to send to the LLM. Default is 3.

The tools array contains a list of tools for the agent. Each tool contains the following fields.

FieldData typeRequired/OptionalDescription
nameStringOptionalThe tool name. The tool name defaults to the type parameter value. If you need to include multiple tools of the same type in an agent, specify different names for the tools.
typeStringRequiredThe tool type. For a list of supported tools, see Tools.
parametersObjectOptionalThe parameters for this tool. The parameters are highly dependent on the tool type. You can find information about specific tool types in Tools.

Example request: Flow agent

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "Test_Agent_For_RAG",
  4.   "type": "flow",
  5.   "description": "this is a test agent",
  6.   "tools": [
  7.     {
  8.       "name": "vector_tool",
  9.       "type": "VectorDBTool",
  10.       "parameters": {
  11.         "model_id": "zBRyYIsBls05QaITo5ex",
  12.         "index": "my_test_data",
  13.         "embedding_field": "embedding",
  14.         "source_field": [
  15.           "text"
  16.         ],
  17.         "input": "${parameters.question}"
  18.       }
  19.     },
  20.     {
  21.       "type": "MLModelTool",
  22.       "description": "A general tool to answer any question",
  23.       "parameters": {
  24.         "model_id": "NWR9YIsBUysqmzBdifVJ",
  25.         "prompt": "\n\nHuman:You are a professional data analyst. You will always answer question based on the given context first. If the answer is not directly shown in the context, you will analyze the data and find the answer. If you don't know the answer, just say don't know. \n\n Context:\n${parameters.vector_tool.output}\n\nHuman:${parameters.question}\n\nAssistant:"
  26.       }
  27.     }
  28.   ]
  29. }

copy

Example request: Conversational flow agent

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "population data analysis agent",
  4.   "type": "conversational_flow",
  5.   "description": "This is a demo agent for population data analysis",
  6.   "app_type": "rag",
  7.   "memory": {
  8.     "type": "conversation_index"
  9.   },
  10.   "tools": [
  11.     {
  12.       "type": "VectorDBTool",
  13.       "name": "population_knowledge_base",
  14.       "parameters": {
  15.         "model_id": "your_text_embedding_model_id",
  16.         "index": "test_population_data",
  17.         "embedding_field": "population_description_embedding",
  18.         "source_field": [
  19.           "population_description"
  20.         ],
  21.         "input": "${parameters.question}"
  22.       }
  23.     },
  24.     {
  25.       "type": "MLModelTool",
  26.       "name": "bedrock_claude_model",
  27.       "description": "A general tool to answer any question",
  28.       "parameters": {
  29.         "model_id": "your_LLM_model_id",
  30.         "prompt": """
  32. Human:You are a professional data analysist. You will always answer question based on the given context first. If the answer is not directly shown in the context, you will analyze the data and find the answer. If you don't know the answer, just say don't know. 
  34. Context:
  35. ${parameters.population_knowledge_base.output:-}
  37. ${parameters.chat_history:-}
  39. Human:${parameters.question}
  41. Assistant:"""
  42.       }
  43.     }
  44.   ]
  45. }

copy

Example request: Conversational agent

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "Test_Agent_For_ReAct_ClaudeV2",
  4.   "type": "conversational",
  5.   "description": "this is a test agent",
  6.   "app_type": "my chatbot",
  7.   "llm": {
  8.     "model_id": "<llm_model_id>",
  9.     "parameters": {
  10.       "max_iteration": 5,
  11.       "stop_when_no_tool_found": true,
  12.       "response_filter": "$.completion"
  13.     }
  14.   },
  15.   "memory": {
  16.     "type": "conversation_index"
  17.   },
  18.   "tools": [
  19.     {
  20.       "type": "VectorDBTool",
  21.       "name": "VectorDBTool",
  22.       "description": "A tool to search opensearch index with natural language quesiotn. If you don't know answer for some question, you should always try to search data with this tool. Action Input: <natrual language question>",
  23.       "parameters": {
  24.         "model_id": "<embedding_model_id>",
  25.         "index": "<your_knn_index>",
  26.         "embedding_field": "<embedding_filed_name>",
  27.         "source_field": [
  28.           "<source_filed>"
  29.         ],
  30.         "input": "${parameters.question}"
  31.       }
  32.     },
  33.     {
  34.       "type": "CatIndexTool",
  35.       "name": "RetrieveIndexMetaTool",
  36.       "description": "Use this tool to get OpenSearch index information: (health, status, index, uuid, primary count, replica count, docs.count, docs.deleted, store.size, primary.store.size)."
  37.     }
  38.   ]
  39. }

copy

Example response

OpenSearch responds with an agent ID that you can use to refer to the agent:

  1. {
  2.   "agent_id": "bpV_Zo0BRhAwb9PZqGja"
  3. }