[Agent Builder] Add page about permissions and access control #3851
Conversation
leemthompo
requested review from
a team and
ppf2
and removed request for
a team
🔍 Preview links for changed docs |
- Document space-aware URL format for MCP server and APIs - Add known issue: copy button doesn't include space name in URL
| ### 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). |
There was a problem hiding this comment.
This was fixed in elastic/kibana#240955, afaik? Is the current version of the documentation meant to be for 9.2.0?
There was a problem hiding this comment.
yep we'll remove this once 9.3 lands
I'll add version tag to make it clear
| :::{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` | ||
| ::: | ||
|
|
| ### {{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). |
There was a problem hiding this comment.
Do we usually describe the API privileges granted by a Kibana feature? It feels more like an implementation detail (or I always assumed it was).
I would have presented it that way, personally:
Agent Builder access control is managed via 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`: Required to create, update, or delete custom agents and tools.
(but I'm not a doc writer 😄)
There was a problem hiding this comment.
Wasn't sure really how much detail we needed here, @ppf2 can chime in here and can tweak accordingly
| 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. |
There was a problem hiding this comment.
So technically this is only true when using an IA connector (or the Elastic default LLM which is one), not when using other Kibana GenAI connectors. But I'm not sure we want to mention that.
Another point, technically to use any connector, the user gonna need at least read level permission on the Actions and Connectors Kibana feature. This part may be worth mentioning.
| 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` |
There was a problem hiding this comment.
not sure we need an exhaustive list, but for information - view_index_metadata is also required for search (and any index_search type user tools) because they may use index_explorer under the hood.
Closes https://github.com/elastic/search-team/issues/11769
WIP, ready for first round of feedback from SMEs
🔗URL preview