[Agent Builder] Add page about permissions and access control

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

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/<space-name>` to the URL after your deployment URL. For example: `https://<deployment>/s/<space-name>/api/agent_builder/mcp`
+
+For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#spaces).
+
+

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).
 :::

solutions/search/agent-builder/permissions.md

@@ -0,0 +1,104 @@
+---
+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](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md).
+
+### {{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.
+
+Refer to 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 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://<deployment>/s/<space-name>/api/agent_builder/...`
+
+The default space uses the standard URL format without `/s/<space-name>`.
+:::
+
+Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md).

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/<space-name>` to the URL path. For example: `https://<deployment>/s/<space-name>/api/agent_builder/mcp`
+:::
+
 For detailed MCP server configuration, refer to [MCP server](mcp-server.md).

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.

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: