计划-执行-反思智能体
3.0 版本引入
这是一个实验性功能，不建议在生产环境中使用。有关该功能的进展更新或如果您想提供反馈，请参阅相关的GitHub 问题。
计划-执行-反思代理旨在解决需要迭代推理和分步执行的复杂任务。这些代理使用一个大型语言模型 (LLM)——即规划器——来创建和更新计划，并使用另一个 LLM（或默认情况下是同一个 LLM）通过内置的对话代理来执行每个单独的步骤。
计划-执行-反思代理分三个阶段工作：
- 规划 – 规划器 LLM 使用可用工具生成初始的分步计划。
- 执行 – 每个步骤都使用对话代理和可用工具顺序执行。
- 重新评估 – 执行每个步骤后，规划器 LLM 使用中间结果重新评估计划。LLM 可以根据新上下文动态调整计划，以跳过、添加或更改步骤。
与对话代理类似，计划-执行-反思代理将 LLM 和代理之间的交互存储在内存索引中。在以下示例中，代理使用 conversation_index 来持久化执行历史，包括用户的问题、中间结果和最终输出。
代理根据工具描述和当前上下文自动选择最适合每个步骤的工具。
代理目前仅支持在每个步骤执行后进行重新评估。这使得代理能够在进入下一步之前，根据中间结果动态调整计划。
创建计划-执行-反思代理
以下示例请求创建了一个带有三个工具的计划-执行-反思代理：
POST /_plugins/_ml/agents/_register
{
"name": "My Plan Execute Reflect Agent",
"type": "plan_execute_and_reflect",
"description": "Agent for dynamic task planning and reasoning",
"llm": {
"model_id": "YOUR_LLM_MODEL_ID",
"parameters": {
"prompt": "${parameters.question}"
}
},
"memory": {
"type": "conversation_index"
},
"parameters": {
"_llm_interface": "YOUR_LLM_INTERFACE"
},
"tools": [
{ "type": "ListIndexTool" },
{ "type": "SearchIndexTool" },
{ "type": "IndexMappingTool" }
],
"app_type": "os_chat"
}
提供工具的详细描述非常重要，这样 LLM 才能决定在何种情况下使用这些工具。
有关注册代理 API 请求字段的更多信息，请参阅请求体字段。
支持的 LLM
计划-执行-反思代理为以下 LLM 提供了内置的函数调用接口：
- Amazon Bedrock 上托管的 Anthropic Claude 3.7 模型
- OpenAI GPT-4o 模型
- Amazon Bedrock 上托管的 DeepSeek-R1 模型
要请求对某个 LLM 的默认支持，请在 ML Commons 仓库中创建功能请求问题。
有关使用计划-执行-反思代理的分步教程，请参阅构建计划-执行-反思代理。
要使用特定模型配置计划-执行-反思代理，您需要修改步骤 1(a)：创建连接器中的连接器，并在步骤 2：创建代理中提供模型特定的 llm_interface 参数
"parameters": {
"_llm_interface": "bedrock/converse/claude"
}
有关 _llm_interface 字段的有效值，请参阅请求体字段。
以下示例提供了对支持的模型进行连接器和代理创建的请求。
Amazon Bedrock 上的 Anthropic Claude
要在 Amazon Bedrock 上为 Anthropic Claude 3.7 Sonnet 模型创建连接器，请使用以下请求：
POST /_plugins/_ml/connectors/_create
{
"name": "Amazon Bedrock Claude 3.7-sonnet connector",
"description": "Connector to Amazon Bedrock service for the Claude model",
"version": 1,
"protocol": "aws_sigv4",
"parameters": {
"region": "your_aws_region",
"service_name": "bedrock",
"model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
},
"credential": {
"access_key": "your_aws_access_key",
"secret_key": "your_aws_secret_key",
"session_token": "your_aws_session_token"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/converse",
"headers": {
"content-type": "application/json"
},
"request_body": "{ \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [${parameters._chat_history:-}{\"role\":\"user\",\"content\":[{\"text\":\"${parameters.prompt}\"}]}${parameters._interactions:-}]${parameters.tool_configs:-} }"
}
]
}
要使用 Anthropic Claude 3.7 Sonnet 模型创建计划-执行-反思代理，请使用以下请求：
POST _plugins/_ml/agents/_register
{
"name": "My Plan Execute and Reflect agent with Claude 3.7",
"type": "plan_execute_and_reflect",
"description": "this is a test agent",
"llm": {
"model_id": "your_llm_model_id",
"parameters": {
"prompt": "${parameters.question}"
}},
"memory": {
"type": "conversation_index"
},
"parameters": {
"_llm_interface": "bedrock/converse/claude"
},
"tools": [
{
"type": "ListIndexTool"
},
{
"type": "SearchIndexTool"
},
{
"type": "IndexMappingTool"
}
]
}
OpenAI GPT-4o
要为 OpenAI GPT-4o 模型创建连接器，请使用以下请求：
POST /_plugins/_ml/connectors/_create
{
"name": "My openai connector: gpt-4",
"description": "The connector to openai chat model",
"version": 1,
"protocol": "http",
"parameters": {
"model": "gpt-4o"
},
"credential": {
"openAI_key": "your_open_ai_key"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://api.openai.com/v1/chat/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"messages\": [{\"role\":\"developer\",\"content\":\"${parameters.system_prompt}\"},${parameters._chat_history:-}{\"role\":\"user\",\"content\":\"${parameters.prompt}\"}${parameters._interactions:-}]${parameters.tool_configs:-} }"
}
]
}
然后注册模型并注册一个代理，在 _llm_interface 字段中指定 openai/v1/chat/completions。
Amazon Bedrock 上的 Deepseek-R1
要在 Amazon Bedrock 上为 DeepSeek-R1 模型创建连接器，请使用以下请求：
POST /_plugins/_ml/connectors/_create
{
"name": "My DeepSeek R1 connector",
"description": "my test connector",
"version": 1,
"protocol": "aws_sigv4",
"parameters": {
"region": "your_region",
"service_name": "bedrock",
"model": "us.deepseek.r1-v1:0"
},
"credential": {
"access_key": "your_access_key",
"secret_key": "your_secret_key",
"session_token": "your_session_token"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/converse",
"headers": {
"content-type": "application/json"
},
"request_body": "{ \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [${parameters._chat_history:-}{\"role\":\"user\",\"content\":[{\"text\":\"${parameters.prompt}\"}]}${parameters._interactions:-}] }"
}
]
}
然后注册模型并注册一个代理，在 _llm_interface 字段中指定 bedrock/converse/deepseek_r1。
由于 Amazon Bedrock 上托管的 Deepseek-R1 模型缺少默认的函数调用支持，因此在代理注册期间提供以下提示作为 executor_system_prompt：
"You are a helpful assistant. You can ask Human to use tools to look up information that may be helpful in answering the users original question. The tools the human can use are:\n[${parameters._tools.toString()}]\n\nIf need to use tool, return which tool should be used and the input to user is enough. User will run the tool to get information. To make it easier for user to parse the response to know whether they should invoke a tool or not, please also return \"stop_reason\", it only return one of two enum values: [end_turn, tool_use], add a random tool call id to differenciate in case same tool invoked multiple times. Tool call id follow this pattern \"tool_use_<random string>\". The random string should be some UUID.\n\nFor example, you should return a json like this if need to use tool:\n{\"stop_reason\": \"tool_use\", \"tool_calls\": [{\"id\":\"tool_use_IIHBxMgOTjGb6ascCiOILg\",tool_name\":\"search_opensearch_index\",\"input\": {\"index\":\"population_data\",\"query\":{\"query\":{\"match\":{\"city\":\"New York City\"}}}}}]}\n\nIf don't need to use tool, return a json like this:\n{\"stop_reason\": \"end_turn\", \"message\": {\"role\":\"user\",\"content\":[{\"text\":\"What is the most popular song on WZPZ?\"}]}}\n\nNOTE: Don't wrap response in markdown ```json<response>```. For example don't return ```json\\n{\"stop_reason\": \"end_turn\", \"message\": {\"role\":\"user\",\"content\":[{\"text\":\"What is the most popular song on WZPZ?\"}]}}```\n"
跟踪代理执行和内存
当您使用代理执行 API 异步执行计划-执行-反思代理时，一旦代理启动，API 将返回规划器代理的 memory_id 和 parent_interaction_id。
在最终响应中，API 还会返回 executor_agent_memory_id 和 executor_agent_parent_interaction_id，它们对应于负责执行计划每个步骤的内部执行器代理。executor_agent_memory_id 和 executor_agent_parent_interaction_id 会在可用时立即在任务中更新，即使在代理完成执行之前也是如此。这使得可以实时跟踪执行过程。
有关完整示例，请参阅构建计划-执行-反思代理。
默认提示
计划-执行-反思代理使用以下预定义提示。您可以通过以下方式提供新提示来自定义它们：
- 在
parameters对象中进行代理注册时 - 在代理执行期间动态设置
规划器模板和提示
要创建自定义规划器提示模板，请修改 planner_prompt_template 参数。以下模板用于要求 LLM 为给定任务制定计划：
${parameters.planner_prompt} \n Objective: ${parameters.user_prompt} \n ${parameters.plan_execute_reflect_response_format}
要创建自定义规划器提示，请修改 planner_prompt 参数。以下提示用于要求 LLM 为给定任务制定计划：
For the given objective, come up with a simple step by step plan. This plan should involve individual tasks, that if executed correctly will yield the correct answer. Do not add any superfluous steps. The result of the final step should be the final answer. Make sure that each step has all the information needed - do not skip steps. At all costs, do not execute the steps. You will be told when to execute the steps.
带历史记录模板的规划器提示
要创建带历史记录模板的自定义规划器提示，请修改 planner_with_history_template 参数。当在代理执行期间提供 memory_id 时，以下模板用于向 LLM 提供有关先前任务的上下文：
${parameters.planner_prompt} \n Objective: ${parameters.user_prompt} \n\n You have currently executed the following steps: \n[${parameters.completed_steps}] \n\n \n ${parameters.plan_execute_reflect_response_format}
反思提示和模板
要创建自定义反思提示模板，请修改 reflect_prompt_template 参数。以下模板用于要求 LLM 根据已完成的步骤重新思考原始计划：
${parameters.planner_prompt} \n Objective: ${parameters.user_prompt} \n Original plan:\n [${parameters.steps}] \n You have currently executed the following steps: \n [${parameters.completed_steps}] \n ${parameters.reflect_prompt} \n ${parameters.plan_execute_reflect_response_format}
要创建自定义反思提示，请修改 reflect_prompt 参数。以下提示用于要求 LLM 重新思考原始计划：
Update your plan accordingly. If no more steps are needed and you can return to the user, then respond with that. Otherwise, fill out the plan. Only add steps to the plan that still NEED to be done. Do not return previously done steps as part of the plan. Please follow the below response format
规划器系统提示
要创建自定义规划器系统提示，请修改 system_prompt 参数。以下是规划器系统提示：
You are part of an OpenSearch cluster. When you deliver your final result, include a comprehensive report. This report MUST:\n1. List every analysis or step you performed.\n2. Summarize the inputs, methods, tools, and data used at each step.\n3. Include key findings from all intermediate steps — do NOT omit them.\n4. Clearly explain how the steps led to your final conclusion.\n5. Return the full analysis and conclusion in the 'result' field, even if some of this was mentioned earlier.\n\nThe final response should be fully self-contained and detailed, allowing a user to understand the full investigation without needing to reference prior messages. Always respond in JSON format.
执行器系统提示
要创建自定义执行器系统提示，请修改 executor_system_prompt 参数。以下是执行器系统提示：
You are a dedicated helper agent working as part of a plan‑execute‑reflect framework. Your role is to receive a discrete task, execute all necessary internal reasoning or tool calls, and return a single, final response that fully addresses the task. You must never return an empty response. If you are unable to complete the task or retrieve meaningful information, you must respond with a clear explanation of the issue or what was missing. Under no circumstances should you end your reply with a question or ask for more information. If you search any index, always include the raw documents in the final result instead of summarizing the content. This is critical to give visibility into what the query retrieved.
我们建议永远不要修改 ${parameters.plan_execute_reflect_response_format}，并始终将其包含在提示模板的末尾。
修改默认提示
要修改提示，请在代理注册期间提供它们：
POST _plugins/_ml/agents/_register
{
"name": "My Plan Execute and Reflect agent with Claude 3.7",
"type": "plan_execute_and_reflect",
"description": "this is a test agent",
"llm": {
"model_id": "your_llm_model_id_from_step1",
"parameters": {
"prompt": "${parameters.question}"
}},
"memory": {
"type": "conversation_index"
},
"parameters": {
"_llm_interface": "bedrock/converse/claude",
"planner_prompt_template": "your_planner_prompt_template",
"planner_prompt": "your_planner_prompt",
"reflect_prompt_template": "your_reflect_prompt_template",
"reflect_prompt": "your_reflect_prompt",
"planner_with_history_template": "your_planner_with_history_template",
"system_prompt": "your_planner_system_prompt",
"executor_system_prompt": "your_executor_system_prompt"
},
"tools": [
{
"type": "ListIndexTool"
},
{
"type": "SearchIndexTool"
},
{
"type": "IndexMappingTool"
}
],
}
您也可以在代理执行期间修改提示：
POST _plugins/_ml/agents/your_agent_id/_execute?async=true
{
"parameters": {
"question": "How many flights from Beijing to Seattle?",
"planner_prompt_template": "your_planner_prompt_template",
"planner_prompt": "your_planner_prompt"
}
}
后续步骤
- 要了解有关注册代理的更多信息，请参阅注册代理 API。
- 有关支持的工具列表，请参阅工具。
- 有关使用计划-执行-反思代理的分步教程，请参阅构建计划-执行-反思代理。
- 有关支持的 API，请参阅代理 API。
- 要在配置自动化中使用代理和工具，请参阅自动化配置。