From 0dfe51df93cfec27f7dcc7498be3c591ada797b5 Mon Sep 17 00:00:00 2001 From: Mingshi Liu Date: Wed, 1 Oct 2025 16:18:07 -0700 Subject: [PATCH 01/11] draft for scratchpad tools Signed-off-by: Mingshi Liu --- .../agents-tools/tools/scratchpad-tools.md | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 _ml-commons-plugin/agents-tools/tools/scratchpad-tools.md diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md new file mode 100644 index 00000000000..356de76eaa8 --- /dev/null +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -0,0 +1,191 @@ +--- +layout: default +title: Scratchpad tools +has_children: false +has_toc: false +nav_order: 60 +parent: Tools +grand_parent: Agents and tools +--- + + +# Scratchpad tools +**Introduced 3.3** +{: .label .label-purple } + + +The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadTool`, which enable agents to store and retrieve intermediate thoughts and results in persistent memory. These tools allow agents to break down complex tasks into smaller steps, maintain state across interactions, and facilitate communication between multiple agents. + +## Use cases + +- **Task decomposition**: Store research plans, intermediate findings, and progress notes during multi-step operations +- **State persistence**: Maintain context and accumulated knowledge across agent interactions +- **Inter-agent communication**: Share information between agents by writing to another agent's scratchpad +- **Research workflows**: Save key findings after searches to build comprehensive responses + +## Step 1: Register and deploy a model + +Register a conversational model that supports the agent framework. The following example uses Anthropic Claude: + +```json +POST /_plugins/_ml/models/_register?deploy=true +{ + "name": "Claude Sonnet for Research Agent", + "function_name": "remote", + "description": "Claude model for research agent with scratchpad", + "connector": { + "name": "Bedrock Claude Sonnet Connector", + "description": "Amazon Bedrock connector for Claude Sonnet", + "version": 1, + "protocol": "aws_sigv4", + "parameters": { + "region": "us-east-1", + "service_name": "bedrock", + "model": "anthropic.claude-3-5-sonnet-20241022-v2: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.messages}, "inferenceConfig": {"maxTokens": 8000, "temperature": 0}}""" + } + ] + } +} +``` +{% include copy-curl.html %} + +## Step 2: Register an agent with scratchpad tools + +Register a conversational agent that includes both scratchpad tools along with other research tools: + +```json +POST /_plugins/_ml/agents/_register +{ + "name": "Research Agent with Scratchpad", + "type": "conversational", + "description": "Research assistant with persistent scratchpad memory", + "app_type": "rag", + "llm": { + "model_id": "your-model-id", + "parameters": { + "max_iteration": 50, + "system_prompt": "You are a sophisticated research assistant with access to OpenSearch indices and a persistent scratchpad for note-taking.\n\nYour Research Workflow:\n1. Check Scratchpad: Before starting a new research task, check your scratchpad to see if you have any relevant information already saved\n2. Create Research Plan: Create a structured research plan\n3. Write to Scratchpad: Save the research plan and any important information to your scratchpad\n4. Use Search: Gather information using OpenSearch search queries\n5. Update Scratchpad: After each search, update your scratchpad with new findings\n6. Iterate: Repeat searching and updating until you have comprehensive information\n7. Complete Task: Provide a thorough response based on your accumulated research\n\nAlways maintain organized notes in your scratchpad and build upon previous research systematically.", + "prompt": "${parameters.question}" + } + }, + "memory": { + "type": "conversation_index" + }, + "parameters": { + "_llm_interface": "bedrock/converse/claude" + }, + "tools": [ + { + "type": "SearchIndexTool" + }, + { + "type": "ListIndexTool" + }, + { + "type": "IndexMappingTool" + }, + { + "type": "ReadFromScratchPadTool", + "name": "ReadFromScratchPadTool", + "parameters": { + "persistent_notes": "You are a helpful researcher. Before making searches, use the listIndexTool to discover available indices. Write down important notes after using tools." + } + }, + { + "type": "WriteToScratchPadTool", + "name": "WriteToScratchPadTool" + } + ] +} +``` +{% include copy-curl.html %} + +## Step 3: Execute the agent + +Execute the agent with a research question: + +```json +POST /_plugins/_ml/agents/your-agent-id/_execute?async=true +{ + "parameters": { + "question": "How many residents are in New York?" + } +} +``` +{% include copy-curl.html %} + +The agent will: +1. Read from its scratchpad to check for existing relevant information +2. Create and save a research plan to the scratchpad +3. Execute searches and update the scratchpad with findings +4. Provide a comprehensive answer based on accumulated research + +## Tool parameters + +### ReadFromScratchPadTool + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created + +### WriteToScratchPadTool + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`notes` | String | Required (at execution) | The content to write to the scratchpad + +## Execute parameters + +When executing an agent with scratchpad tools, provide the following parameters: + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`question` | String | Required | The research question or task for the agent to work on +`notes` | String | Optional | Specific notes to write to the scratchpad (when using WriteToScratchPadTool directly) + +## Viewing scratchpad activity + +You can monitor how the agent uses the scratchpad by examining the execution traces: + +```json +GET /_plugins/_ml/memory/message/your-memory-id/traces?next_token=0 +``` +{% include copy-curl.html %} + +The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent builds up its knowledge over time. + +## Inter-agent communication + +Scratchpad tools can facilitate communication between multiple agents. For example, a planning agent can write an execution plan to an executor agent's scratchpad: + +1. **Planning Agent**: Creates a detailed plan and writes it to the executor's scratchpad +2. **Executor Agent**: Reads the plan from its scratchpad before beginning task execution + +This enables sophisticated multi-agent workflows where agents can coordinate and share context effectively. + +## Best practices + +- **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad +- **Regular updates**: Have agents update the scratchpad after each significant step or finding +- **Clear communication**: When using inter-agent communication, establish clear conventions for scratchpad content format +- **Memory management**: Consider the scratchpad as persistent memory that accumulates over the agent's lifetime + +## Related pages + +- [Agents and tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/) +- [Conversational agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) From a2247074308aceb80f0a0bc1d224f247f3194732 Mon Sep 17 00:00:00 2001 From: Mingshi Liu Date: Fri, 3 Oct 2025 14:48:01 -0700 Subject: [PATCH 02/11] add details to scratch pads tools Signed-off-by: Mingshi Liu --- _ml-commons-plugin/agents-tools/tools/scratchpad-tools.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 356de76eaa8..8dfbbb492a6 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -148,6 +148,7 @@ Parameter | Type | Required/Optional | Description Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `notes` | String | Required (at execution) | The content to write to the scratchpad +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation ## Execute parameters From 75e15d241a677be0efe33a7f8f67e05ac576bc32 Mon Sep 17 00:00:00 2001 From: Mingshi Liu Date: Fri, 10 Oct 2025 14:17:01 -0700 Subject: [PATCH 03/11] add tool execute example Signed-off-by: Mingshi Liu --- .../agents-tools/tools/scratchpad-tools.md | 211 ++++++++++++++---- 1 file changed, 167 insertions(+), 44 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 8dfbbb492a6..cf8ed37c592 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -14,14 +14,157 @@ grand_parent: Agents and tools {: .label .label-purple } -The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadTool`, which enable agents to store and retrieve intermediate thoughts and results in persistent memory. These tools allow agents to break down complex tasks into smaller steps, maintain state across interactions, and facilitate communication between multiple agents. +The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadTool`, which enable agents to store and retrieve intermediate thoughts and results during runtime. These tools serve as temporary memory for a single agent execution session, allowing agents to take notes and store important findings during tool executions. + +**Important**: The scratchpad acts as runtime memory that persists only during a single agent execution. When you call the agent's `_execute` API, a new scratchpad is created for that session. All notes and data, except persistent_notes, are cleared when the execution completes, ensuring each execution starts with a fresh scratchpad. ## Use cases -- **Task decomposition**: Store research plans, intermediate findings, and progress notes during multi-step operations -- **State persistence**: Maintain context and accumulated knowledge across agent interactions -- **Inter-agent communication**: Share information between agents by writing to another agent's scratchpad -- **Research workflows**: Save key findings after searches to build comprehensive responses +- **Task decomposition**: Store research plans, intermediate findings, and progress notes during multi-step operations within a single execution +- **Temporary state management**: Maintain context and accumulated knowledge during the current agent execution session +- **Multi-step workflows**: Save key findings after searches to build comprehensive responses in complex tasks +- **Execution planning**: Store and reference step-by-step plans during complex operations + +## Tool parameters + +### ReadFromScratchPadTool + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created + + +You can directly use the tools API to execute ReadFromScratchPadTool and test the tool response before registering it with your agents. + +```json +POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool +{ + "parameters": { + "persistent_notes": "You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used." + } +} +``` +{% include copy-curl.html %} + +When giving persistent_notes, you will see when tool response, it will try to show the persistent notes given in the response. + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Notes from scratchpad:\n- You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used." + } + ] + } + ] +} +``` + +You can also test with empty persistent notes. + +```json +POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool +{ + "parameters": { + "persistent_notes": "" + } +} +``` + +You will get a response about empty scratchpad. + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Scratchpad is empty." + } + ] + } + ] +} +``` + +### WriteToScratchPadTool + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`notes` | String | Required (at execution) | The content to write to the scratchpad +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation + +## Execute parameters + +When executing the scratchpad tools, provide the following parameters: + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`notes` | String | Optional | Specific notes to write to the scratchpad (when using WriteToScratchPadTool directly) + +You can directly use the tools API to execute WriteToScratchPadTool and test the tool response before registering it with your agents. + +```json +POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool +{ + "parameters": { + "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" + } +} +``` +{% include copy-curl.html %} + +You can see the sample response from the tool output as follows: +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Wrote to scratchpad: Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" + } + ] + } + ] +} +``` +you can opt to set `return_history` parameter to `true` to get the full scratchpad content after writing. + +```json +POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool +{ + "parameters": { + "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n", + "return_history": true + } +} +``` +{% include copy-curl.html %} + +You can see the full content in the response: + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Scratchpad updated. Full content:\n- Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" + } + ] + } + ] +} +``` +{% include copy-curl.html %} + +## Example: Building a research agent with scratchpad tools ## Step 1: Register and deploy a model @@ -44,9 +187,9 @@ POST /_plugins/_ml/models/_register?deploy=true "model": "anthropic.claude-3-5-sonnet-20241022-v2:0" }, "credential": { - "access_key": "your-aws-access-key", - "secret_key": "your-aws-secret-key", - "session_token": "your-aws-session-token" + "access_key": "${AWS_ACCESS_KEY_ID}", + "secret_key": "${AWS_SECRET_ACCESS_KEY}", + "session_token": "${AWS_SESSION_TOKEN}" }, "actions": [ { @@ -79,7 +222,7 @@ POST /_plugins/_ml/agents/_register "model_id": "your-model-id", "parameters": { "max_iteration": 50, - "system_prompt": "You are a sophisticated research assistant with access to OpenSearch indices and a persistent scratchpad for note-taking.\n\nYour Research Workflow:\n1. Check Scratchpad: Before starting a new research task, check your scratchpad to see if you have any relevant information already saved\n2. Create Research Plan: Create a structured research plan\n3. Write to Scratchpad: Save the research plan and any important information to your scratchpad\n4. Use Search: Gather information using OpenSearch search queries\n5. Update Scratchpad: After each search, update your scratchpad with new findings\n6. Iterate: Repeat searching and updating until you have comprehensive information\n7. Complete Task: Provide a thorough response based on your accumulated research\n\nAlways maintain organized notes in your scratchpad and build upon previous research systematically.", + "system_prompt": "You are a sophisticated research assistant with access to OpenSearch indices and a persistent scratchpad for note-taking.\n\nYour Research Workflow:\n1. Check Scratchpad: Before starting a new research task, check your scratchpad to see if you have any relevant information already saved\n2. Create Research Plan: Create a structured research plan\n3. Write to Scratchpad: Save the research plan and any important information to your scratchpad\n4. Use Search: Gather information using OpenSearch search queries\n5. Update Scratchpad: After each search, update your scratchpad with new findings\n6. Iterate: Repeat searching and updating until you have comprehensive information\n7. Complete Task: Provide a thorough response based on your accumulated research\n\nRemember: Your scratchpad is temporary memory for this execution session only. Use it to organize your thoughts and findings during this task.", "prompt": "${parameters.question}" } }, @@ -103,7 +246,7 @@ POST /_plugins/_ml/agents/_register "type": "ReadFromScratchPadTool", "name": "ReadFromScratchPadTool", "parameters": { - "persistent_notes": "You are a helpful researcher. Before making searches, use the listIndexTool to discover available indices. Write down important notes after using tools." + "persistent_notes": "You are a helpful researcher. Before making searches, use the ListIndexTool to discover available indices. Write down important notes after using tools." } }, { @@ -120,7 +263,7 @@ POST /_plugins/_ml/agents/_register Execute the agent with a research question: ```json -POST /_plugins/_ml/agents/your-agent-id/_execute?async=true +POST /_plugins/_ml/agents//_execute?async=true { "parameters": { "question": "How many residents are in New York?" @@ -129,62 +272,42 @@ POST /_plugins/_ml/agents/your-agent-id/_execute?async=true ``` {% include copy-curl.html %} + The agent will: -1. Read from its scratchpad to check for existing relevant information +1. Read from its scratchpad to check for existing relevant information (starts empty for new executions) 2. Create and save a research plan to the scratchpad 3. Execute searches and update the scratchpad with findings 4. Provide a comprehensive answer based on accumulated research -## Tool parameters - -### ReadFromScratchPadTool - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created - -### WriteToScratchPadTool - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`notes` | String | Required (at execution) | The content to write to the scratchpad -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation - -## Execute parameters - -When executing an agent with scratchpad tools, provide the following parameters: - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`question` | String | Required | The research question or task for the agent to work on -`notes` | String | Optional | Specific notes to write to the scratchpad (when using WriteToScratchPadTool directly) +When using the `agents//_execute` API, you will get a `parent_interaction_id` and `memory_id` in the response. Note the `parent_interaction_id` for later tracing steps. ## Viewing scratchpad activity You can monitor how the agent uses the scratchpad by examining the execution traces: ```json -GET /_plugins/_ml/memory/message/your-memory-id/traces?next_token=0 +GET /_plugins/_ml/memory/message//traces?next_token=0 ``` {% include copy-curl.html %} -The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent builds up its knowledge over time. +The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent builds up its knowledge during the execution session. -## Inter-agent communication +## Scratchpad lifecycle -Scratchpad tools can facilitate communication between multiple agents. For example, a planning agent can write an execution plan to an executor agent's scratchpad: +The scratchpad follows a simple lifecycle: -1. **Planning Agent**: Creates a detailed plan and writes it to the executor's scratchpad -2. **Executor Agent**: Reads the plan from its scratchpad before beginning task execution +1. **Creation**: A new, empty scratchpad is created when an agent execution begins +2. **Usage**: During execution, the agent can read from and write to the scratchpad multiple times +3. **Cleanup**: The scratchpad is automatically cleared when the execution completes -This enables sophisticated multi-agent workflows where agents can coordinate and share context effectively. +Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring executions are isolated from each other. ## Best practices - **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad - **Regular updates**: Have agents update the scratchpad after each significant step or finding -- **Clear communication**: When using inter-agent communication, establish clear conventions for scratchpad content format -- **Memory management**: Consider the scratchpad as persistent memory that accumulates over the agent's lifetime +- **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution +- **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution ## Related pages From 2d26b929d5550700dfb5547ff63149f65f7bb410 Mon Sep 17 00:00:00 2001 From: Mingshi Liu Date: Fri, 10 Oct 2025 16:48:25 -0700 Subject: [PATCH 04/11] explain register paramters and execute parameters in two tables Signed-off-by: Mingshi Liu --- .../agents-tools/tools/scratchpad-tools.md | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index cf8ed37c592..5d71d0aaf1e 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -27,14 +27,28 @@ The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadT ## Tool parameters +The scratchpad tools have different parameter requirements depending on whether you're registering them with an agent or executing them directly. + ### ReadFromScratchPadTool +**Registration parameters** (when adding to an agent): + Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created +**Execution parameters** (when calling the tool directly): + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad + -You can directly use the tools API to execute ReadFromScratchPadTool and test the tool response before registering it with your agents. +## Testing the tools + +You can directly use the tools API to execute both scratchpad tools and test their responses before registering them with your agents. + +### Testing ReadFromScratchPadTool ```json POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool @@ -93,18 +107,20 @@ You will get a response about empty scratchpad. ### WriteToScratchPadTool +**Registration parameters** (when adding to an agent): + Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`notes` | String | Required (at execution) | The content to write to the scratchpad `return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation -## Execute parameters - -When executing the scratchpad tools, provide the following parameters: +**Execution parameters** (when calling the tool directly): Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`notes` | String | Optional | Specific notes to write to the scratchpad (when using WriteToScratchPadTool directly) +`notes` | String | Required | The content to write to the scratchpad +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation + +### Testing WriteToScratchPadTool You can directly use the tools API to execute WriteToScratchPadTool and test the tool response before registering it with your agents. From ce212ee85ba6821777b203b751df727e39334d4f Mon Sep 17 00:00:00 2001 From: Mingshi Liu Date: Fri, 10 Oct 2025 16:55:52 -0700 Subject: [PATCH 05/11] executing parameters is required Signed-off-by: Mingshi Liu --- _ml-commons-plugin/agents-tools/tools/scratchpad-tools.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 5d71d0aaf1e..df6c97fe027 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -27,8 +27,6 @@ The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadT ## Tool parameters -The scratchpad tools have different parameter requirements depending on whether you're registering them with an agent or executing them directly. - ### ReadFromScratchPadTool **Registration parameters** (when adding to an agent): @@ -40,8 +38,8 @@ Parameter | Type | Required/Optional | Description **Execution parameters** (when calling the tool directly): Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad +:--- | :--- |:------------------| :--- +`persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad ## Testing the tools From 5740d617f14c59a81d5b046c1d2890f32b556758 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 12:09:30 -0400 Subject: [PATCH 06/11] Apply suggestions from code review Signed-off-by: Nathan Bower --- .../agents-tools/tools/scratchpad-tools.md | 72 ++++++++++--------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index df6c97fe027..91142ae93be 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -16,37 +16,38 @@ grand_parent: Agents and tools The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadTool`, which enable agents to store and retrieve intermediate thoughts and results during runtime. These tools serve as temporary memory for a single agent execution session, allowing agents to take notes and store important findings during tool executions. -**Important**: The scratchpad acts as runtime memory that persists only during a single agent execution. When you call the agent's `_execute` API, a new scratchpad is created for that session. All notes and data, except persistent_notes, are cleared when the execution completes, ensuring each execution starts with a fresh scratchpad. +**Important**: The scratchpad acts as runtime memory that persists only during a single agent execution. When you call the agent's `_execute` API, a new scratchpad is created for that session. All notes and data, except `persistent_notes`, are cleared when the execution completes, ensuring each execution starts with a fresh scratchpad. ## Use cases -- **Task decomposition**: Store research plans, intermediate findings, and progress notes during multi-step operations within a single execution -- **Temporary state management**: Maintain context and accumulated knowledge during the current agent execution session -- **Multi-step workflows**: Save key findings after searches to build comprehensive responses in complex tasks -- **Execution planning**: Store and reference step-by-step plans during complex operations +- **Task decomposition**: Store research plans, intermediate findings, and progress notes during multi-step operations within a single execution. +- **Temporary state management**: Maintain context and accumulated knowledge during the current agent execution session. +- **Multi-step workflows**: Save key findings after searches to build comprehensive responses in complex tasks. +- **Execution planning**: Store and reference step-by-step plans during complex operations. ## Tool parameters +The following are the parameters for the scratchpad tools. ### ReadFromScratchPadTool -**Registration parameters** (when adding to an agent): +The following are the **registration parameters** used when adding to an agent. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created +`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created. -**Execution parameters** (when calling the tool directly): +The following are the **execution parameters** used when calling the tool directly. Parameter | Type | Required/Optional | Description :--- | :--- |:------------------| :--- -`persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad +`persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad. ## Testing the tools -You can directly use the tools API to execute both scratchpad tools and test their responses before registering them with your agents. +You can use the Tools API directly to execute both scratchpad tools and test their responses before registering them with your agents. -### Testing ReadFromScratchPadTool +### Testing the ReadFromScratchPadTool ```json POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool @@ -58,7 +59,7 @@ POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool ``` {% include copy-curl.html %} -When giving persistent_notes, you will see when tool response, it will try to show the persistent notes given in the response. +When provided `persistent_notes`, the tool will attempt to show the persistent notes in the response: ```json { @@ -75,7 +76,7 @@ When giving persistent_notes, you will see when tool response, it will try to sh } ``` -You can also test with empty persistent notes. +You can also test with an empty `persistent_notes` field: ```json POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool @@ -86,7 +87,7 @@ POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool } ``` -You will get a response about empty scratchpad. +The response will indicate that the scratchpad is empty: ```json { @@ -105,22 +106,22 @@ You will get a response about empty scratchpad. ### WriteToScratchPadTool -**Registration parameters** (when adding to an agent): +The following **registration parameters** are used when adding to an agent. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. -**Execution parameters** (when calling the tool directly): +The following **execution parameters** are used when calling the tool directly. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`notes` | String | Required | The content to write to the scratchpad -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation +`notes` | String | Required | The content to write to the scratchpad. +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. -### Testing WriteToScratchPadTool +### Testing the WriteToScratchPadTool -You can directly use the tools API to execute WriteToScratchPadTool and test the tool response before registering it with your agents. +You can use the Tools API directly to execute the `WriteToScratchPadTool` and test the tool response before registering it with your agents. ```json POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool @@ -132,7 +133,7 @@ POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool ``` {% include copy-curl.html %} -You can see the sample response from the tool output as follows: +The following is the example response from the tool output: ```json { "inference_results": [ @@ -147,7 +148,7 @@ You can see the sample response from the tool output as follows: ] } ``` -you can opt to set `return_history` parameter to `true` to get the full scratchpad content after writing. +You can opt to set the `return_history` parameter to `true` to get the full scratchpad content after writing: ```json POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool @@ -179,6 +180,7 @@ You can see the full content in the response: {% include copy-curl.html %} ## Example: Building a research agent with scratchpad tools +Use the following steps to build a research agent with scratchpad tools. ## Step 1: Register and deploy a model @@ -223,7 +225,7 @@ POST /_plugins/_ml/models/_register?deploy=true ## Step 2: Register an agent with scratchpad tools -Register a conversational agent that includes both scratchpad tools along with other research tools: +Register a conversational agent that includes both scratchpad tools and other research tools: ```json POST /_plugins/_ml/agents/_register @@ -288,10 +290,10 @@ POST /_plugins/_ml/agents//_execute?async=true The agent will: -1. Read from its scratchpad to check for existing relevant information (starts empty for new executions) -2. Create and save a research plan to the scratchpad -3. Execute searches and update the scratchpad with findings -4. Provide a comprehensive answer based on accumulated research +1. Read from its scratchpad to check for existing relevant information (starts empty for new executions). +2. Create and save a research plan to the scratchpad. +3. Execute searches and update the scratchpad with findings. +4. Provide a comprehensive answer based on accumulated research. When using the `agents//_execute` API, you will get a `parent_interaction_id` and `memory_id` in the response. Note the `parent_interaction_id` for later tracing steps. @@ -304,26 +306,26 @@ GET /_plugins/_ml/memory/message//traces?next_token=0 ``` {% include copy-curl.html %} -The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent builds up its knowledge during the execution session. +The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent accumulates knowledge during the execution session. ## Scratchpad lifecycle The scratchpad follows a simple lifecycle: -1. **Creation**: A new, empty scratchpad is created when an agent execution begins -2. **Usage**: During execution, the agent can read from and write to the scratchpad multiple times -3. **Cleanup**: The scratchpad is automatically cleared when the execution completes +1. **Creation**: A new, empty scratchpad is created when an agent execution begins. +2. **Usage**: During execution, the agent can read from and write to the scratchpad multiple times. +3. **Cleanup**: The scratchpad is automatically cleared when execution completes. Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring executions are isolated from each other. ## Best practices -- **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad -- **Regular updates**: Have agents update the scratchpad after each significant step or finding +- **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad. +- **Regular updates**: Have agents update the scratchpad after each significant step or finding. - **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution - **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution -## Related pages +## Related documentation - [Agents and tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/) - [Conversational agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) From f9dc998bcc2366e71fe6d0c10113ab7886a84993 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 15:15:57 -0400 Subject: [PATCH 07/11] Doc review Signed-off-by: Fanit Kolchina --- .../agents-tools/tools/scratchpad-tools.md | 334 +++++++++--------- 1 file changed, 170 insertions(+), 164 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 91142ae93be..bf7b81ffd6a 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -16,7 +16,8 @@ grand_parent: Agents and tools The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadTool`, which enable agents to store and retrieve intermediate thoughts and results during runtime. These tools serve as temporary memory for a single agent execution session, allowing agents to take notes and store important findings during tool executions. -**Important**: The scratchpad acts as runtime memory that persists only during a single agent execution. When you call the agent's `_execute` API, a new scratchpad is created for that session. All notes and data, except `persistent_notes`, are cleared when the execution completes, ensuring each execution starts with a fresh scratchpad. +The scratchpad acts as runtime memory that persists only during a single agent execution. When you call the agent's `_execute` API, a new scratchpad is created for that session. All notes and data, except `persistent_notes`, are cleared when the execution completes, ensuring each execution starts with a fresh scratchpad. +{: .important} ## Use cases @@ -25,161 +26,25 @@ The scratchpad tools consist of `WriteToScratchPadTool` and `ReadFromScratchPadT - **Multi-step workflows**: Save key findings after searches to build comprehensive responses in complex tasks. - **Execution planning**: Store and reference step-by-step plans during complex operations. -## Tool parameters -The following are the parameters for the scratchpad tools. - -### ReadFromScratchPadTool - -The following are the **registration parameters** used when adding to an agent. - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created. - -The following are the **execution parameters** used when calling the tool directly. - -Parameter | Type | Required/Optional | Description -:--- | :--- |:------------------| :--- -`persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad. - - -## Testing the tools - -You can use the Tools API directly to execute both scratchpad tools and test their responses before registering them with your agents. - -### Testing the ReadFromScratchPadTool - -```json -POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool -{ - "parameters": { - "persistent_notes": "You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used." - } -} -``` -{% include copy-curl.html %} - -When provided `persistent_notes`, the tool will attempt to show the persistent notes in the response: - -```json -{ - "inference_results": [ - { - "output": [ - { - "name": "response", - "result": "Notes from scratchpad:\n- You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used." - } - ] - } - ] -} -``` - -You can also test with an empty `persistent_notes` field: - -```json -POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool -{ - "parameters": { - "persistent_notes": "" - } -} -``` - -The response will indicate that the scratchpad is empty: - -```json -{ - "inference_results": [ - { - "output": [ - { - "name": "response", - "result": "Scratchpad is empty." - } - ] - } - ] -} -``` - -### WriteToScratchPadTool - -The following **registration parameters** are used when adding to an agent. - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. - -The following **execution parameters** are used when calling the tool directly. - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`notes` | String | Required | The content to write to the scratchpad. -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. - -### Testing the WriteToScratchPadTool - -You can use the Tools API directly to execute the `WriteToScratchPadTool` and test the tool response before registering it with your agents. +## Scratchpad lifecycle -```json -POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool -{ - "parameters": { - "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" - } -} -``` -{% include copy-curl.html %} +The scratchpad follows a simple lifecycle: -The following is the example response from the tool output: -```json -{ - "inference_results": [ - { - "output": [ - { - "name": "response", - "result": "Wrote to scratchpad: Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" - } - ] - } - ] -} -``` -You can opt to set the `return_history` parameter to `true` to get the full scratchpad content after writing: +1. **Creation**: A new, empty scratchpad is created when an agent execution begins. +2. **Usage**: During execution, the agent can read from and write to the scratchpad multiple times. +3. **Cleanup**: The scratchpad is automatically cleared when execution completes. -```json -POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool -{ - "parameters": { - "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n", - "return_history": true - } -} -``` -{% include copy-curl.html %} +Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring executions are isolated from each other. -You can see the full content in the response: +## Best practices -```json -{ - "inference_results": [ - { - "output": [ - { - "name": "response", - "result": "Scratchpad updated. Full content:\n- Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" - } - ] - } - ] -} -``` -{% include copy-curl.html %} +- **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad. +- **Regular updates**: Have agents update the scratchpad after each significant step or finding. +- **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution +- **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution ## Example: Building a research agent with scratchpad tools + Use the following steps to build a research agent with scratchpad tools. ## Step 1: Register and deploy a model @@ -297,33 +162,174 @@ The agent will: When using the `agents//_execute` API, you will get a `parent_interaction_id` and `memory_id` in the response. Note the `parent_interaction_id` for later tracing steps. -## Viewing scratchpad activity +## Tool parameters -You can monitor how the agent uses the scratchpad by examining the execution traces: +The following are the parameters for the scratchpad tools. + +### ReadFromScratchPadTool + +The following are the **registration parameters** used when adding to an agent. + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`persistent_notes` | String | Optional | Initial notes or instructions to store in the scratchpad when first created. + +The following are the **execution parameters** used when calling the tool directly. + +Parameter | Type | Required/Optional | Description +:--- | :--- |:------------------| :--- +`persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad. + + +## Testing the tools + +You can use the Tools API directly to execute both scratchpad tools and test their responses before registering them with your agents. + +### Testing the ReadFromScratchPadTool ```json -GET /_plugins/_ml/memory/message//traces?next_token=0 +POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool +{ + "parameters": { + "persistent_notes": "You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used." + } +} ``` {% include copy-curl.html %} -The traces will show the sequence of scratchpad reads and writes, demonstrating how the agent accumulates knowledge during the execution session. +When provided `persistent_notes`, the tool attempts to show the persistent notes in the response: -## Scratchpad lifecycle +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": """Notes from scratchpad: +- You are a helpful researcher to conduct searches in OpenSearch cluster. Before making the search, please remember to use the listIndexTool to figure out what are the available indices first. When using listIndexTool, remember the index name has to be in an array format. Please write down important notes after tool used.""" + } + ] + } + ] +} +``` -The scratchpad follows a simple lifecycle: +You can also test with an empty `persistent_notes` field: -1. **Creation**: A new, empty scratchpad is created when an agent execution begins. -2. **Usage**: During execution, the agent can read from and write to the scratchpad multiple times. -3. **Cleanup**: The scratchpad is automatically cleared when execution completes. +```json +POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool +{ + "parameters": { + "persistent_notes": "" + } +} +``` -Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring executions are isolated from each other. +The response indicates that the scratchpad is empty: -## Best practices +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Scratchpad is empty." + } + ] + } + ] +} +``` -- **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad. -- **Regular updates**: Have agents update the scratchpad after each significant step or finding. -- **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution -- **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution +### WriteToScratchPadTool + +The following **registration parameters** are used when adding to an agent. + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. + +The following **execution parameters** are used when calling the tool directly. + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`notes` | String | Required | The content to write to the scratchpad. +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. + +### Testing the WriteToScratchPadTool + +You can use the Tools API directly to execute the `WriteToScratchPadTool` and test the tool response before registering it with your agents. + +```json +POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool +{ + "parameters": { + "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" + } +} +``` +{% include copy-curl.html %} + +The following is the example response from the tool output: + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "Wrote to scratchpad: Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n" + } + ] + } + ] +} +``` + +You can set the `return_history` parameter to `true` to get the full scratchpad content after writing: + +```json +POST /_plugins/_ml/tools/_execute/WriteToScratchPadTool +{ + "parameters": { + "notes": "Research Plan for OpenSearch History and ML Evolution:\\n\\n1. OpenSearch version history, major releases after v2.0\\n2. For each major release:\\n a. Key architectural upgrades\\n b. New machine learning capabilities, especially ML Commons Agent framework \\n c. Descriptions of major Agent tools added\\n d. GitHub issue IDs tied to Agent framework features\\n3. Look for official OpenSearch documentation, release notes, blogs\\n4. Search code repositories for more technical details on ML changes\\n", + "return_history": true + } +} +``` +{% include copy-curl.html %} + +The response contains the full scratchpad content: + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": """Scratchpad updated. Full content: +- Research Plan for OpenSearch History and ML Evolution:\n\n1. OpenSearch version history, major releases after v2.0\n2. For each major release:\n a. Key architectural upgrades\n b. New machine learning capabilities, especially ML Commons Agent framework \n c. Descriptions of major Agent tools added\n d. GitHub issue IDs tied to Agent framework features\n3. Look for official OpenSearch documentation, release notes, blogs\n4. Search code repositories for more technical details on ML changes\n""" + } + ] + } + ] +} +``` + +## Viewing scratchpad activity + +You can monitor how the agent uses the scratchpad by examining the execution traces: + +```json +GET /_plugins/_ml/memory/message//traces?next_token=0 +``` +{% include copy-curl.html %} + +The traces show the sequence of scratchpad reads and writes, demonstrating how the agent accumulates knowledge during the execution session. ## Related documentation From 8279885ba3d7a8fbf9dcb08c42d92bfd7e051f3c Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 15:20:30 -0400 Subject: [PATCH 08/11] Reorganize sections Signed-off-by: Fanit Kolchina --- .../agents-tools/tools/scratchpad-tools.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index bf7b81ffd6a..53ade42db74 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -180,6 +180,21 @@ Parameter | Type | Required/Optional | Description :--- | :--- |:------------------| :--- `persistent_notes` | String | Required | Initial notes or instructions to store in the scratchpad. +### WriteToScratchPadTool + +The following **registration parameters** are used when adding to an agent. + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. + +The following **execution parameters** are used when calling the tool directly. + +Parameter | Type | Required/Optional | Description +:--- | :--- | :--- | :--- +`notes` | String | Required | The content to write to the scratchpad. +`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. + ## Testing the tools @@ -243,21 +258,6 @@ The response indicates that the scratchpad is empty: } ``` -### WriteToScratchPadTool - -The following **registration parameters** are used when adding to an agent. - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. - -The following **execution parameters** are used when calling the tool directly. - -Parameter | Type | Required/Optional | Description -:--- | :--- | :--- | :--- -`notes` | String | Required | The content to write to the scratchpad. -`return_history` | Boolean | Optional | When set to `true`, returns the full scratchpad content after writing. When `false` or omitted (default), returns the newly added note with confirmation. - ### Testing the WriteToScratchPadTool You can use the Tools API directly to execute the `WriteToScratchPadTool` and test the tool response before registering it with your agents. From a1ccc5297ad544c1f56b4fd9674831b4b3efe247 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 15:23:54 -0400 Subject: [PATCH 09/11] Small updates Signed-off-by: Fanit Kolchina --- .../agents-tools/tools/scratchpad-tools.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 53ade42db74..2998896043f 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -47,7 +47,7 @@ Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring exe Use the following steps to build a research agent with scratchpad tools. -## Step 1: Register and deploy a model +### Step 1: Register and deploy a model Register a conversational model that supports the agent framework. The following example uses Anthropic Claude: @@ -88,7 +88,7 @@ POST /_plugins/_ml/models/_register?deploy=true ``` {% include copy-curl.html %} -## Step 2: Register an agent with scratchpad tools +### Step 2: Register an agent with scratchpad tools Register a conversational agent that includes both scratchpad tools and other research tools: @@ -139,7 +139,7 @@ POST /_plugins/_ml/agents/_register ``` {% include copy-curl.html %} -## Step 3: Execute the agent +### Step 3: Execute the agent Execute the agent with a research question: @@ -160,7 +160,7 @@ The agent will: 3. Execute searches and update the scratchpad with findings. 4. Provide a comprehensive answer based on accumulated research. -When using the `agents//_execute` API, you will get a `parent_interaction_id` and `memory_id` in the response. Note the `parent_interaction_id` for later tracing steps. +When using the `agents//_execute` API, you will get a `parent_interaction_id` and `memory_id` in the response. Note the `parent_interaction_id` for later tracing steps. For more information, see [Viewing scratchpad activity](#viewing-scratchpad-activity). ## Tool parameters @@ -240,6 +240,7 @@ POST /_plugins/_ml/tools/_execute/ReadFromScratchPadTool } } ``` +{% include copy-curl.html %} The response indicates that the scratchpad is empty: From 8e0729408688474b90db4c8f8720688eea478d8d Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 15:27:35 -0400 Subject: [PATCH 10/11] Add missing tools to index page Signed-off-by: Fanit Kolchina --- _ml-commons-plugin/agents-tools/tools/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md index 0f3f27be146..94b0a28ba06 100644 --- a/_ml-commons-plugin/agents-tools/tools/index.md +++ b/_ml-commons-plugin/agents-tools/tools/index.md @@ -40,10 +40,13 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa |[`IndexMappingTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index-mapping-tool/) |Retrieves index mapping and setting information for an index. | |[`ListIndexTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/list-index-tool/) |Retrieves index information for the OpenSearch cluster. Introduced in OpenSearch version 3.0 as a replacement for the `CatIndexTool`. | |[`LogPatternAnalysisTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool/) |Performs advanced log analysis by detecting exceptional log patterns and sequences through comparative analysis. | +|[`LogPatternTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/log-pattern-tool/) |Analyzes log data to extract and identify recurring structural patterns across log messages. | |[`MLModelTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/ml-model-tool/) |Runs machine learning models. | |[`NeuralSparseSearchTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/neural-sparse-tool/) | Performs sparse vector retrieval. | |[`PPLTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/ppl-tool/) |Translates natural language into a Piped Processing Language (PPL) query. | +|[`QueryPlanningTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/query-planning-tool/) |Creates and executes an OpenSearch DSL query based on a user's natural language question. | |[`RAGTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/rag-tool/) |Uses neural search or neural sparse search to retrieve documents and integrates a large language model to summarize the answers. | +|[`ReadFromScratchPadTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/scratchpad-tools/) |Reads notes and information from an agent's temporary scratchpad memory during execution. | |[`SearchAlertsTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/search-alerts-tool/) |Searches for alerts. | |[`SearchAnomalyDetectorsTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/search-anomaly-detectors/) | Searches for anomaly detectors. | |[`SearchAnomalyResultsTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/search-anomaly-results/) | Searches anomaly detection results generated by anomaly detectors. | @@ -52,7 +55,7 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa |[`VectorDBTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/vector-db-tool/) |Performs dense vector retrieval. | |[`VisualizationTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/visualization-tool/) |Finds visualizations in OpenSearch Dashboards. | |[`WebSearchTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/web-search-tool/) |Answers a user's question using a web search. | -|[`QueryPlanningTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/query-planning-tool/) |Creates and executes an OpenSearch DSL query based on a user's natural language question. | +|[`WriteToScratchPadTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/scratchpad-tools/) |Writes notes and information to an agent's temporary scratchpad memory during execution. | ## Developer information From d4a4a152247330aacb5375ea90459cf764d320ff Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 15:27:57 -0400 Subject: [PATCH 11/11] Apply suggestions from code review Signed-off-by: Nathan Bower --- _ml-commons-plugin/agents-tools/tools/scratchpad-tools.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md index 53ade42db74..7d01dcd7742 100644 --- a/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md +++ b/_ml-commons-plugin/agents-tools/tools/scratchpad-tools.md @@ -40,8 +40,8 @@ Each call to the agent's `_execute` API creates a fresh scratchpad, ensuring exe - **Structured notes**: Encourage agents to maintain organized, structured notes in the scratchpad. - **Regular updates**: Have agents update the scratchpad after each significant step or finding. -- **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution -- **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution +- **Session awareness**: Remember that scratchpad content is temporary and specific to the current execution. +- **Efficient usage**: Use the scratchpad for intermediate results that need to be referenced multiple times during execution. ## Example: Building a research agent with scratchpad tools