[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#working-with-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,121 @@
+---
+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.
+
+## Required privileges
+
+{{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 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).
+
+### {{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).
+
+## 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.
+
+:::{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
+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`.
+:::
+
+### Grant access with API keys
+
+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).
+
+### Working with 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: