Link Search Menu Expand Document Documentation Menu

注册代理

2.13 版本引入

使用此 API 注册代理。

代理可以是以下类型:

  • 流 (Flow) 代理
  • 对话流 (Conversational flow) 代理
  • 对话式代理
  • 计划-执行-反思 (Plan-execute-reflect) 代理

有关代理的更多信息,请参阅 代理

端点

POST /_plugins/_ml/agents/_register

请求正文字段

下表列出了可用的请求字段。

字段 数据类型 必需/可选 代理类型 描述
名称 字符串 必需 所有 代理名称。
类型 字符串 必需 所有 代理类型。有效值为 flowconversational_flowconversationalplan_execute_and_reflect。有关更多信息,请参阅 代理
描述 字符串 可选 所有 代理的描述。
工具 数组 可选 所有 代理要执行的工具列表。
应用类型 字符串 可选 所有 指定一个可选的代理类别。然后,您可以对该类别中的所有代理执行操作。例如,您可以删除所有 RAG 代理的消息。
memory.type 字符串 可选 conversational_flow, conversational 指定存储对话内存的位置。目前,唯一支持的类型是 conversation_index (将内存存储在对话系统索引中)。
llm.model_id 字符串 必需 对话式 用于发送问题给 LLM 的模型 ID。
llm.parameters.response_filter 字符串 必需 对话式 解析 LLM 响应的模式。对于每个 LLM,您需要提供响应所在的字段。例如,对于 Anthropic Claude 模型,响应位于 completion 字段中,因此模式为 $.completion。对于 OpenAI 模型,模式为 $.choices[0].message.content
llm.parameters.max_iteration 整数 可选 对话式 发送到 LLM 的最大消息数。默认值为 10
参数 对象 可选 所有 代理参数,可用于控制代理执行的 max_steps,修改默认提示等。
parameters.executor_agent_id 整数 可选 计划-执行-反思 plan_execute_and_reflect 代理内部使用一个 conversational 代理来执行每个步骤。默认情况下,此执行器代理使用与 llm 配置中指定的计划模型相同的模型。要使用不同的模型执行步骤,请使用另一个模型创建 conversational 代理,并将代理 ID 传递到此字段。如果您想对计划和执行使用不同的模型,这会很有用。
parameters.max_steps 整数 可选 计划-执行-反思 LLM 执行的最大步数。默认值为 20
parameters.executor_max_iterations 整数 可选 计划-执行-反思 执行器代理发送到 LLM 的最大消息数。默认值为 20
parameters._llm_interface 字符串 必需 plan_execute_and_reflect, conversational 在使用函数调用时,指定如何解析 LLM 输出。有效值为
- bedrock/converse/claude: 托管在 Amazon Bedrock 上的 Anthropic Claude 对话模型
- bedrock/converse/deepseek_r1: 托管在 Amazon Bedrock 上的 DeepSeek-R1 模型
- openai/v1/chat/completions: 托管在 OpenAI 上的 OpenAI 聊天完成模型。每个接口都定义了一个默认的响应模式和函数调用解析器。

tools 数组包含代理的工具列表。每个工具包含以下字段。

字段 数据类型 必需/可选 描述
类型 字符串 必需 工具类型。有关支持的工具列表,请参阅 工具
名称 字符串 可选 工具名称。工具名称默认为 type 参数值。如果您需要在代理中包含多个相同类型的工具,请为这些工具指定不同的名称。
描述 字符串 可选 工具描述。默认为指定类型的内置描述。
参数 对象 可选 此工具的参数。参数高度依赖于工具类型。您可以在 工具 中找到有关特定工具类型的信息。
attributes.input_schema 对象 可选 此工具的预期输入格式,定义为 JSON 模式。用于定义 LLM 调用工具时应遵循的结构。
attributes.strict 布尔型 可选 函数调用是否可靠地遵循输入模式。

请求示例:流代理

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_RAG",
  "type": "flow",
  "description": "this is a test agent",
  "tools": [
    {
      "name": "vector_tool",
      "type": "VectorDBTool",
      "parameters": {
        "model_id": "zBRyYIsBls05QaITo5ex",
        "index": "my_test_data",
        "embedding_field": "embedding",
        "source_field": [
          "text"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "MLModelTool",
      "description": "A general tool to answer any question",
      "parameters": {
        "model_id": "NWR9YIsBUysqmzBdifVJ",
        "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:"
      }
    }
  ]
}

请求示例:对话流代理

POST /_plugins/_ml/agents/_register
{
  "name": "population data analysis agent",
  "type": "conversational_flow",
  "description": "This is a demo agent for population data analysis",
  "app_type": "rag",
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "VectorDBTool",
      "name": "population_knowledge_base",
      "parameters": {
        "model_id": "your_text_embedding_model_id",
        "index": "test_population_data",
        "embedding_field": "population_description_embedding",
        "source_field": [
          "population_description"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "MLModelTool",
      "name": "bedrock_claude_model",
      "description": "A general tool to answer any question",
      "parameters": {
        "model_id": "your_LLM_model_id",
        "prompt": """

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. 

Context:
${parameters.population_knowledge_base.output:-}

${parameters.chat_history:-}

Human:${parameters.question}

Assistant:"""
      }
    }
  ]
}

请求示例:对话式代理

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_ReAct_ClaudeV2",
  "type": "conversational",
  "description": "this is a test agent",
  "app_type": "my chatbot",
  "llm": {
    "model_id": "<llm_model_id>",
    "parameters": {
      "max_iteration": 5,
      "stop_when_no_tool_found": true,
      "response_filter": "$.completion"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "VectorDBTool",
      "name": "VectorDBTool",
      "description": "A tool to search opensearch index with natural language question. If you don't know answer for some question, you should always try to search data with this tool. Action Input: <natural language question>",
      "parameters": {
        "model_id": "<embedding_model_id>",
        "index": "<your_knn_index>",
        "embedding_field": "<embedding_filed_name>",
        "source_field": [
          "<source_filed>"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "ListIndexTool",
      "name": "RetrieveIndexMetaTool",
      "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)."
    }
  ]
}

请求示例:计划-执行-反思代理

3.0 版本引入

POST /_plugins/_ml/agents/_register
{
  "name": "My plan execute and reflect agent",
  "type": "plan_execute_and_reflect",
  "description": "this is a test agent",
  "llm": {
    "model_id": "<llm_model_id>",
    "parameters": {
      "prompt": "${parameters.question}"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "<llm_interface>"
  },
  "tools": [
    {
      "type": "ListIndexTool"
    },
    {
      "type": "SearchIndexTool"
    },
    {
      "type": "IndexMappingTool"
    }
  ],
  "app_type": "os_chat"
}

示例响应

OpenSearch 返回一个代理 ID,您可以使用它来引用该代理

{
  "agent_id": "bpV_Zo0BRhAwb9PZqGja"
}
剩余 350 字符

有问题?

想做贡献?