diff --git a/explore-analyze/ai-features/agent-builder/kibana-api.md b/explore-analyze/ai-features/agent-builder/kibana-api.md index bf54e9fa41..eb4e3bdb32 100644 --- a/explore-analyze/ai-features/agent-builder/kibana-api.md +++ b/explore-analyze/ai-features/agent-builder/kibana-api.md @@ -1114,6 +1114,62 @@ curl -X POST "${KIBANA_URL}/api/agent_builder/converse" \ :::: +**Example:** Create a conversation {applies_to}`stack: ga 9.6+` {applies_to}`serverless: ga` + +This example uses the [create a conversation API]({{kib-apis}}operation/operation-post-agent-builder-conversations). + +Every field is optional. If you omit `agent_id`, the conversation uses the default Elastic AI Agent. If you omit `title`, the conversation is named `New conversation`. If you omit `access_control`, the conversation is private to you. + +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/conversations +{ + "agent_id": "elastic-ai-agent" +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "${KIBANA_URL}/api/agent_builder/conversations" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{"agent_id": "elastic-ai-agent"}' +``` +:::{include} _snippets/spaces-api-note.md +::: +::: + +:::: + +The response includes the conversation's `access_control` and your `permissions` on it: + +```json +{ + "id": "8e5fd2c3-04d7-4b1a-b295-5d486afd8584", + "agent_id": "elastic-ai-agent", + "title": "New conversation", + "access_control": { + "access_mode": "private", + "entries": [] + }, + "permissions": { + "rename": true, + "delete": true, + "update_access_control": true + } +} +``` + +To share the conversation at creation time, include an `access_control` object with the same shape +as the [update conversation access control](#update-conversation-access-control) example. + **Example:** List conversations This example uses the [list conversations API]({{kib-apis}}operation/operation-get-agent-builder-conversations). @@ -1193,6 +1249,77 @@ curl -X DELETE "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" :::: +**Example:** Update conversation access control $$$update-conversation-access-control$$$ {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` + +This example uses the [update conversation access control API]({{kib-apis}}operation/operation-put-agent-builder-conversations-conversation-id-access-control). + +Share a conversation with specific users, or make it readable by anyone who can access its agent. Only the conversation owner can call this endpoint. To learn what members can do, refer to [Conversation access control](permissions.md#conversation-access-control). + +Each request replaces the entire access control. To stop sharing, send `private` with an empty `entries` list. + +The `id` of each entry is a {{kib}} user profile ID, not a username. + +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control +{ + "access_mode": "private", + "entries": [ + { + "type": "user", + "id": "", + "role": "member" + } + ] +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X PUT "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}/access_control" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "access_mode": "private", + "entries": [ + {"type": "user", "id": "", "role": "member"} + ] + }' +``` +:::{include} _snippets/spaces-api-note.md +::: +::: + +:::: + +To make a conversation readable by anyone who can access its agent, set `access_mode` to `public` and send an empty `entries` list: + +```console +PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control +{ + "access_mode": "public", + "entries": [] +} +``` + +Keep these constraints in mind: + +- `entries` is required. Send an empty list when `access_mode` is `public`, or to unshare. +- `entries` must be empty when `access_mode` is `public`. +- A conversation can have at most 100 members. +- Each user can appear only once. Repeated IDs are rejected. +- `member` is the only supported role, and `user` is the only supported entry type. +- An entry that names the owner is accepted but not stored. +- Entry IDs are not validated. An ID that does not match a real user profile is stored and simply never grants access to anyone. +- If you do not own the conversation, the request fails with a `404` error rather than a permissions error. + ### Get A2A agent card configuration Use this API to retrieve the A2A agent card configuration for a specific agent. diff --git a/explore-analyze/ai-features/agent-builder/permissions.md b/explore-analyze/ai-features/agent-builder/permissions.md index 9bfe0347dc..09872039a7 100644 --- a/explore-analyze/ai-features/agent-builder/permissions.md +++ b/explore-analyze/ai-features/agent-builder/permissions.md @@ -111,6 +111,70 @@ Access is granted at the index level. Any user who can read these data streams c +## Conversation access control [conversation-access-control] + +```{applies_to} +stack: preview 9.6+ +serverless: preview +``` + +The {{kib}} privileges described above control who can use {{agent-builder}} at all. Individual conversations have a second layer of access control on top of that, so the owner of a conversation can decide who else can read it. + +Conversations are private by default. Only the user who created a conversation, its owner, can see it. + +### Access modes + +An owner can put a conversation into one of two access modes: + +- `private`: only the owner and the users listed as members can read and continue the conversation. This is the default. +- `public`: any user who can access the conversation's agent can read and continue it. Public conversations also appear in those users' conversation lists. + +Members apply to private conversations only. A public conversation cannot have members. + +A conversation belongs to the {{kib}} space it was created in. Sharing does not make it visible from another space. + +### The member role + +Users you share a conversation with are added as members. `member` is the only available role. It grants two things: + +- Read the conversation, including its full history. +- Continue the conversation by sending new messages. + +Members cannot rename the conversation, delete it, or change who it is shared with. + +You can share with individual users only. Granting access to an {{es}} role is not supported. + +Members are identified by their {{kib}} user profile ID, not by username. A user who has never logged in to {{kib}} has no profile and cannot be added. + +### Who can do what + +| Action | Owner | Member | Other users | +| --- | --- | --- | --- | +| Read and continue | Yes | Yes | Only if the conversation is public | +| Rename | Yes | No | No | +| Delete | Yes | No | No | +| Change sharing | Yes | No | No | + +A user with full cluster privileges, such as a superuser, can also rename or delete a `public` conversation they do not own. This does not extend to `private` conversations, even ones shared with them, and it never includes changing who a conversation is shared with. + +### Sharing does not bypass privileges + +Sharing a conversation grants access to that conversation only. It does not grant any privilege the user does not already have. + +A member still needs: + +- The `agentBuilder` {{kib}} `Read` privilege. +- Access to the agent the conversation uses. +- Access to the space the conversation belongs to. + +Access to the agent is checked every time a conversation is read, and this applies to the owner as well. If anyone loses access to a conversation's agent, or the agent is deleted, the conversation stops being readable for them and disappears from their conversation list. + +Managing sharing needs only the `Read` privilege plus ownership. There is no separate sharing privilege, and no write privilege is involved. + +When a user cannot access a conversation, {{agent-builder}} reports it as not found rather than as a permissions error. This is deliberate, so that users cannot detect the existence of conversations they cannot read. + +To share a conversation, use the [{{kib}} API](kibana-api.md#update-conversation-access-control). + ## Grant access You can grant users access to {{agent-builder}} using these methods: @@ -124,7 +188,7 @@ You can grant users access to {{agent-builder}} using these methods: [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. +When configuring roles in the {{kib}} UI, {{agent-builder}} privileges appear under **Analytics**. In {{serverless-short}} {{es}} projects, they appear under **{{es}}**. ::: Example role for users who need full {{agent-builder}} access: