diff --git a/_ml-commons-plugin/agentic-memory.md b/_ml-commons-plugin/agentic-memory.md new file mode 100644 index 0000000000..1ab3de95d0 --- /dev/null +++ b/_ml-commons-plugin/agentic-memory.md @@ -0,0 +1,209 @@ +--- +layout: default +title: Agentic memory +nav_order: 60 +--- + +# Agentic memory +**Introduced 3.3** +{: .label .label-purple } + +Agentic memory enables AI agents to learn, remember, and reason over structured information across conversations. Unlike simple conversation memory that only stores message history, agentic memory provides persistent, intelligent storage that helps agents maintain context, learn user preferences, and improve their responses over time. + +Using agentic memory, you can build AI agents that can do the following: + +- Remember user preferences across multiple conversation sessions +- Learn from past interactions to provide more personalized responses +- Maintain conversation context beyond simple message history +- Store and retrieve factual knowledge extracted from conversations +- Track agent execution traces for debugging and analysis +- Organize information across different users, sessions, or agent instances + +Currently, agentic memory is designed for integration with external agent frameworks like LangChain and LangGraph. OpenSearch's internal [agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/) cannot interact with agentic memory. +{: .note} + +## Memory containers + +Agentic memory is organized into _memory containers_ that hold all memory types for a specific use case, such as a chatbot, research assistant, or customer service agent. + +Each container can be configured with the following components: + +- Text embedding models: For semantic search capabilities. +- Large language models (LLMs): For inference and knowledge extraction. +- [Memory processing strategies](#memory-processing-strategies): For defining how memories are processed or extracted. +- [Namespaces](#namespaces): For partitioning and isolating memories by context, user, agent, or session. + +For example, to create a memory container with two strategies, send the following request: + +```json +POST /_plugins/_ml/memory_containers/_create +{ + "name": "customer-service-agent", + "description": "Memory container for customer service agent", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "your-embedding-model-id", + "llm_id": "your-llm-model-id", + "strategies": [ + { + "type": "USER_PREFERENCE", + "namespace": ["user_id"] + }, + { + "type": "SUMMARY", + "namespace": ["user_id", "session_id"] + } + ] + } +} +``` +{% include copy-curl.html %} + +## Memory types + +Each memory container can store four distinct types of memory: + +- `sessions` -- Manages conversation sessions and their metadata. Each session represents a distinct interaction context between users and agents, containing session-specific information such as start time, participants, and session state. + +- `working` -- Stores active conversation data and structured information that agents use during ongoing interactions. This includes recent messages, current context, agent state, execution traces, and temporary data needed for immediate processing. + +- `long-term` -- Contains processed knowledge and facts extracted from conversations over time. When inference is enabled, LLMs extract key insights, user preferences, and important information from working memory and store them as persistent knowledge. + +- `history` -- Maintains an audit trail of all memory operations (add, update, delete) across the memory container. This provides a comprehensive log of how memories have evolved and changed over time. + +## Payload types + +When adding memories, you can specify different payload types: + +- `conversational` -- Stores conversational messages between users and assistants. +- `data` -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. + +To add a conversation memory with inference, send the following request: + +```json +POST /_plugins/_ml/memory_containers//memories +{ + "messages": [ + { + "role": "user", + "content": "I prefer email notifications over SMS" + }, + { + "role": "assistant", + "content": "I've noted your preference for email notifications" + } + ], + "namespace": { + "user_id": "user123", + "session_id": "session456" + }, + "payload_type": "conversational", + "infer": true +} +``` +{% include copy-curl.html %} + +To add agent state data, send the following request: + +```json +POST /_plugins/_ml/memory_containers//memories +{ + "structured_data": { + "agent_state": "researching", + "current_task": "analyze customer feedback", + "progress": 0.75 + }, + "namespace": { + "agent_id": "research-agent-1", + "session_id": "session456" + }, + "payload_type": "data", + "infer": false +} +``` +{% include copy-curl.html %} + +## Inference mode + +You can control how OpenSearch processes memories using the `infer` parameter: + +- `false` (default) -- Stores raw messages and data in `working` memory without LLM processing. +- `true` -- Uses the configured LLM to extract key information and knowledge from the content. + +## Memory processing strategies + +Memory containers can use the following _strategies_ to automatically process and organize memories: + +- `SEMANTIC` -- Groups related memories by meaning and content similarity. +- `USER_PREFERENCE` -- Extracts and stores user preferences from conversations. +- `SUMMARY` -- Creates condensed summaries of conversation content. + +Strategies are optional; you can create containers without them for simple storage needs. + +## Namespaces + +_Namespaces_ organize memories within containers by grouping them with identifiers like `user_id`, `session_id`, or `agent_id`. This allows you to separate memories for different users or conversation sessions. + +To search memories by namespace, send the following request: + +```json +GET /_plugins/_ml/memory_containers//memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "user123" + } + } + ] + } + } +} +``` +{% include copy-curl.html %} + +## Example use cases + +The following examples demonstrate how you can use agentic memory. + +### Personalized chatbot + +Create a memory container that learns user preferences over time: + +- Store conversations in `working` memory with inference enabled. +- Extract user preferences into `long-term` memory using the `USER_PREFERENCE` strategy. +- Use namespaces to separate different users' memories. + +### Research assistant agent + +Build an agent that accumulates knowledge from research sessions: + +- Store research queries and results in `working` memory. +- Use the `SEMANTIC` strategy to group related research topics. +- Maintain `history` to track how knowledge evolved over time. + +### Customer service agent + +Develop an agent that remembers customer interactions: + +- Store customer conversations with inference to extract key issues. +- Use `SUMMARY` strategy to create concise interaction summaries. +- Organize by customer ID using namespaces. + +## Getting started + +To implement agentic memory in your agents: + +1. **[Create a memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/)** with appropriate models and strategies. +2. **[Add memories]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/)** during agent interactions. +3. **[Search and retrieve]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/)** relevant memories to inform agent responses. +4. **[Update memories]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/)** as conversations evolve. + +For detailed API documentation, see [Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/). + +## Next steps + +- Explore [memory container configuration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) options. +- Review the complete [Agentic Memory API reference]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/). \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/index.md b/_ml-commons-plugin/agents-tools/index.md index a3ceed6ff3..b1e5e450f4 100644 --- a/_ml-commons-plugin/agents-tools/index.md +++ b/_ml-commons-plugin/agents-tools/index.md @@ -12,11 +12,10 @@ redirect_from: **Introduced 2.13** {: .label .label-purple } -You can automate machine learning (ML) tasks using agents and tools. +You can automate machine learning (ML) tasks using agents and tools. An _agent_ orchestrates and runs ML models and tools. For a list of supported agents, see [Agents]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/agents/). A _tool_ performs a set of specific tasks. Some examples of tools are the [`VectorDBTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/vector-db-tool/), which supports vector search, and the [`ListIndexTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/list-index-tool/), which executes the List Indices API. For a list of supported tools, see [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/). -You can modify and transform tool outputs using a [processor chain]({{site.url}}{{site.baseurl}}/ml-commons-plugin/processor-chain/). - +You can modify and transform tool outputs using a [processor chain]({{site.url}}{{site.baseurl}}/ml-commons-plugin/processor-chain/). \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/agent-tool.md b/_ml-commons-plugin/agents-tools/tools/agent-tool.md index 272af51e4d..e0e4ec09c0 100644 --- a/_ml-commons-plugin/agents-tools/tools/agent-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/agent-tool.md @@ -104,4 +104,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index dfe4770932..ace94c3844 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -165,4 +165,8 @@ When running the agent, you can define any parameter needed for the API call in "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }" } ] -``` \ No newline at end of file +``` + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md index a66d85a5cc..404ad7eacf 100644 --- a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md +++ b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md @@ -167,3 +167,7 @@ The following table lists the available tool parameters for running the agent. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index name. Supports wildcards (for example, `weblogs-*`). If wildcards are used, then the tool fetches mappings from the first resolved index and sends them to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md index 6f35f90041..26ccbbe17e 100644 --- a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md @@ -195,6 +195,10 @@ The following table lists the available tool parameters for running the agent. | `dsl` | String | Optional | A complete raw DSL query as a JSON string. If provided, takes precedence over the `filter` parameter. | | `ppl` | String | Optional | A complete PPL statement without time information. Used when `queryType` is `ppl`. | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Data Distribution tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md index 8649d2d74d..39cc6f9109 100644 --- a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. -`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. \ No newline at end of file +`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md index 94b0a28ba0..ff4a98f53e 100644 --- a/_ml-commons-plugin/agents-tools/tools/index.md +++ b/_ml-commons-plugin/agents-tools/tools/index.md @@ -31,6 +31,8 @@ Specify a tool by providing its `type`, `parameters`, and, optionally, a `descri Each tool takes a list of parameters specific to that tool. In the preceding example, the `AgentTool` takes an `agent_id` of the agent it will run. For a list of parameters, see each tool's documentation. +You can also run tools directly without creating an agent using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/), which is useful for testing individual tools or performing standalone operations. + |Tool | Description | |:--- |:--- | |[`AgentTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/agent-tool/) |Runs any agent. | diff --git a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md index 79d9d0d7b0..41c02dbe49 100644 --- a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md @@ -130,4 +130,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md index 3249fa2cd6..0d6a7f334e 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: +The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: - Log sequence analysis (with trace correlation) - Log pattern difference analysis @@ -192,6 +192,10 @@ The following table lists the available tool parameters for running the agent. | `selectionTimeRangeStart` | String | Required | The start time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:50:26`). | | `selectionTimeRangeEnd` | String | Required | The end time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:55:56`). | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Log Pattern Analysis tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md index 3bbd09b169..a179fa3b96 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md @@ -117,4 +117,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- |:-----------------------| :--- | `index` | String | Required for DSL queries | The index to search for pattern analysis. | | `input` | String | Required for DSL queries | A DSL query JSON as a string. If both `input` and `ppl` are provided, `input` (DSL) takes precedence. | -| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | \ No newline at end of file +| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md index ceeda40528..048028d806 100644 --- a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md @@ -14,7 +14,7 @@ plugins.ml_commons.rag_pipeline_feature_enabled: true {: .label .label-purple } -The `MLModelTool` runs a machine learning (ML) model and returns inference results. +The `MLModelTool` runs a machine learning (ML) model and returns inference results. ## Step 1: Create a connector for a model @@ -164,4 +164,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md index b78d3d641e..9be67422c0 100644 --- a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md @@ -221,3 +221,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md index 72d8ba30b5..2cb1cc181f 100644 --- a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. +The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. ## Prerequisite @@ -201,4 +201,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index on which to run the PPL query. `question` | String | Required | The natural language question to send to the LLM. -`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`. \ No newline at end of file +`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md index 1bec951294..9d3518d101 100644 --- a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. +The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. The `QueryPlanningTool` supports two approaches for generating DSL queries from natural language questions: @@ -522,6 +522,10 @@ GIVE THE OUTPUT PART ONLY IN YOUR RESPONSE (a single JSON object) Output: ``` +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Related pages - [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index) \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/rag-tool.md b/_ml-commons-plugin/agents-tools/tools/rag-tool.md index 24e95286a4..9b22798ec1 100644 --- a/_ml-commons-plugin/agents-tools/tools/rag-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/rag-tool.md @@ -144,4 +144,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md index 76f9e4b4dc..c9ce8994cb 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md index 9f31dea057..c0978857c2 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md @@ -107,3 +107,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md index 2f2728e32d..2fb7d98c96 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md @@ -121,3 +121,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md index b023522893..50bab482ea 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when registerin Parameter | Type | Description :--- | :--- | :--- -`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required. \ No newline at end of file +`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index, and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md index 77b51d4964..853e6e3fd8 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md index 61c6028f28..8e8753e101 100644 --- a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md @@ -234,3 +234,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md index 98457932c2..769f9325dc 100644 --- a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -Use the `VisualizationTool` to find visualizations relevant to a question. +Use the `VisualizationTool` to find visualizations relevant to a question. ## Step 1: Register a flow agent that will run the VisualizationTool @@ -101,3 +101,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md index 8cc5814a5f..2f16332041 100644 --- a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md @@ -319,4 +319,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md index 1e298dc4f1..4f6a8bf3db 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/add-memory.md @@ -1,73 +1,176 @@ --- layout: default title: Add agentic memory -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 40 +nav_order: 45 --- # Add Agentic Memory API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} -Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create a memory in one of the following modes (controlled by the `infer` parameter): +Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can specify different [payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#payload-types) and control [inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#inference-mode) for how OpenSearch processes the memory. -- Fact memory -- A processed representation of the message. The large language model (LLM) associated with the memory container extracts and stores key factual information or knowledge from the original text. +Once an agentic memory is created, provide its `memory_id` to other APIs. -- Raw message memory -- The unprocessed message content. - -Once an agentic memory is created, you'll provide its `memory_id` to other APIs. - -## Endpoint +## Endpoints ```json -POST /_plugins/_ml/memory_containers/{memory_container_id}/memories +POST /_plugins/_ml/memory_containers//memories ``` +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to add the memory to. | + ## Request body fields The following table lists the available request body fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`messages` | List | Required | A list of messages. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. -`session_id` | String | Optional | The session ID associated with the memory. -`agent_id` | String | Optional | The agent ID associated with the memory. -`infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true`. When `true`, the LLM extracts factual information from the original text and stores it as the memory. When `false`, the memory contains the unprocessed message and you must explicitly specify the `role` in each message. -`tags` | Object | Optional | Custom metadata for the agentic memory. +`messages` | Array | Conditional | A list of messages for a `conversational` payload. Each message requires a `content` field and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required when `payload_type` is `conversational`. +`structured_data` | Object | Conditional | Structured data content for data memory. Required when `payload_type` is `data`. +`binary_data` | String | Optional | Binary data content encoded as a Base64 string for binary payloads. +`payload_type` | String | Required | The type of payload. Valid values are `conversational` or `data`. See [Payload types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#payload-types). +`namespace` | Object | Optional | The [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the `namespace` field and `disable_session: false` (default is `true`), a new session with a new session ID is created. +`metadata` | Object | Optional | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). +`tags` | Object | Optional | Tags for categorizing and organizing memories. +`infer` | Boolean | Optional | Whether to use a large language model (LLM) to extract key information from messages. Default is `false`. When `true`, the LLM extracts key information from the original text and stores it as a memory. See [Inference mode]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#inference-mode). -## Example request +## Example request: Conversational payload ```json POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories { - "messages": [ - {"role": "user", "content": "Machine learning is a subset of artificial intelligence"} - ], - "session_id": "sess_789", - "agent_id": "agent_123", - "tags": { - "topic": "personal info" + "messages": [ + { + "role": "user", + "content": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content": "Cool, nice. Hope you enjoy your life." } + ], + "namespace": { + "user_id": "bob" + }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + } + }, + "tags": { + "topic": "personal info" + }, + "infer": true, + "payload_type": "conversational" +} +``` +{% include copy-curl.html %} + +## Example response: Conversation payload + +```json +{ + "session_id": "XSEuiJkBeh2gPPwzjYVh", + "working_memory_id": "XyEuiJkBeh2gPPwzjYWM" +} +``` + +## Example request: Data payload + +To store agent state in working memory, send the following request: + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "time_range": { + "start": "2025-09-11", + "end": "2025-09-15" + } + }, + "namespace": { + "agent_id": "testAgent1" + }, + "metadata": { + "status": "checkpoint", + "anyobject": "abc" + }, + "tags": { + "topic": "agent_state" + }, + "infer": false, + "payload_type": "data" +} +``` +{% include copy-curl.html %} + +## Example response: Data payload + +```json +{ + "working_memory_id": "Z8xeTpkBvwXRq366l0iA" +} +``` + +## Example request: Storing tool invocation data + +To store agent trace data in working memory, send the following request: + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories +{ + "structured_data": { + "tool_invocations": [ + { + "tool_name": "ListIndexTool", + "tool_input": { + "filter": "*,-.plugins*" + }, + "tool_output": "green open security-auditlog-2025.09.17..." + } + ] + }, + "namespace": { + "user_id": "bob", + "agent_id": "testAgent1", + "session_id": "123" + }, + "metadata": { + "status": "checkpoint", + "branch": { + "branch_name": "high", + "root_event_id": "228nadfs879mtgk" + }, + "anyobject": "abc" + }, + "tags": { + "topic": "personal info", + "parent_memory_id": "o4-WWJkBFT7urc7Ed9hM", + "data_type": "trace" + }, + "infer": false, + "payload_type": "data" } ``` {% include copy-curl.html %} -## Example response +## Example response: Trace data ```json { - "results": [ - { - "id": "T9jtmpgBOh0h20Y91WtZ", - "text": "Machine learning is a subset of artificial intelligence", - "event": "ADD" - } - ], - "session_id": "sess_789" + "working_memory_id": "Z8xeTpkBvwXRq366l0iA" } ``` @@ -77,8 +180,5 @@ The following table lists all response body fields. | Field | Data type | Description | | :-------------- | :-------- | :------------------------------------------------------------------------------------------------ | -| `results` | List | A list of memory entries returned by the request. | -| `results.id` | String | The unique identifier for the memory entry. | -| `results.text` | String | If `infer` is `false`, contains the stored text from the message. If `infer` is `true`, contains the extracted fact from the message. | -| `results.event` | String | The type of event for the memory entry. For the Add Agentic Memory API, the event type is always `ADD`, indicating that the memory was added. | -| `session_id` | String | The session ID associated with the memory. | +| `session_id` | String | The session ID associated with the memory (returned for `conversation` memory when a session is created or used). | +| `working_memory_id` | String | The unique identifier for the created working memory entry. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md index 34437cf68c..04ee2bd8ae 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md @@ -1,30 +1,32 @@ --- layout: default title: Create memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 10 --- # Create Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} - -Use this API to create a memory container to hold agentic memories. The container can have two model types associated with it: +Use this API to create a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-containers) to store agentic memories. The container can have two model types associated with it: - A text embedding model for vectorizing the message so it can be searched. Use a text embedding model for dense vector embeddings or a sparse encoding model for sparse vector formats. If no embedding model is specified, messages are stored but cannot be used for vector-based searches. -- A large language model (LLM) for reasoning over the message to produce factual or processed content. If no LLM is specified, messages are stored directly, without applying inference. +- A large language model (LLM) for reasoning over the message to produce factual or processed content. If no LLM is specified, messages are stored directly, without applying inference. Long-term memory requires both an LLM model and embedding model to be configured. + +For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). -Once a memory container is created, you'll provide its `memory_container_id` to other APIs. +LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). If using an OpenAI GPT model, set the `llm_result_path` to `$.choices[0].message.content`. +{: .note} + +Once a memory container is created, provide its `memory_container_id` to other APIs. ## Prerequisites If you want to use one of the model types to process memories, register the models in OpenSearch. -### Embedding model +### Embedding model Register either a local or externally hosted embedding model. OpenSearch supports text embedding and sparse encoding models. @@ -78,9 +80,8 @@ POST /_plugins/_ml/models/_register ``` {% include copy-curl.html %} -### LLM +### LLM -Currently, agentic memory supports only the Anthropic Claude model for LLM capabilities. Starting with OpenSearch 3.3, this feature will be generally available and will include support for additional LLM providers, such as OpenAI. To register an Anthropic Claude model, send the following request: @@ -91,7 +92,7 @@ POST /_plugins/_ml/models/_register "function_name": "remote", "description": "test model", "connector": { - "name": "Amazon Bedrock Connector: embedding", + "name": "Amazon Bedrock Connector: Chat", "description": "The connector to bedrock Claude 3.7 sonnet model", "version": 1, "protocol": "aws_sigv4", @@ -115,8 +116,8 @@ POST /_plugins/_ml/models/_register "headers": { "content-type": "application/json" }, - "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke", - "request_body": """{ "system": "${parameters.system_prompt}", "anthropic_version": "${parameters.anthropic_version}", "max_tokens": ${parameters.max_tokens}, "temperature": ${parameters.temperature}, "messages": ${parameters.messages} }""" + "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/converse", + "request_body": "{ \"anthropic_version\": \"${parameters.anthropic_version}\", \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature}, \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [ { \"role\": \"user\", \"content\": [ {\"text\": \"${parameters.user_prompt}\" }] }]}" } ] } @@ -129,7 +130,7 @@ The `system_prompt` parameter is required for Claude models. For more information about using externally hosted models, see [Connecting to externally hosted models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index/). -## Endpoint +## Endpoints ```json POST /_plugins/_ml/memory_containers/_create @@ -143,33 +144,163 @@ Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- `name` | String | Required | The name of the memory container. `description` | String | Optional | The description of the memory container. -`memory_storage_config` | Object | Optional | The memory storage configuration. See [the `memory_storage_config` object](#the-memory_storage_config-object). +`configuration` | Object | Required | The memory container configuration. See [The `configuration` object](#the-configuration-object). -### The memory_storage_config object +### The configuration object -The `memory_storage_config` object supports the following fields. +The `configuration` object supports the following fields. Field | Data type | Required/Optional | Description :--- | :--- | :--- | :--- -`dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. -`embedding_model_id` | String | Optional | The embedding model ID. `embedding_model_type` | String | Optional | The embedding model type. Supported types are `TEXT_EMBEDDING` and `SPARSE_ENCODING`. -`llm_model_id` | String | Optional | The LLM ID. -`max_infer_size` | Integer | Optional | The maximum number of messages the LLM processes for inference in a single request. Valid values are 1--9, inclusive. Default is 5. -`memory_index_name` | String | Optional | The name of the index in which to save messages, embeddings, and inferred facts. If not specified, a default index is automatically generated. +`embedding_model_id` | String | Optional | The embedding model ID. +`embedding_dimension` | Integer | Optional | The dimension of the embedding model. Required if `embedding_model_type` is `TEXT_EMBEDDING`. +`llm_id` | String | Optional | The LLM model ID for processing and inference. +`index_prefix` | String | Optional | A custom prefix for memory indexes. If not specified, a default prefix is used: `default` when `use_system_index` is `true`, or an 8-character random UUID when `use_system_index` is `false`. +`use_system_index` | Boolean | Optional | Whether to use system indexes. Default is `true`. +`disable_history` | Boolean | Optional | If disabled, no history will be persisted. Default is `false`, so history will be persisted by default. +`disable_session` | Boolean | Optional | If disabled, no session will be persisted. Default is `true`, so the session will not be persisted by default. +`max_infer_size` | int | Optional | Controls the top k number of similar existing memories retrieved during memory consolidation to make ADD/UPDATE/DELETE decisions. +`index_settings` | Object | Optional | Custom OpenSearch index settings for the memory storage indexes that will be created for this container. Each memory type (`sessions`, `working`, `long_term`, and `history`) uses its own index. See [Index settings](#index-settings). +`strategies` | Array | Optional | An array of [memory processing strategies]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-processing-strategies). See [The `strategies` array](#the-strategies-array). +`parameters` | Object | Optional | Global parameters for the memory container. See [The `parameters` object](#the-parameters-object). + +### Index settings + +You can customize the OpenSearch index settings for the storage indexes that will be created to store memory data. Each memory type uses a dedicated index, and you can configure settings like the number of shards and replicas for performance optimization. + +The following example shows you how to specify custom index settings in the `configuration` object: + +```json +{ + "name": "my-memory-container", + "configuration": { + "embedding_model_id": "your-model-id", + "index_settings": { + "session_index": { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "short_term_memory_index": { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "long_term_memory_index": { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + }, + "long_term_memory_history_index": { + "index": { + "number_of_shards": "2", + "number_of_replicas": "2" + } + } + } + } +} +``` +{% include copy.html %} + +### The strategies array + +Each strategy in the `strategies` array supports the following fields. + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`type` | String | Required | The strategy type. Valid values are `SEMANTIC`, `USER_PREFERENCE`, and `SUMMARY`. +`namespace` | Array | Required | An array of [namespace]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#namespaces) dimensions for organizing memories (for example, `["user_id"]` or `["agent_id", "session_id"]`). +`configuration` | Object | Optional | Strategy-specific configuration. See [The strategy `configuration` object](#the-strategy-configuration-object). +`enabled` | Boolean | Optional | Whether to enable the strategy in the memory container. Default is `true`. + +### The strategy configuration object + +The strategy `configuration` object supports the following fields. + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | A JSONPath expression for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). +`system_prompt` | String | Optional | A custom system prompt used to override the default strategy prompt. +`llm_id` | String | Optional | The LLM model ID for this strategy. Overrides the global LLM setting. + +### The parameters object +The `parameters` object supports the following field. + +Field | Data type | Required/Optional | Description +:--- | :--- | :--- | :--- +`llm_result_path` | String | Optional | A global JSONPath expression for extracting LLM results from responses. Default is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). + +## Example request: Basic memory container + +```json +POST /_plugins/_ml/memory_containers/_create +{ + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + } +} +``` +{% include copy-curl.html %} -## Example request +## Example request: Advanced memory container with multiple strategies ```json POST /_plugins/_ml/memory_containers/_create { - "name": "Sparse memory container", - "description": "Store sparse conversations with semantic search", - "memory_storage_config": { - "llm_model_id": "bbphdJgB9L0Qb_M6ipnn", - "embedding_model_type": "SPARSE_ENCODING", - "embedding_model_id": "RodoX5gBfObQ5OgTHf1X" + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "{{embedding_model_id}}", + "embedding_dimension": 1024, + "llm_id": "{{llm_id}}", + "index_prefix": "my_custom_prefix", + "use_system_index": false, + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text", + "system_prompt": "Extract semantic information from user conversations", + "llm_id": "{{custom_llm_id}}" + } + }, + { + "type": "USER_PREFERENCE", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + }, + { + "type": "SUMMARY", + "namespace": ["agent_id"], + "configuration": { + "llm_result_path": "$.output.message.content[0].text" + } + } + ], + "parameters": { + "llm_result_path": "$.output.message.content[0].text" } + } } ``` {% include copy-curl.html %} diff --git a/_ml-commons-plugin/api/agentic-memory-apis/create-session.md b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md new file mode 100644 index 0000000000..b500df8205 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/create-session.md @@ -0,0 +1,93 @@ +--- +layout: default +title: Create session +parent: Agentic memory APIs +grand_parent: ML Commons APIs +nav_order: 40 +--- + +# Create session +**Introduced 3.3** +{: .label .label-purple } + +Use this API to create a new session in a memory container. Sessions represent distinct interaction contexts between users and agents. + +## Path and HTTP methods + +```json +POST /_plugins/_ml/memory_containers//memories/sessions +``` + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container where the session will be created. | + +## Request fields + +The following table lists the available request body fields. + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `session_id` | String | Optional | A custom session ID. If provided, this ID is used for the session. If not provided, a random ID is generated. | +| `summary` | String | Optional | A session summary or description. | +| `metadata` | Object | Optional | Additional metadata for the session provided as key-value pairs. | +| `namespace` | Object | Optional | Namespace information for organizing the session. | + +## Example request: Create a session with a custom ID + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/sessions +{ + "session_id": "abc123", + "metadata": { + "key1": "value1" + } +} +``` + +## Example response: Custom session ID + +```json +{ + "session_id": "abc123", + "status": "created" +} +``` + +## Example request: Create a session with an autogenerated ID + +```json +POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/sessions +{ + "summary": "This is a test session", + "metadata": { + "key1": "value1" + }, + "namespace": { + "user_id": "bob" + } +} +``` +{% include copy-curl.html %} + +## Example response: Autogenerated session ID + +```json +{ + "session_id": "jTYm35kBt8CyICnjxJl9", + "status": "created" +} +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `session_id` | String | The ID of the created session (either provided or auto-generated). | +| `status` | String | The status of the creation operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md index f23f324946..cea64aba36 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md @@ -1,31 +1,57 @@ --- layout: default title: Delete memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 30 --- # Delete Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} - Use this API to delete a memory container by its ID. -## Endpoint +## Endpoints ```json -DELETE /_plugins/_ml/memory_containers/{memory_container_id} +DELETE /_plugins/_ml/memory_containers/ ``` -## Example request +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to delete. | + +## Query parameters + +The following table lists the available query parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `delete_all_memories` | Boolean | Optional | Controls whether to delete all memory indexes when deleting the container. Default is `false`. When `false`, memory indexes (sessions, working, long-term, history) are preserved. | +| `delete_memories` | Array | Optional | Array of memory types to delete when deleting the container. Default is empty array. Accepts values: `sessions`, `working`, `long-term`, `history`. Example: `delete_memories=sessions,working`. | + +## Example request: Basic deletion (preserves memory indexes) ```json DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN ``` + +## Example request: Delete a container and all memory indexes + +```json +DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_all_memories=true +``` + +## Example request: Delete a container and specific memory types + +```json +DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_memories=sessions,working +``` {% include copy-curl.html %} ## Example response @@ -45,4 +71,17 @@ DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN "_seq_no": 6, "_primary_term": 1 } -``` \ No newline at end of file +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory container. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | +| `_seq_no` | Long | The sequence number assigned to the delete operation. | +| `_primary_term` | Long | The primary term of the index. | \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md index e7263b60e4..99779994a8 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/delete-memory.md @@ -1,47 +1,164 @@ --- layout: default -title: Delete agentic memory -parent: Agentic Memory APIs +title: Delete memory +parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 80 +nav_order: 53 --- -# Delete Agentic Memory API -**Introduced 3.2** +# Delete Memory API +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} +Use this API to delete a specific memory by its type and ID or to delete memories matching a query. This unified API supports deleting memories of any [memory type]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types): `sessions`, `working`, `long-term`, or `history`. -Use this API to delete an agentic memory by its ID. +## Delete a memory by type and ID -## Endpoint +Use this API to delete a memory by type and ID. + +### Endpoints ```json -DELETE /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} +DELETE /_plugins/_ml/memory_containers//memories// ``` -## Example request +### Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container from which to delete the memory. | +| `type` | String | Required | The type of memory to delete. Valid values are `sessions`, `working`, `long-term`, and `history`. | +| `id` | String | Required | The ID of the specific memory to delete. | + +### Example request: Delete a working memory ```json -DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM ``` {% include copy-curl.html %} -## Example response +### Example request: Delete a long-term memory + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` +{% include copy-curl.html %} + +### Example request: Delete a sessions memory + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE +``` +{% include copy-curl.html %} + +### Example request: Delete a history memory + +```json +DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU +``` +{% include copy-curl.html %} + +### Example response ```json { - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 3, - "result": "deleted", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 + "result": "deleted", + "_id": "XyEuiJkBeh2gPPwzjYWM", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +### Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the delete operation. | +| `_id` | String | The ID of the deleted memory. | +| `_version` | Integer | The version number after deletion. | +| `_shards` | Object | Information about the shards involved in the operation. | + +## Delete memories by query + +Use this API to delete multiple memories using a query to match specific criteria. + +### Endpoints + +```json +POST /_plugins/_ml/memory_containers//memories//_delete_by_query +``` + +### Path parameters + +| Field | Data type | Required/Optional | Description | +|:----------------------| :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container from which to delete the memory. | +| `type` | String | Required | The type of memory to delete. Valid values are `sessions`, `working`, `long-term`, and `history`. | + +### Request body fields + +The request body must contain a query to match the memories you want to delete. + +### Example request + +```json +POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_delete_by_query +{ + "query": { + "match": { + "owner_id": "admin" + } + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "took": 159, + "timed_out": false, + "total": 6, + "updated": 0, + "created": 0, + "deleted": 6, + "batches": 1, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 }, - "_seq_no": 3, - "_primary_term": 1 + "throttled_millis": 0, + "requests_per_second": -1.0, + "throttled_until_millis": 0, + "failures": [] } -``` \ No newline at end of file +``` + +### Response fields + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `took` | Integer | The time, in milliseconds, taken to execute the request. | +| `timed_out` | Boolean | Whether the request timed out. | +| `total` | Integer | The total number of documents processed. | +| `deleted` | Integer | The number of documents deleted. | +| `batches` | Integer | The number of batches processed. | +| `version_conflicts` | Integer | The number of version conflicts encountered. | +| `noops` | Integer | The number of no-operation updates. | +| `retries` | Object | Information about bulk and search retries. | +| `throttled_millis` | Integer | The time, in milliseconds, that the request was throttled. | +| `requests_per_second` | Float | The number of requests processed per second. | +| `throttled_until_millis` | Integer | The time, in milliseconds, until throttling is lifted. | +| `failures` | Array | Any failures that occurred during the operation. | + diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md index 33cad3b4f1..0521c33ba6 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory-container.md @@ -1,24 +1,22 @@ --- layout: default title: Get memory container -parent: Agentic Memory APIs +parent: Agentic memory APIs grand_parent: ML Commons APIs nav_order: 20 --- # Get Memory Container API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} Use this API to retrieve a memory container by its ID. -## Endpoint +## Endpoints ```json -GET /_plugins/_ml/memory_containers/{memory_container_id} +GET /_plugins/_ml/memory_containers/ ``` ## Example request diff --git a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md index 7030fc4b09..b647325f0f 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/get-memory.md @@ -1,57 +1,213 @@ --- layout: default -title: Get agentic memory -parent: Agentic Memory APIs +title: Get memory +parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 60 +nav_order: 51 --- -# Get Agentic Memory API -**Introduced 3.2** +# Get Memory API +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} +Use this API to retrieve a specific memory by its type and ID. This unified API supports the four [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types): `sessions`, `working`, `long-term`, and `history`. -Use this API to retrieve an agentic memory by its ID. +## Endpoints -## Endpoint +```json +GET /_plugins/_ml/memory_containers//memories// +``` + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container from which to retrieve the memory. | +| `type` | String | Required | The memory type. Valid values are `sessions`, `working`, `long-term`, and `history`. | +| `id` | String | Required | The ID of the memory to retrieve. | + +## Example request: Get a working memory + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +``` +{% include copy-curl.html %} + +## Example response: Working memory + +```json +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "memory_type": "conversation", + "messages": [ + { + "role": "user", + "content_text": "I'm Bob, I really like swimming." + }, + { + "role": "assistant", + "content_text": "Cool, nice. Hope you enjoy your life." + } + ], + "namespace": { + "user_id": "bob", + "session_id": "S-dqiJkB1SltqOcZ1cYO" + }, + "metadata": { + "status": "checkpoint", + "branch": "{\"root_event_id\":\"228nadfs879mtgk\",\"branch_name\":\"high\"}" + }, + "infer": true, + "tags": { + "topic": "personal info" + }, + "created_time": 1758930326804, + "last_updated_time": 1758930326804 +} +``` + +## Example request: Get a long-term memory + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz +``` +{% include copy-curl.html %} + +## Example response: Long-term memory + +```json +{ + "memory": "Kubernetes RBAC permission issues detected with CloudWatch agents experiencing persistent permission denials", + "strategy_type": "SUMMARY", + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "namespace": { + "agent_id": "chat-agent" + }, + "namespace_size": 1, + "created_time": 1760052801773, + "last_updated_time": 1760052801773, + "memory_embedding": [0.018510794, 0.056366503, "..."], + "owner_id": "admin", + "strategy_id": "summary_96f04d97" +} +``` + +## Example request: Get a session + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/CcxjTpkBvwXRq366A1aE +``` +{% include copy-curl.html %} + +## Example response: Session ```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} +{ + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" +} ``` -## Example request +## Example request: Get a history memory ```json -GET /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMxnTpkBvwXRq366hmAU ``` {% include copy-curl.html %} -## Example response +## Example response: History ```json { - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "memory": "Machine learning is a subset of artificial intelligence", - "memory_type": "RAW_MESSAGE", - "user_id": "admin", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 + "owner_id": "admin", + "memory_container_id": "nrJBy5kByIxXWyhQjmqv", + "memory_id": "4bJMy5kByIxXWyhQvGr9", + "action": "ADD", + "after": { + "memory": "A comprehensive security investigation was performed across multiple data sources including 55 OpenSearch indices, 50 CloudTrail events, 22 VPC Flow logs, 38 WAF events, 74 CloudWatch log groups, active CloudWatch alarms, and OpenSearch cluster security configuration." + }, + "namespace": { + "agent_id": "chat-agent" + }, + "namespace_size": 1, + "tags": { + "agent_type": "chat_agent", + "conversation": "true" + }, + "created_time": 1760052428089 } ``` -## Response body fields +## Response fields + +The response fields vary depending on the memory type. + +### Working memory response fields + +The following table lists all working memory response body fields. + +| Field | Data type | Description | +|:----------------------| :--- |:--------------------------------------------------------| +| `memory_container_id` | String | The ID of the memory container. | +| `payload_type` | String | The type of payload. Valid values are `conversation` and `data`. | +| `messages` | Array | Array of conversation messages (applicable only to the `conversation` memory type). | +| `namespace` | Object | The namespace context for this memory. | +| `metadata` | Object | Additional metadata associated with the memory. | +| `tags` | Object | Associated tags for categorization. | +| `infer` | Boolean | Whether inference was enabled for this memory. | +| `created_time` | Long | The timestamp of when the memory was created. | +| `last_updated_time` | Long | The timestamp of when the memory was last updated. | + +### Long-term memory response fields + +The following table lists all long-term memory response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The extracted long-term memory fact. | +| `strategy_type` | String | The type of memory strategy used (for example, `SEMANTIC`, `SUMMARY`, or `USER_PREFERENCE`). | +| `namespace` | Object | The namespace context for this memory. | +| `namespace_size` | Integer | The number of namespaces. | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | The timestamp when the memory was created. | +| `last_updated_time` | Long | The timestamp when the memory was last updated. | +| `memory_embedding` | Array | The vector embedding of the memory content (truncated in display). | +| `owner_id` | String | The ID of the memory owner. | +| `strategy_id` | String | The unique identifier for the strategy instance. | + +### Session response fields + +The following table lists all session response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory_container_id` | String | The ID of the memory container. | +| `namespace` | Object | The namespace context for this session. | +| `created_time` | String | The timestamp of when the session was created. | +| `last_updated_time` | String | The timestamp of when the session was last updated. | + +### History response fields -The following table lists all response body fields. +The following table lists all history response body fields. -| Field | Data type | Description | -| :------------------ | :-------- | :--------------------------------------------------------------------------------------- | -| `session_id` | String | The unique identifier for the session associated with this memory. | -| `memory` | String | If the memory was created with `infer: false`, contains the stored text from the message. If the memory was created with `infer: true`, contains the extracted fact from the message. | -| `memory_type` | String | The type of memory. `RAW_MESSAGE` indicates the unprocessed message text. `FACT` indicates a fact inferred by the large language model. | -| `user_id` | String | The ID of the user associated with this memory. | -| `role` | String | The role of the message author. Can be any string, such as `assistant` or `user`. | -| `created_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was created. | -| `last_updated_time` | Integer | The Unix timestamp, in milliseconds, when the memory entry was last updated. | +| Field | Data type | Description | +| :--- | :--- | :--- | +| `owner_id` | String | The ID of the memory owner. | +| `memory_container_id` | String | The ID of the memory container. | +| `memory_id` | String | The ID of the affected memory. | +| `action` | String | The type of operation: `ADD`, `UPDATE`, or `DELETE`. | +| `after` | Object | The memory content after the operation. | +| `before` | Object | The memory content before the operation (for `UPDATE` operations). | +| `namespace` | Object | The namespace context for this memory. | +| `namespace_size` | Integer | The number of namespaces. | +| `tags` | Object | Associated tags for categorization. | +| `created_time` | Long | The timestamp of when the operation occurred. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/index.md b/_ml-commons-plugin/api/agentic-memory-apis/index.md index ff5a7f73a6..c5d5698e0b 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/index.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Agentic Memory APIs +title: Agentic memory APIs parent: ML Commons APIs has_children: true has_toc: false @@ -9,41 +9,39 @@ redirect_from: - /ml-commons-plugin/api/agentic-memory-apis/ --- -# Agentic Memory APIs -**Introduced 3.2** +# Agentic memory APIs +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} +Agentic memory APIs provide persistent memory management for AI agents. For an overview of concepts, use cases, and getting started information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/). -Agentic Memory APIs provide persistent memory management for AI agents. This enables agents to learn, remember, and reason over structured information across conversations. +## Disabling agentic memory APIs -## Enabling Agentic Memory APIs - -To enable Agentic Memory APIs, update the following cluster setting: +Agentic memory APIs are enabled by default. To disable agentic memory APIs, update the following cluster setting: ```json PUT /_cluster/settings { "persistent": { - "plugins.ml_commons.agentic_memory_enabled": true + "plugins.ml_commons.agentic_memory_enabled": false } } ``` {% include copy-curl.html %} -For more information and other ways to enable experimental features, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). - OpenSearch supports the following memory container APIs: - [Create memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container/) - [Get memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory-container/) +- [Update memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory-container/) - [Delete memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-container/) +- [Search memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-container/) OpenSearch supports the following memory APIs: - [Add memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/add-memory/) +- [Create session]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-session/) - [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/) -- [Search memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) - [Update memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/update-memory/) -- [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) \ No newline at end of file +- [Delete memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory/) +- [Search memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory/) \ No newline at end of file diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md new file mode 100644 index 0000000000..b79c65fc99 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory-container.md @@ -0,0 +1,95 @@ +--- +layout: default +title: Search memory containers +parent: Agentic memory APIs +grand_parent: ML Commons APIs +nav_order: 25 +--- + +# Search Memory Containers API +**Introduced 3.3** +{: .label .label-purple } + +Use this API to search for memory containers using OpenSearch query domain-specific language (DSL). + +## Endpoints + +```json +GET /_plugins/_ml/memory_containers/_search +POST /_plugins/_ml/memory_containers/_search +``` + +## Request fields + +The request body supports standard OpenSearch query DSL. For more information, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). + +## Example request + +```json +GET /_plugins/_ml/memory_containers/_search +{ + "query": { + "match_all": {} + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": 1.0, + "hits": [ + { + "_index": ".plugins-ml-memory-meta", + "_id": "HudqiJkB1SltqOcZusVU", + "_score": 1.0, + "_source": { + "name": "agentic memory test", + "description": "Store conversations with semantic search and summarization", + "configuration": { + "embedding_model_type": "TEXT_EMBEDDING", + "embedding_model_id": "uXZAtJkBvHNmcp1JAROh", + "embedding_dimension": 1024, + "llm_id": "aFouy5kBrfmzAZ6R6wo-", + "strategies": [ + { + "type": "SEMANTIC", + "namespace": ["user_id"] + } + ] + }, + "created_time": 1757956737699, + "last_updated_time": 1757956737699 + } + } + ] + } +} +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `name` | String | The name of the memory container. | +| `description` | String | The description of the memory container. | +| `configuration` | Object | The memory container configuration, including models and strategies. | +| `created_time` | Long | The timestamp of when the container was created. | +| `last_updated_time` | Long | The timestamp of when the container was last updated. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md index bee96e6f0c..5b764edeb6 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/search-memory.md @@ -1,58 +1,194 @@ --- layout: default -title: Search agentic memory -parent: Agentic Memory APIs +title: Search memory +parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 70 +nav_order: 54 --- -# Search Agentic Memory APIs -**Introduced 3.2** +# Search Memory API +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} - -Use these APIs to to search for an agentic memory in a memory container. These APIs use a query to search for matching memories. +Use this API to search for memories of a specific type within a memory container. This unified API supports searching `sessions`, `working`, `long-term`, and `history` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types). ## Endpoints ```json -GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search -POST /_plugins/_ml/memory_containers/{memory_container_id}/memories/_search +GET /_plugins/_ml/memory_containers//memories//_search ``` -## Example request +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The memory type. Valid values are `sessions`, `working`, `long-term`, and `history`. | + +## Request fields + +The request body supports standard OpenSearch query domain-specific language (DSL). For more information, see [Query DSL]({{site.url}}{{site.baseurl}}/query-dsl/). + +## Example request: Search sessions ```json -POST /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/_search +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/_search { - "query": "machine learning concepts" + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] } ``` {% include copy-curl.html %} -## Example response +## Example request: Search long-term memories + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example request: Search a history memory + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/_search +{ + "query": { + "match_all": {} + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example request: Search working memories with a namespace filter + +```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search +{ + "query": { + "bool": { + "must": [ + { + "term": { + "namespace.user_id": "bob" + } + } + ], + "must_not": [ + { + "exists": { + "field": "tags.parent_memory_id" + } + } + ] + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } + } + ] +} +``` +{% include copy-curl.html %} + +## Example request: Search trace data by session ```json +GET /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/_search { - "timed_out": false, - "hits": { - "total": 1, - "max_score": 0.69813377, - "hits": [ - { - "memory_id": "T9jtmpgBOh0h20Y91WtZ", - "memory": "Machine learning is a subset of artificial intelligence", - "_score": 0.69813377, - "session_id": "sess_a99c5a19-cee3-44ce-b64d-6fbdc411c537", - "user_id": "admin", - "memory_type": "RAW_MESSAGE", - "role": "assistant", - "created_time": 1754945934681, - "last_updated_time": 1754945934681 - } - ] + "query": { + "term": { + "namespace.session_id": "123" + } + }, + "sort": [ + { + "created_time": { + "order": "desc" + } } + ] } -``` \ No newline at end of file +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": null, + "hits": [ + { + "_index": "test1-session", + "_id": "CcxjTpkBvwXRq366A1aE", + "_score": null, + "_source": { + "memory_container_id": "HudqiJkB1SltqOcZusVU", + "namespace": { + "user_id": "bob" + }, + "created_time": "2025-09-15T17:18:55.881276939Z", + "last_updated_time": "2025-09-15T17:18:55.881276939Z" + }, + "sort": ["2025-09-15T17:18:55.881276939Z"] + } + ] + } +} +``` + +## Response fields + +The response fields vary depending on the memory type being searched. For field descriptions, see [Get memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/get-memory/#response-fields). diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md new file mode 100644 index 0000000000..55659ce8d4 --- /dev/null +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory-container.md @@ -0,0 +1,120 @@ +--- +layout: default +title: Update memory container +parent: Agentic memory APIs +grand_parent: ML Commons APIs +nav_order: 15 +--- + +# Update Memory Container API +**Introduced 3.3** +{: .label .label-purple } + +Use this API to update an existing memory container's properties, such as name, description, configuration, and access permissions. + +## Endpoints + +```json +PUT /_plugins/_ml/memory_containers/ +``` + +## Path parameters + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container to update. | + +## Request fields + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `name` | String | Optional | The updated name of the memory container. | +| `description` | String | Optional | The updated description of the memory container. | +| `configuration` | Object | Optional | The configuration object containing strategies and embedding settings. See [The configuration object](#the-configuration-object). | + +### The configuration object + +The `configuration` object supports the following fields. + +| Field | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `llm_id` | String | Optional | The large language model (LLM) ID to use to extract facts. | +| `strategies` | Array | Optional | An array of strategy objects for memory processing. | +| `embedding_model_id` | String | Optional | The embedding model ID. Can only be updated if no long-term memory index exists. | +| `embedding_model_type` | String | Optional | The embedding model type. Can only be updated if no long-term memory index exists. | +| `embedding_dimension` | Integer | Optional | The embedding dimension. Can only be updated if no long-term memory index exists. | + +## Update behavior + +Note the following update behavior. + +### Strategy updates + +- To update a specific strategy, specify the strategy `id`. +- To create a new strategy, specify a strategy without an `id`. + +### Backend roles updates + +- Adding new `backend_roles` grants new users read or write access with those roles. +- The new `backend_roles` field overwrites the existing field, so include the original roles if you want to keep them. + +### Namespace updates + +- The `namespace` field in the `strategies` object is updated by overwriting. Include the original namespace if you want to keep it. + +### Embedding model restrictions + +- The `embedding_model_id`, `embedding_model_type`, and `embedding_dimension` fields can only be updated if no long-term memory index has been created for this memory container. Once a long-term memory index with the specified `index_prefix` is created, these embedding fields cannot be updated. + +## Example request + +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU +{ + "name": "opensearch-agents-memory", + "description": "Updated memory container for OpenSearch agents", + "backend_roles": ["admin", "ml_user"], + "configuration": { + "strategies": [ + { + "id": "existing_strategy_id", + "type": "summarization", + "namespace": "updated_namespace" + }, + { + "type": "keyword_extraction" + } + ], + "embedding_model_id": "new_embedding_model", + "embedding_model_type": "dense", + "embedding_dimension": 768 + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "result": "updated", + "_id": "HudqiJkB1SltqOcZusVU", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } +} +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory container. | +| `_version` | Integer | The version number of the updated memory container. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md index b6b2bc44ce..20e6b14261 100644 --- a/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md +++ b/_ml-commons-plugin/api/agentic-memory-apis/update-memory.md @@ -1,40 +1,105 @@ --- layout: default -title: Update agentic memory -parent: Agentic Memory APIs +title: Update memory +parent: Agentic memory APIs grand_parent: ML Commons APIs -nav_order: 50 +nav_order: 52 --- -# Update Agentic Memory API -**Introduced 3.2** +# Update Memory API +**Introduced 3.3** {: .label .label-purple } -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, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} +Use this API to update a specific memory by its type and ID. This unified API supports updating `sessions`, `working`, and `long-term` [memory types]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/#memory-types). `history` memory does not support updates. -Use this API to update an agentic memory. - -## Endpoint +## Endpoints ```json -PUT /_plugins/_ml/memory_containers/{memory_container_id}/memories/{memory_id} +PUT /_plugins/_ml/memory_containers//memories// ``` -## Request body fields +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Required/Optional | Description | +| :--- | :--- | :--- | :--- | +| `memory_container_id` | String | Required | The ID of the memory container. | +| `type` | String | Required | The memory type. Valid values are `sessions`, `working`, and `long-term`. Note that `history` memory cannot be updated. | +| `id` | String | Required | The ID of the memory to update. | + +## Request fields + +The request fields vary depending on the memory type being updated. All request fields are optional. + +### Session memory request fields + +The following table lists all session memory request body fields. + +| Field | Data type | Description | +|:-----------|:----------------------| :--- | +| `summary` | String | The summary of the session. +| `metadata` | Object | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). | +| `agents` | Object | Additional information about the agents. | +| `additional_info` | Object | Additional metadata to associate with the session. | + +### Working memory request fields + +The following table lists all working memory request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `messages` | Array | Updated conversation messages (for conversation type). Optional. | +| `structured_data` | Object | Updated structured data content (for `data` memory payloads). | +| `binary_data` | Object | Updated binary data content (for `data` memory payloads). Optional. | +| `tags` | Object | Updated tags for categorization. | +| `metadata` | Object | Additional metadata for the memory (for example, `status`, `branch`, or custom fields). + +### Long-term memory request fields + +The following table lists all long-term memory request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `memory` | String | The updated memory content. Optional. | +| `tags` | Object | Updated tags for categorization. Optional. | + +## Example request: Update a session -The following table lists the available request body fields. +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/sessions/N2CDipkB2Mtr6INFFcX8 +{ + "additional_info": { + "key1": "value1", + "last_activity": "2025-09-15T17:30:00Z" + } +} +``` +{% include copy-curl.html %} -Field | Data type | Required/Optional | Description -:--- | :--- | :--- | :--- -`text` | String | Required | The updated `text` content. +## Example request: Update a working memory -## Example request +```json +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/working/XyEuiJkBeh2gPPwzjYWM +{ + "tags": { + "topic": "updated_topic", + "priority": "high" + } +} +``` +{% include copy-curl.html %} + +## Example request: Update a long-term memory ```json -PUT /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20Y91WtZ +PUT /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/DcxjTpkBvwXRq366C1Zz { - "text": "Updated content with new information about machine learning" + "memory": "User's name is Bob Smith", + "tags": { + "topic": "personal info", + "updated": "true" + } } ``` {% include copy-curl.html %} @@ -43,16 +108,24 @@ PUT /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN/memories/T9jtmpgBOh0h20 ```json { - "_index": "ml-static-memory-sdjmmpgboh0h20y9kwun-admin", - "_id": "S9jnmpgBOh0h20Y9qWu7", - "_version": 2, - "result": "updated", - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "_seq_no": 2, - "_primary_term": 1 + "result": "updated", + "_id": "N2CDipkB2Mtr6INFFcX8", + "_version": 2, + "_shards": { + "total": 2, + "successful": 1, + "failed": 0 + } } -``` \ No newline at end of file +``` + +## Response fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `result` | String | The result of the update operation. | +| `_id` | String | The ID of the updated memory. | +| `_version` | Integer | The version number of the updated memory. | +| `_shards` | Object | Information about the shards involved in the operation. | diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md new file mode 100644 index 0000000000..865d79bd2a --- /dev/null +++ b/_ml-commons-plugin/api/execute-tool.md @@ -0,0 +1,126 @@ +--- +layout: default +title: Execute tool +parent: ML Commons APIs +nav_order: 100 +--- + +# Execute Tool API +**Introduced 3.3** +{: .label .label-purple } + +The Execute Tool API allows you to run individual tools directly without creating an agent first. This API is particularly beneficial for applications requiring quick, single-tool operations where the overhead of agent creation and management is unnecessary. + +## Use cases + +The Execute Tool API is ideal for: + +- **Direct tool execution**: Run specific tools like search, data analysis, or retrieval operations without agent setup. +- **Testing and debugging**: Quickly test tool functionality during development. +- **Lightweight integrations**: Integrate specific OpenSearch capabilities into applications without full agent workflows. +- **Standalone operations**: Perform single tasks that don't require conversation memory or complex orchestration. + +## Supported tools + +This API supports all available OpenSearch tools. Each tool can be executed independently with its specific parameters. + +For more information regarding the list of available tools, see [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/). + +## Endpoint + +```json +POST /_plugins/_ml/tools/_execute/ +``` + +The `` parameter refers to the predefined tool type name, such as `PPLTool`, `SearchIndexTool`, or `VectorDBTool`,---not a custom tool name that you define. +{: .note} + +## Request body fields + +The following table lists all request body fields. + +| Field | Data type | Required | Description | +| :--- | :--- | :--- | :--- | +| `parameters` | Object | Yes | Contains tool-specific parameters that vary depending on the tool being executed. Each tool requires different parameters based on its functionality. | + +### Parameter structure + +The `parameters` object combines the parameters used during tool registration and tool execution. The specific fields depend on the tool being executed. + +To determine the required parameters for a specific tool, refer to the individual tool documentation in the [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/) section. + +| Component | Description | +|:-------------------------|:-----------------------------------------------| +| Tool registration parameters | Parameters specified during tool registration. | +| Tool execution parameters | Parameters specified during tool execution. | + +## Example requests + +The following are examples of both simple and complex tool execution. + +### Example 1: Simple tool execution + +```json +POST /_plugins/_ml/tools/_execute/ListIndexTool +{ + "parameters": { + "question": "How many indices do I have?" + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": """row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards) +1,yellow,open,movies,kKcJKu2aT0C9uwJIPP4hxw,2,1,2,0,7.8kb,7.8kb +2,green,open,.plugins-ml-config,h8ovp_KFTq6_zvcBEn2kvg,1,0,1,0,4kb,4kb +3,green,open,.plugins-ml-agent,1oGlUBCIRAGXLbLv27Qg8w,1,0,1,0,8kb,8kb +""" + } + ] + } + ] +} +``` + +### Example 2: Complex tool execution + +```json +POST /_plugins/_ml/tools/_execute/PPLTool +{ + "parameters": { + "question": "what's the population of Seattle in 2021?", + "index": "test-population", + "model_id": "1TuQQ5gBMJhRgCqgSV79" + } +} + +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "dataAsMap": { + "result":"{\"ppl\":\"source\=test-population | where QUERY_STRING([\'population_description\'], \'Seattle\') AND QUERY_STRING([\'population_description\'], \'2021\')\",\"executionResult\":\"{\\n \\\"schema\\\": [\\n {\\n \\\"name\\\": \\\"population_description\\\",\\n \\\"type\\\": \\\"string\\\"\\n }\\n ],\\n \\\"datarows\\\": [],\\n \\\"total\\\": 0,\\n \\\"size\\\": 0\\n}\"}" + } + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index ab34d954c0..ed7ef546a4 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -21,7 +21,16 @@ OpenSearch supports the following machine learning (ML) APIs: - [Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/) - [Controller APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/controller-apis/index/) - [Execute Algorithm API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-algorithm/) +- [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/) - [Tasks APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/index/) - [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/) - [Stats API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/stats/) -- [MCP Server APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/mcp-server-apis/) \ No newline at end of file +- [MCP Server APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/mcp-server-apis/) + +## Memory APIs comparison + +OpenSearch provides two different memory systems: + +- **[Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/index/)** -- Simple conversation history storage for [conversational search]({{site.url}}{{site.baseurl}}/search-plugins/conversational-search/). Stores question/answer pairs chronologically without processing or learning. + +- **[Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/)** -- Intelligent memory system for AI agents. Uses large language models (LLMs) to extract knowledge, learn user preferences, and maintain context across sessions. For conceptual information, see [Agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/). \ No newline at end of file diff --git a/_ml-commons-plugin/api/profile.md b/_ml-commons-plugin/api/profile.md index dc9ec94cbe..f281c25dcf 100644 --- a/_ml-commons-plugin/api/profile.md +++ b/_ml-commons-plugin/api/profile.md @@ -2,7 +2,7 @@ layout: default title: Profile parent: ML Commons APIs -nav_order: 100 +nav_order: 110 --- # Profile API diff --git a/_ml-commons-plugin/api/stats.md b/_ml-commons-plugin/api/stats.md index 45b145effe..43b31b3806 100644 --- a/_ml-commons-plugin/api/stats.md +++ b/_ml-commons-plugin/api/stats.md @@ -2,7 +2,7 @@ layout: default title: Stats parent: ML Commons APIs -nav_order: 110 +nav_order: 120 --- # Stats API diff --git a/_ml-commons-plugin/cluster-settings.md b/_ml-commons-plugin/cluster-settings.md index 2cab887487..65518bdd33 100644 --- a/_ml-commons-plugin/cluster-settings.md +++ b/_ml-commons-plugin/cluster-settings.md @@ -18,6 +18,7 @@ By default, ML tasks and models only run on ML nodes. When configured without th ```yml node.roles: [ ml ] ``` +{% include copy.html %} ### Setting up a cluster with a dedicated ML node @@ -38,6 +39,7 @@ We recommend setting `plugins.ml_commons.only_run_on_ml_node` to `true` on produ ```yaml plugins.ml_commons.only_run_on_ml_node: true ``` +{% include copy.html %} ### Values @@ -54,6 +56,7 @@ plugins.ml_commons.only_run_on_ml_node: true ```yaml plugins.ml_commons.task_dispatch_policy: round_robin ``` +{% include copy.html %} ### Values @@ -70,6 +73,7 @@ Sets the number of ML tasks that can run on each ML node. When set to `0`, no ML ```yaml plugins.ml_commons.max_ml_task_per_node: 10 ``` +{% include copy.html %} ### Values @@ -85,6 +89,7 @@ Sets the number of ML models that can be deployed to each ML node. When set to ` ```yaml plugins.ml_commons.max_model_on_node: 10 ``` +{% include copy.html %} ### Values @@ -101,6 +106,7 @@ When returning runtime information with the [Profile API]({{site.url}}{{site.bas ```yaml plugins.ml_commons.sync_up_job_interval_in_seconds: 3 ``` +{% include copy.html %} ### Values @@ -116,6 +122,7 @@ Controls how many predict requests are monitored on one node. If set to `0`, Ope ```yaml plugins.ml_commons.monitoring_request_count: 100 ``` +{% include copy.html %} ### Value range @@ -131,6 +138,7 @@ Controls how many register model tasks can run in parallel on one node. If set t ```yaml plugins.ml_commons.max_register_model_tasks_per_node: 10 ``` +{% include copy.html %} ### Values @@ -148,6 +156,7 @@ Controls how many deploy model tasks can run in parallel on one node. If set to ```yaml plugins.ml_commons.max_deploy_model_tasks_per_node: 10 ``` +{% include copy.html %} ### Values @@ -163,6 +172,7 @@ This setting gives you the ability to register models using a URL. By default, M ```yaml plugins.ml_commons.allow_registering_model_via_url: false ``` +{% include copy.html %} ### Values @@ -178,6 +188,7 @@ This setting gives you the ability to register a model using a local file. By de ```yaml plugins.ml_commons.allow_registering_model_via_local_file: false ``` +{% include copy.html %} ### Values @@ -198,6 +209,7 @@ The default URL value for this trusted URL setting is not secure. For security, ```yaml plugins.ml_commons.trusted_url_regex: ``` +{% include copy.html %} ### Values @@ -213,6 +225,7 @@ Assigns how long in seconds an ML task will live. After the timeout, the task wi ```yaml plugins.ml_commons.ml_task_timeout_in_seconds: 600 ``` +{% include copy.html %} ### Values @@ -232,6 +245,7 @@ Starting with OpenSearch 2.5, ML Commons runs a native memory circuit breaker to ```yaml plugins.ml_commons.native_memory_threshold: 90 ``` +{% include copy.html %} ### Values @@ -249,6 +263,7 @@ Values are based on the percentage of JVM heap memory available. When set to `0` ```yaml plugins.ml_commons.jvm_heap_memory_threshold: 85 ``` +{% include copy.html %} ### Values @@ -266,6 +281,7 @@ Valid values are in byte units. To disable the circuit breaker, set this value t ```yaml plugins.ml_commons.disk_free_space_threshold: 5G ``` +{% include copy.html %} ### Values @@ -281,6 +297,7 @@ Use this setting to specify the names of nodes on which you don't want to run ML ```yaml plugins.ml_commons.exclude_nodes._name: node1, node2 ``` +{% include copy.html %} ## Allow custom deployment plans @@ -291,6 +308,7 @@ When enabled, this setting grants users the ability to deploy models to specific ```yaml plugins.ml_commons.allow_custom_deployment_plan: false ``` +{% include copy.html %} ### Values @@ -306,6 +324,7 @@ This setting is applicable when you send a prediction request for an externally ```yaml plugins.ml_commons.model_auto_deploy.enable: false ``` +{% include copy.html %} ### Values @@ -319,8 +338,9 @@ This setting automatically redeploys deployed or partially deployed models upon ### Setting ```yaml -plugins.ml_commons.model_auto_redeploy.enable: true +plugins.ml_commons.model_auto_redeploy.enable: true ``` +{% include copy.html %} ### Values @@ -336,6 +356,7 @@ This setting sets the limit for the number of times a deployed or partially depl ```yaml plugins.ml_commons.model_auto_redeploy.lifetime_retry_times: 3 ``` +{% include copy.html %} ### Values @@ -351,6 +372,7 @@ This setting sets the ratio of success for the auto-redeployment of a model base ```yaml plugins.ml_commons.model_auto_redeploy_success_ratio: 0.8 ``` +{% include copy.html %} ### Values @@ -366,6 +388,8 @@ When set to `true`, this setting enables the ability to run Python-based models ```yaml plugins.ml_commons.enable_inhouse_python_model: false ``` +{% include copy.html %} + ### Values @@ -383,6 +407,7 @@ When set to `true`, this setting enables a safety feature that checks for downst ```yaml plugins.ml_commons.safe_delete_model: true ``` +{% include copy.html %} ### Values @@ -399,6 +424,7 @@ When set to `true`, the setting allows admins to control access and permissions ```yaml plugins.ml_commons.connector_access_control_enabled: true ``` +{% include copy.html %} ### Values @@ -414,6 +440,7 @@ This setting allows a cluster admin to enable running local models on the cluste ```yaml plugins.ml_commons.local_model.enabled: true ``` +{% include copy.html %} ### Values @@ -429,6 +456,7 @@ This setting allows a cluster admin to control the types of nodes on which exter ```yaml plugins.ml_commons.task_dispatcher.eligible_node_role.remote_model: ["ml"] ``` +{% include copy.html %} ### Values @@ -444,6 +472,7 @@ This setting allows a cluster admin to control the types of nodes on which local ```yaml plugins.ml_commons.task_dispatcher.eligible_node_role.remote_model: ["ml"] ``` +{% include copy.html %} ### Values @@ -458,6 +487,7 @@ This setting allows a cluster admin to enable remote inference on the cluster. I ```yaml plugins.ml_commons.remote_inference.enabled: true ``` +{% include copy.html %} ### Values @@ -473,6 +503,7 @@ When set to `true`, this setting enables the agent framework (including agents a ```yaml plugins.ml_commons.agent_framework_enabled: true ``` +{% include copy.html %} ### Values @@ -488,12 +519,28 @@ When set to `true`, this setting enables conversational memory, which stores all ```yaml plugins.ml_commons.memory_feature_enabled: true ``` +{% include copy.html %} ### Values - Default value: `true` - Valid values: `false`, `true` +## Enable agentic memory + +When set to `true`, this setting enables [agentic memory]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agentic-memory/), which provides advanced memory management for AI agents, including session memory, working memory, long-term memory, and memory history with namespace-based organization. + +### Setting + +```yaml +plugins.ml_commons.agentic_memory_enabled: true +``` +{% include copy.html %} + +### Values + +- Default value: `true` +- Valid values: `false`, `true` ## Enable RAG pipeline @@ -504,6 +551,7 @@ When set to `true`, this setting enables the search processors for retrieval-aug ```yaml plugins.ml_commons.rag_pipeline_feature_enabled: true ``` +{% include copy.html %} ### Values