Skip to content

Commit f9178e9

Browse files
leemthompoleemthompo
authored
[Agent Builder] Add page about permissions and access control (#3851)
Closes elastic/search-team#11769 and elastic/search-team#11751
1 parent 158d84f commit f9178e9

File tree

7 files changed

+163
-8
lines changed

7 files changed

+163
-8
lines changed

‎solutions/search/agent-builder/get-started.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ Find **Agents** in the navigation menu to begin using the feature, or search for
5252

5353
::::
5454

55+
:::{note}
56+
To learn about required privileges for {{agent-builder}}, refer to [Permissions and access control](permissions.md).
57+
:::
58+
5559
:::::
5660

5761
::::{step} Ingest some data

‎solutions/search/agent-builder/limitations-known-issues.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,4 +67,16 @@ This results in parsing errors like this:
6767
]
6868
```
6969

70-
70+
### MCP server URL copy button omits space name
71+
72+
:::{note}
73+
Fixed on serverless and 9.3.
74+
:::
75+
76+
On 9.2 deployments, the **Copy your MCP server URL** button does not include the space name when used from a custom {{kib}} Space.
77+
78+
**Workaround:** Manually add `/s/<space-name>` to the URL. For example: `https://<deployment>/s/<space-name>/api/agent_builder/mcp`
79+
80+
For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#working-with-spaces).
81+
82+

‎solutions/search/agent-builder/mcp-server.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,13 @@ The MCP server is available at:
1919
```
2020
{KIBANA_URL}/api/agent_builder/mcp
2121
```
22+
23+
When using a custom {{kib}} Space, include the space name in the URL:
24+
25+
```
26+
{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp
27+
```
28+
2229
:::{tip}
2330
You can copy your MCP server URL directly in the Tools GUI. Refer to [](tools.md#copy-your-mcp-server-url).
2431
:::

‎solutions/search/agent-builder/permissions.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
applies_to:
3+
stack: preview 9.2
4+
serverless:
5+
elasticsearch: preview
6+
observability: unavailable
7+
security: unavailable
8+
navigation_title: "Permissions & access control"
9+
---
10+
11+
# Permissions and access control in {{agent-builder}}
12+
13+
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.
14+
15+
## Required privileges
16+
17+
{{agent-builder}} requires privileges at three levels:
18+
19+
- [{{kib}} feature access](#kib-privileges)
20+
- [{{es}} cluster access](#es-cluster-privileges)
21+
- [{{es}} index access](#es-index-privileges)
22+
23+
### {{kib}} privileges
24+
25+
{{agent-builder}} access control is managed by the `agentBuilder` {{kib}} feature:
26+
27+
- "Read" access to the `agentBuilder` feature: Required to use agents, send chat messages, view tools, and access conversations.
28+
- "All" access to the `agentBuilder` feature: Required to create, update, or delete custom agents and tools.
29+
- "Read" access to the "Actions and Connectors" feature: Required to use AI connectors with agents.
30+
31+
Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md).
32+
33+
### {{es}} cluster privileges
34+
35+
{{agent-builder}} requires cluster-level privileges for AI-powered query generation:
36+
37+
- `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.
38+
39+
Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster).
40+
41+
### {{es}} index privileges
42+
43+
Tools execute queries against {{es}} indices as the current user. Required privileges depend on which indices the tools access:
44+
45+
- `read`: Required for tools that query data.
46+
- `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.
47+
48+
Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices).
49+
50+
## Grant access
51+
52+
You can grant users access to {{agent-builder}} using these methods:
53+
54+
- [Roles](#grant-access-with-roles) to bundle privileges for users.
55+
- [API keys](#grant-access-with-api-keys) for programmatic access.
56+
- [Spaces](#working-with-spaces) to scope access to specific environments.
57+
58+
### Grant access with roles
59+
60+
[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.
61+
62+
:::{note}
63+
When configuring roles in the {{kib}} UI, {{agent-builder}} privileges are currently located under the **Analytics** section, not the {{es}} section.
64+
:::
65+
66+
Example role for users who need full {{agent-builder}} access:
67+
68+
```json
69+
POST /_security/role/agent-builder-full
70+
{
71+
"cluster": ["monitor_inference"],
72+
"indices": [
73+
{
74+
"names": ["logs-*", "metrics-*"],
75+
"privileges": ["read", "view_index_metadata"]
76+
}
77+
],
78+
"applications": [
79+
{
80+
"application": "kibana-.kibana",
81+
"privileges": [
82+
"feature_agentBuilder.all",
83+
"feature_actions.read"
84+
],
85+
"resources": ["space:default"]
86+
}
87+
]
88+
}
89+
```
90+
91+
:::{tip}
92+
For read-only access, use `feature_agentBuilder.read` instead of `feature_agentBuilder.all`.
93+
:::
94+
95+
### Grant access with API keys
96+
97+
When using the {{agent-builder}} APIs programmatically, authenticate with an API key that includes the required privileges.
98+
99+
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.
100+
101+
Refer to these pages for API key configuration examples:
102+
- [MCP server](mcp-server.md#api-key-application-privileges)
103+
- [{{kib}} API](kibana-api.md)
104+
105+
Learn more about [API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md).
106+
107+
### Working with Spaces
108+
109+
{{agent-builder}} respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space.
110+
111+
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.
112+
113+
Learn how to [Copy your MCP server URL](tools.md#copy-your-mcp-server-url).
114+
115+
:::{important}
116+
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/...`
117+
118+
The default space uses the standard URL format without `/s/<space-name>`.
119+
:::
120+
121+
Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md).

‎solutions/search/agent-builder/tools.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@ Each tool is an atomic operation with a defined signature - accepting typed para
4040

4141
Key built-in tools include:
4242

43-
- **`.execute_esql`**: Executes an {{esql}} query and returns the results in a tabular format
44-
- **`.generate_esql`**: Generates an {{esql}} query from a natural language query
45-
- **`.get_document_by_id`**: Retrieves the full content of an {{es}} document based on its ID and index name
46-
- **`.get_index_mapping`**: Retrieves mappings for the specified index or indices
47-
- **`.index_explorer`**: Lists relevant indices and corresponding mappings based on a natural language query
48-
- **`.list_indices`**: Lists the indices in the {{es}} cluster the current user has access to
49-
- **`.search`**: A powerful tool for searching and analyzing data within a specific {{es}} index
43+
- `.execute_esql`: Executes an {{esql}} query and returns the results in a tabular format
44+
- `.generate_esql`: Generates an {{esql}} query from a natural language query
45+
- `.get_document_by_id`: Retrieves the full content of an {{es}} document based on its ID and index name
46+
- `.get_index_mapping`: Retrieves mappings for the specified index or indices
47+
- `.index_explorer`: Lists relevant indices and corresponding mappings based on a natural language query
48+
- `.list_indices`: Lists the indices in the {{es}} cluster the current user has access to
49+
- `.search`: Searches and analyzes data within a specific {{es}} index
5050

5151
Built-in tools serve as building blocks for more complex interactions and provide the foundation for agent capabilities.
5252

@@ -208,4 +208,8 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access.
208208
:width: 250px
209209
:::
210210

211+
:::{important}
212+
There is a [known issue](limitations-known-issues.md#mcp-server-url-copy-button-omits-space-name) with the copy button in 9.2.
213+
:::
214+
211215
For detailed MCP server configuration, refer to [MCP server](mcp-server.md).

‎solutions/search/elastic-agent-builder.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ These interfaces enable you to build integrations with other applications and ex
6666

6767
[**Learn more about programmatic access**](agent-builder/programmatic-access.md)
6868

69+
## Permissions and access control
70+
71+
Configure security roles and API keys to control who can use agents, which tools they can access, and what data they can query.
72+
73+
[**Learn more about permissions and access control**](agent-builder/permissions.md)
74+
6975
## Limitations and known issues
7076

7177
{{agent-builder}} is in technical preview.

‎solutions/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ toc:
7777
- file: search/agent-builder/kibana-api.md
7878
- file: search/agent-builder/a2a-server.md
7979
- file: search/agent-builder/mcp-server.md
80+
- file: search/agent-builder/permissions.md
8081
- file: search/agent-builder/limitations-known-issues.md
8182
- file: search/rag.md
8283
children:

0 commit comments

Comments
 (0)