[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.
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.
We should mention it. Thx!
| 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.
|
@pgayvallet this has seen a round of iteration, LMKWYT at this point |
| # 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. | ||
|
|
There was a problem hiding this comment.
WDYT about adding an H2 here as parent to the 3 privileges sections? (they're all H3 currently while there's no H2), and another before the Granting access ones, to split he page into a "reference" part and a "how-to" part?
szabosteve
left a comment
szabosteve
left a comment
There was a problem hiding this comment.
Left some smaller comments.
Co-authored-by: István Zoltán Szabó <[email protected]>
Closes https://github.com/elastic/search-team/issues/11769 and https://github.com/elastic/search-team/issues/11751
🔗URL preview