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/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index 52f41bec7e..f5cfadd94f 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/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/` 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#working-with-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 new file mode 100644 index 0000000000..449793a636 --- /dev/null +++ b/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:///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..b2fe7657f5 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. @@ -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). 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 f26eb43f41..0263947dd1 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: