[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,16 @@ This results in parsing errors like this:
 ]
 ```
 
-
+### MCP server URL copy button omits space name
+
+:::{note}
+Fixed on serverless and 9.3.
+:::
+
+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/<space-name>` to the 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,108 @@
+---
+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 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.
+- "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).
+
+### {{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
+- `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).
+
+### 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",
+        "feature_actions.read"
+      ],
+      "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

@@ -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.
 
@@ -208,4 +208,8 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access.
 :width: 250px
 :::
 
+:::{important}
+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).

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

@@ -1,3 +1,3 @@
 project: "Solutions and use cases"
 toc:
   - file: index.md
@@ -77,6 +77,7 @@
               - 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: