From 706e0b00ec48db0dc8b50b998b01d65e81d9fc10 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 7 Nov 2025 17:37:21 +0100 Subject: [PATCH 01/13] =?UTF-8?q?[Agent=20Builder]=C2=A0Add=20page=20about?= =?UTF-8?q?=20permissions=20and=20access=20control?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- solutions/search/agent-builder/get-started.md | 4 + solutions/search/agent-builder/permissions.md | 96 +++++++++++++++++++ solutions/search/elastic-agent-builder.md | 6 ++ solutions/toc.yml | 1 + 4 files changed, 107 insertions(+) create mode 100644 solutions/search/agent-builder/permissions.md diff --git a/solutions/search/agent-builder/get-started.md b/solutions/search/agent-builder/get-started.md index db1e712a7d..3e5c393661 100644 --- a/solutions/search/agent-builder/get-started.md +++ b/solutions/search/agent-builder/get-started.md @@ -52,6 +52,10 @@ Find **Agents** in the navigation menu to begin using the feature, or search for :::: +:::{note} +To learn about required privileges for {{agent-builder}}, refer to [Permissions and access control](permissions.md). +::: + ::::: ::::{step} Ingest some data diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md new file mode 100644 index 0000000000..3e9660d0d0 --- /dev/null +++ b/solutions/search/agent-builder/permissions.md @@ -0,0 +1,96 @@ +--- +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview + observability: unavailable + security: unavailable +navigation_title: "Permissions & access control" +--- + + +# Permissions and access control in {{agent-builder}} + +Use this page to learn how to configure security roles and API keys for Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. + +Agent Builder requires privileges at three levels: + +- [{{kib}} feature access](#kib-privileges) +- [{{es}} cluster access](#es-cluster-privileges) +- [{{es}} index access](#es-index-privileges) + +### {{kib}} privileges + +Agent Builder uses two {{kib}} privileges within the `agentBuilder` feature: + +- `read_onechat`: Required to use agents, send chat messages, view tools, and access conversations. Maps to the "Read" feature privilege. +- `manage_onechat`: Required to create, update, or delete custom agents and tools. Maps to the "All" feature privilege along with `read_onechat`. + +Learn more about [{{kib}} privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-kibana). + +### {{es}} cluster privileges + +Agent Builder requires cluster-level privileges for AI-powered query generation: + +- `monitor_inference`: Required for agents to use AI-powered tools. The built-in tools `search` and `generate_esql`, as well as [index search tools](tools/index-search-tools.md), call the {{es}} Inference API to generate queries from natural language. + +Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster). + +### {{es}} index privileges + +Tools execute queries against {{es}} indices as the current user. Required privileges depend on which indices the tools access: + +- `read`: Required for tools that query data, including `execute_esql`, `search`, `get_document_by_id`, and [{{esql}} tools](tools/esql-tools.md) +- `view_index_metadata`: Required for tools that inspect index structure, including `list_indices`, `get_index_mapping`, and `index_explorer` + +Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). + +### Granting access with roles + +[Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. + +Example role for users who need full Agent Builder access: + +```json +POST /_security/role/agent-builder-full +{ + "cluster": ["monitor_inference"], + "indices": [ + { + "names": ["logs-*", "metrics-*"], + "privileges": ["read", "view_index_metadata"] + } + ], + "applications": [ + { + "application": "kibana-.kibana", + "privileges": ["feature_agentBuilder.all"], + "resources": ["space:default"] + } + ] +} +``` + +:::{tip} +For read-only access, use `feature_agentBuilder.read` instead of `feature_agentBuilder.all`. +::: + +### API keys for programmatic access + +When using the Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges. + +Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the {{kib}} API layer rather than through the UI. + +See these pages for API key configuration examples: +- [MCP server](mcp-server.md#api-key-application-privileges) +- [{{kib}} API](kibana-api.md) + +Learn more about [API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md). + +### Spaces + +Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space. + +When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. + +Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md). \ No newline at end of file diff --git a/solutions/search/elastic-agent-builder.md b/solutions/search/elastic-agent-builder.md index b6f74ee423..5b6c0915fa 100644 --- a/solutions/search/elastic-agent-builder.md +++ b/solutions/search/elastic-agent-builder.md @@ -66,6 +66,12 @@ These interfaces enable you to build integrations with other applications and ex [**Learn more about programmatic access**](agent-builder/programmatic-access.md) +## Permissions and access control + +Configure security roles and API keys to control who can use agents, which tools they can access, and what data they can query. + +[**Learn more about permissions and access control**](agent-builder/permissions.md) + ## Limitations and known issues {{agent-builder}} is in technical preview. diff --git a/solutions/toc.yml b/solutions/toc.yml index 2a824dabd3..5aff742331 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -77,6 +77,7 @@ toc: - file: search/agent-builder/kibana-api.md - file: search/agent-builder/a2a-server.md - file: search/agent-builder/mcp-server.md + - file: search/agent-builder/permissions.md - file: search/agent-builder/limitations-known-issues.md - file: search/rag.md children: From 683b1e7cca1c7f575d7869e436a7382d8686a65c Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 7 Nov 2025 17:42:42 +0100 Subject: [PATCH 02/13] fix link --- solutions/search/agent-builder/permissions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 3e9660d0d0..e4ad96b7c8 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -26,7 +26,7 @@ Agent Builder uses two {{kib}} privileges within the `agentBuilder` feature: - `read_onechat`: Required to use agents, send chat messages, view tools, and access conversations. Maps to the "Read" feature privilege. - `manage_onechat`: Required to create, update, or delete custom agents and tools. Maps to the "All" feature privilege along with `read_onechat`. -Learn more about [{{kib}} privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-kibana). +Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). ### {{es}} cluster privileges @@ -81,7 +81,7 @@ When using the Agent Builder APIs programmatically, authenticate with an API key Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the {{kib}} API layer rather than through the UI. -See these pages for API key configuration examples: +Refer to these pages for API key configuration examples: - [MCP server](mcp-server.md#api-key-application-privileges) - [{{kib}} API](kibana-api.md) From 99d633e0a6b18c335e8fda55882caf7f09371e85 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Sat, 8 Nov 2025 12:34:03 +0100 Subject: [PATCH 03/13] Clarify spaces URLs, add known issue for copy button - Document space-aware URL format for MCP server and APIs - Add known issue: copy button doesn't include space name in URL --- .../search/agent-builder/limitations-known-issues.md | 10 +++++++++- solutions/search/agent-builder/mcp-server.md | 7 +++++++ solutions/search/agent-builder/permissions.md | 6 ++++++ solutions/search/agent-builder/tools.md | 4 ++++ 4 files changed, 26 insertions(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index 52f41bec7e..1e15a4d6d2 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -67,4 +67,12 @@ This results in parsing errors like this: ] ``` - +### MCP server URL copy button does not include space name + +When using the **Copy your MCP server URL** button in the Tools UI from a custom {{kib}} Space, the copied URL does not include the space name in the path. + +**Workaround:** Manually add `/s/` to the URL after your deployment URL. For example: `https:///s//api/agent_builder/mcp` + +For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#spaces). + + diff --git a/solutions/search/agent-builder/mcp-server.md b/solutions/search/agent-builder/mcp-server.md index b486d58d91..fbe9011e0f 100644 --- a/solutions/search/agent-builder/mcp-server.md +++ b/solutions/search/agent-builder/mcp-server.md @@ -19,6 +19,13 @@ The MCP server is available at: ``` {KIBANA_URL}/api/agent_builder/mcp ``` + +When using a custom {{kib}} Space, include the space name in the URL: + +``` +{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp +``` + :::{tip} You can copy your MCP server URL directly in the Tools GUI. Refer to [](tools.md#copy-your-mcp-server-url). ::: diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index e4ad96b7c8..425d2b582c 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -93,4 +93,10 @@ Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom ag When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. +:::{important} +When accessing Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...` + +The default space uses the standard URL format without `/s/`. +::: + Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md). \ No newline at end of file diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 6075aa3e8c..6445e199a3 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -208,4 +208,8 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access. :width: 250px ::: +:::{important} +If you're using a custom {{kib}} Space, the copied URL will not include the space name. You must manually add `/s/` to the URL path. For example: `https:///s//api/agent_builder/mcp` +::: + For detailed MCP server configuration, refer to [MCP server](mcp-server.md). From c0d6a32bd2e325d968569bc66ea9d4bdebc96067 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 10 Nov 2025 09:59:45 +0100 Subject: [PATCH 04/13] add another link to MCP copy URL --- solutions/search/agent-builder/permissions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 425d2b582c..50090226b4 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -93,6 +93,8 @@ Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom ag When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. +Learn how to [Copy your MCP server URL](tools.md#copy-your-mcp-server-url). + :::{important} When accessing Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...` From 78b699e083e506ba917c2daf716d349eacad7246 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Thu, 13 Nov 2025 16:49:30 +0100 Subject: [PATCH 05/13] incorporate Pierre's feedback, minor cleanups --- solutions/search/agent-builder/permissions.md | 16 ++++++++++------ solutions/search/agent-builder/tools.md | 14 +++++++------- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 50090226b4..71ea41c1b5 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -21,10 +21,11 @@ Agent Builder requires privileges at three levels: ### {{kib}} privileges -Agent Builder uses two {{kib}} privileges within the `agentBuilder` feature: +Agent Builder access control is managed by the `agentBuilder` {{kib}} feature: -- `read_onechat`: Required to use agents, send chat messages, view tools, and access conversations. Maps to the "Read" feature privilege. -- `manage_onechat`: Required to create, update, or delete custom agents and tools. Maps to the "All" feature privilege along with `read_onechat`. +- "Read" access to the `agentBuilder` feature: Required to use agents, send chat messages, view tools, and access conversations. +- "All" access to the `agentBuilder` feature: Required to create, update, or delete custom agents and tools. +- "Read" access to the "Actions and Connectors" feature: Required to use AI connectors with agents. Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). @@ -40,8 +41,8 @@ Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsea Tools execute queries against {{es}} indices as the current user. Required privileges depend on which indices the tools access: -- `read`: Required for tools that query data, including `execute_esql`, `search`, `get_document_by_id`, and [{{esql}} tools](tools/esql-tools.md) -- `view_index_metadata`: Required for tools that inspect index structure, including `list_indices`, `get_index_mapping`, and `index_explorer` +- `read`: Required for tools that query data +- `view_index_metadata`: Required for tools that inspect index structure. Also required for the built-in `search` tool and [index search tools](tools/index-search-tools.md), which may use index exploration capabilities internally Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). @@ -64,7 +65,10 @@ POST /_security/role/agent-builder-full "applications": [ { "application": "kibana-.kibana", - "privileges": ["feature_agentBuilder.all"], + "privileges": [ + "feature_agentBuilder.all", + "feature_actions.read" + ], "resources": ["space:default"] } ] diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 6445e199a3..97ae313761 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -40,13 +40,13 @@ Each tool is an atomic operation with a defined signature - accepting typed para Key built-in tools include: -- **`.execute_esql`**: Executes an {{esql}} query and returns the results in a tabular format -- **`.generate_esql`**: Generates an {{esql}} query from a natural language query -- **`.get_document_by_id`**: Retrieves the full content of an {{es}} document based on its ID and index name -- **`.get_index_mapping`**: Retrieves mappings for the specified index or indices -- **`.index_explorer`**: Lists relevant indices and corresponding mappings based on a natural language query -- **`.list_indices`**: Lists the indices in the {{es}} cluster the current user has access to -- **`.search`**: A powerful tool for searching and analyzing data within a specific {{es}} index +- `.execute_esql`: Executes an {{esql}} query and returns the results in a tabular format +- `.generate_esql`: Generates an {{esql}} query from a natural language query +- `.get_document_by_id`: Retrieves the full content of an {{es}} document based on its ID and index name +- `.get_index_mapping`: Retrieves mappings for the specified index or indices +- `.index_explorer`: Lists relevant indices and corresponding mappings based on a natural language query +- `.list_indices`: Lists the indices in the {{es}} cluster the current user has access to +- `.search`: Searches and analyzes data within a specific {{es}} index Built-in tools serve as building blocks for more complex interactions and provide the foundation for agent capabilities. From 031280f132175d9d95721dc5a2b772bfe3caedf8 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Thu, 13 Nov 2025 16:57:19 +0100 Subject: [PATCH 06/13] clarify version for copy mcp url button bug --- .../search/agent-builder/limitations-known-issues.md | 10 +++++++--- solutions/search/agent-builder/tools.md | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index 1e15a4d6d2..370197f790 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -67,11 +67,15 @@ This results in parsing errors like this: ] ``` -### MCP server URL copy button does not include space name +### MCP server URL copy button omits space name -When using the **Copy your MCP server URL** button in the Tools UI from a custom {{kib}} Space, the copied URL does not include the space name in the path. +:::{note} +Fixed on serverless and 9.3. +::: -**Workaround:** Manually add `/s/` to the URL after your deployment URL. For example: `https:///s//api/agent_builder/mcp` +On 9.2 deployments, the **Copy your MCP server URL** button does not include the space name when used from a custom {{kib}} Space. + +**Workaround:** Manually add `/s/` to the URL. For example: `https:///s//api/agent_builder/mcp` For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#spaces). diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 97ae313761..8400707c9e 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -209,7 +209,7 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access. ::: :::{important} -If you're using a custom {{kib}} Space, the copied URL will not include the space name. You must manually add `/s/` to the URL path. For example: `https:///s//api/agent_builder/mcp` +There is a [known issue](limitations-known-issues.md#mcp-server-url-copy-button-does-not-include-space-name) with the copy button in 9.2. ::: For detailed MCP server configuration, refer to [MCP server](mcp-server.md). From 72d544921e68dd17eb1bb2527b77c162ced5b3a4 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Thu, 13 Nov 2025 17:03:49 +0100 Subject: [PATCH 07/13] fix anchor --- solutions/search/agent-builder/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 8400707c9e..b2fe7657f5 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -209,7 +209,7 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access. ::: :::{important} -There is a [known issue](limitations-known-issues.md#mcp-server-url-copy-button-does-not-include-space-name) with the copy button in 9.2. +There is a [known issue](limitations-known-issues.md#mcp-server-url-copy-button-omits-space-name) with the copy button in 9.2. ::: For detailed MCP server configuration, refer to [MCP server](mcp-server.md). From ba1355f81182ab3f059998f5bd22a720a8f57831 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 17 Nov 2025 19:16:40 +0100 Subject: [PATCH 08/13] update roles and AI connector info --- solutions/search/agent-builder/permissions.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 71ea41c1b5..8544b3121d 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -8,7 +8,6 @@ applies_to: navigation_title: "Permissions & access control" --- - # Permissions and access control in {{agent-builder}} Use this page to learn how to configure security roles and API keys for Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. @@ -33,7 +32,7 @@ Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-depl Agent Builder requires cluster-level privileges for AI-powered query generation: -- `monitor_inference`: Required for agents to use AI-powered tools. The built-in tools `search` and `generate_esql`, as well as [index search tools](tools/index-search-tools.md), call the {{es}} Inference API to generate queries from natural language. +- `monitor_inference`: Required when the agent uses an AI connector that calls the {{es}} Inference API (such as the Elastic default LLM or other AI connectors configured to use the Inference API). The built-in tools `search` and `generate_esql`, as well as [index search tools](tools/index-search-tools.md), use this API to generate queries from natural language. This privilege is not required when the agent uses other {{kib}} GenAI connectors. Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster). @@ -50,6 +49,10 @@ Learn more about [index privileges](elasticsearch://reference/elasticsearch/secu [Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. +:::{note} +When configuring roles in the {{kib}} UI, Agent Builder privileges are currently located under the **Analytics** section, not the {{es}} section. +::: + Example role for users who need full Agent Builder access: ```json From 2cc7b21f662d68f5c8dfaacfc54f37c93b4065c5 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:00:28 +0100 Subject: [PATCH 09/13] reorganize headings --- solutions/search/agent-builder/permissions.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 8544b3121d..b2abf7a495 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -12,10 +12,12 @@ navigation_title: "Permissions & access control" Use this page to learn how to configure security roles and API keys for Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. +## Required privileges + Agent Builder requires privileges at three levels: - [{{kib}} feature access](#kib-privileges) -- [{{es}} cluster access](#es-cluster-privileges) +- [{{es}} cluster access](#es-cluster-privileges) - [{{es}} index access](#es-index-privileges) ### {{kib}} privileges @@ -45,7 +47,9 @@ Tools execute queries against {{es}} indices as the current user. Required privi Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). -### Granting access with roles +## Grant access + +### Grant access with roles [Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. @@ -82,7 +86,7 @@ POST /_security/role/agent-builder-full For read-only access, use `feature_agentBuilder.read` instead of `feature_agentBuilder.all`. ::: -### API keys for programmatic access +### Grant access with API keys When using the Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges. @@ -94,7 +98,7 @@ Refer to these pages for API key configuration examples: Learn more about [API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md). -### Spaces +### Working with Spaces Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space. From 34042738a920770da53341c73e22b4bbd90a881b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:04:19 +0100 Subject: [PATCH 10/13] fix anchor --- solutions/search/agent-builder/limitations-known-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index 370197f790..f5cfadd94f 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -77,6 +77,6 @@ On 9.2 deployments, the **Copy your MCP server URL** button does not include the **Workaround:** Manually add `/s/` to the URL. For example: `https:///s//api/agent_builder/mcp` -For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#spaces). +For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#working-with-spaces). From 612f24c974f14c57e970cbd440914393faae8920 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 18 Nov 2025 11:29:17 +0100 Subject: [PATCH 11/13] Update solutions/search/agent-builder/permissions.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- solutions/search/agent-builder/permissions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index b2abf7a495..15d374009e 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -42,8 +42,8 @@ Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsea Tools execute queries against {{es}} indices as the current user. Required privileges depend on which indices the tools access: -- `read`: Required for tools that query data -- `view_index_metadata`: Required for tools that inspect index structure. Also required for the built-in `search` tool and [index search tools](tools/index-search-tools.md), which may use index exploration capabilities internally +- `read`: Required for tools that query data. +- `view_index_metadata`: Required for tools that inspect index structure. Also required for the built-in `search` tool and [index search tools](tools/index-search-tools.md), which may use index exploration capabilities internally. Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). From 1c36e55030acc542aeb82c6f42151fc5479fc999 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:31:07 +0100 Subject: [PATCH 12/13] use lead text to avoid stacking heading levels --- solutions/search/agent-builder/permissions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 15d374009e..675d79aa30 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -49,6 +49,12 @@ Learn more about [index privileges](elasticsearch://reference/elasticsearch/secu ## Grant access +You can grant users access to Agent Builder using these methods: + +- [Roles](#grant-access-with-roles) to bundle privileges for users. +- [API keys](#grant-access-with-api-keys) for programmatic access. +- [Spaces](#working-with-spaces) to scope access to specific environments. + ### Grant access with roles [Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. From 8505d7e2ce84955ff936b72759d46143deb76d69 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:33:40 +0100 Subject: [PATCH 13/13] use variables --- solutions/search/agent-builder/permissions.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 675d79aa30..449793a636 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -10,11 +10,11 @@ navigation_title: "Permissions & access control" # Permissions and access control in {{agent-builder}} -Use this page to learn how to configure security roles and API keys for Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. +Use this page to learn how to configure security roles and API keys for {{agent-builder}}. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. ## Required privileges -Agent Builder requires privileges at three levels: +{{agent-builder}} requires privileges at three levels: - [{{kib}} feature access](#kib-privileges) - [{{es}} cluster access](#es-cluster-privileges) @@ -22,7 +22,7 @@ Agent Builder requires privileges at three levels: ### {{kib}} privileges -Agent Builder access control is managed by the `agentBuilder` {{kib}} feature: +{{agent-builder}} access control is managed by the `agentBuilder` {{kib}} feature: - "Read" access to the `agentBuilder` feature: Required to use agents, send chat messages, view tools, and access conversations. - "All" access to the `agentBuilder` feature: Required to create, update, or delete custom agents and tools. @@ -32,7 +32,7 @@ Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-depl ### {{es}} cluster privileges -Agent Builder requires cluster-level privileges for AI-powered query generation: +{{agent-builder}} requires cluster-level privileges for AI-powered query generation: - `monitor_inference`: Required when the agent uses an AI connector that calls the {{es}} Inference API (such as the Elastic default LLM or other AI connectors configured to use the Inference API). The built-in tools `search` and `generate_esql`, as well as [index search tools](tools/index-search-tools.md), use this API to generate queries from natural language. This privilege is not required when the agent uses other {{kib}} GenAI connectors. @@ -49,7 +49,7 @@ Learn more about [index privileges](elasticsearch://reference/elasticsearch/secu ## Grant access -You can grant users access to Agent Builder using these methods: +You can grant users access to {{agent-builder}} using these methods: - [Roles](#grant-access-with-roles) to bundle privileges for users. - [API keys](#grant-access-with-api-keys) for programmatic access. @@ -57,13 +57,13 @@ You can grant users access to Agent Builder using these methods: ### Grant access with roles -[Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. +[Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to {{agent-builder}}, create a role that includes the required privileges. :::{note} -When configuring roles in the {{kib}} UI, Agent Builder privileges are currently located under the **Analytics** section, not the {{es}} section. +When configuring roles in the {{kib}} UI, {{agent-builder}} privileges are currently located under the **Analytics** section, not the {{es}} section. ::: -Example role for users who need full Agent Builder access: +Example role for users who need full {{agent-builder}} access: ```json POST /_security/role/agent-builder-full @@ -94,7 +94,7 @@ For read-only access, use `feature_agentBuilder.read` instead of `feature_agentB ### Grant access with API keys -When using the Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges. +When using the {{agent-builder}} APIs programmatically, authenticate with an API key that includes the required privileges. Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the {{kib}} API layer rather than through the UI. @@ -106,14 +106,14 @@ Learn more about [API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md). ### Working with Spaces -Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space. +{{agent-builder}} respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space. When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. Learn how to [Copy your MCP server URL](tools.md#copy-your-mcp-server-url). :::{important} -When accessing Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...` +When accessing {{agent-builder}} APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...` The default space uses the standard URL format without `/s/`. :::