[Agent Builder] Update access control docs: new agents default to Private

explore-analyze/ai-features/agent-builder/chat.md

@@ -398,7 +398,9 @@ stack: ga 9.4+
 The **Manage components** link at the bottom of the left sidebar exits the single-agent view. It provides an overview of all agents, skills, plugins, connectors, and tools available across the deployment.
 
 **Agents**
-:   View all agents in the deployment. The list displays each agent's name, visibility badge (**Public**, **Shared**, or **Read-only**), and any custom labels. From this page, you can create new agents, edit existing ones, or start a chat.
+:   View all agents available in the current {{kib}} space. The list displays each agent's name and access control level (**Public**, **Shared**, or **Private**), a **Read-only** badge for built-in agents, and any labels. From this page, you can create new agents, edit existing ones, or start a chat.
+
+    {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` Agents that individual users have been granted access to also show a badge with the number of those users.
 
 **Skills**
 :   View and manage all skills available in the deployment. Create new skills or edit existing ones.

explore-analyze/ai-features/agent-builder/custom-agents.md

@@ -105,14 +105,22 @@ For details, refer to [Pre-execution workflows](agents-and-workflows.md#pre-exec
 
 :::::
 
-:::::{step} Set visibility
+:::::{step} Set access control
 ```{applies_to}
 stack: ga 9.4+
+serverless: ga
 ```
 
-Configure the **Visibility** for your agent in the **Organization** section. Visibility controls who can view and edit the agent. The default setting is **Public**.
+Configure **Access control** for your agent in the **Organization** section. Access control determines who can view and edit the agent.
+
+{applies_to}`stack: ga =9.4` This setting is labeled **Visibility**.
+
+New agents default to:
 
-For more information, refer to [Visibility settings](#visibility-settings). You can also configure [per-agent access controls](#per-agent-access-controls) for more granular control.
+* {applies_to}`stack: ga 9.6+` {applies_to}`serverless: ga` **Private**
+* {applies_to}`stack: ga 9.4-9.5` **Public**
+
+For what each level means, refer to [Access control settings](#access-control-settings). You can also configure [per-agent access controls](#per-agent-access-controls) for more granular control.
 
 :::::
 
@@ -191,50 +199,84 @@ From the **Agents** page, you can perform various actions on custom agents:
 These management options apply only to custom agents and the Elastic AI Agent {applies_to}`stack: ga 9.4+`. Other built-in agents can only be chatted with or cloned, not edited or deleted.
 :::
 
-## Visibility settings
+## Access control settings [access-control-settings]
 
 ```{applies_to}
 stack: ga 9.4+
+serverless: ga
 ```
 
-Control who can view and edit your agent by configuring its visibility. To change visibility, edit the agent and scroll to the **Organization** section.
+Control who can view and edit your agent by configuring its access control level. To change the level, edit the agent and go to the **Organization** section.
+
+{applies_to}`stack: ga =9.4` This setting is labeled **Visibility**.
 
-Every agent has one of three visibility levels:
+Throughout this section, the owner is the user who created the agent, and an administrator is a user whose role grants wildcard (`*`) privileges, such as the built-in `superuser` role. {{agent-builder}} privileges alone, including the privilege to manage agents in a space, don't make a user an administrator.
+
+Every agent has one of three access control levels:
 
 **Public**
 :   Anyone can view and edit.
 
 **Shared**
 :   Anyone can view. Only the owner or an administrator can edit.
 
+    {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` People you grant access to can also edit.
+
 **Private**
 :   Only the owner or an administrator can view and edit.
 
-:::{image} images/agent-visibility-levels.png
-:alt: Agent visibility dropdown showing Public, Shared, and Private.
+    {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` People you grant access to can also view it, and edit it if you give them **Editor** or **Manager**.
+
+:::{image} images/agent-access-control-levels.png
+:screenshot:
+:alt: The open Access control menu with Private selected, beside a panel describing each level.
 :width: 700px
 :::
 
+Whatever the level, only the owner or an administrator can change it. For everyone else, the setting is read-only.
+
+{applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` A user you give **Manager** access can also change the level.
+
+Who can delete an agent:
+
+* {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` The owner, an administrator, or a user you give **Manager** access. Being able to edit a **Public** agent doesn't include deleting it.
+* {applies_to}`stack: ga =9.4` Anyone who can edit the agent, which on a **Public** agent means anyone.
+
+To grant access to individual users, refer to [Per-agent access controls](#per-agent-access-controls).
+
+{applies_to}`stack: ga 9.6+` {applies_to}`serverless: ga` The new default applies to new agents only. Agents that already exist keep the level they have, and agents created before access control existed are **Public**.
+
+Most built-in agents don't have an access control level at all. They're always available to everyone who can use {{agent-builder}}. The **Elastic AI Agent** is the exception: it does have a level, which is always **Public** and can't be changed, even by an administrator.
+
 ### Per-agent access controls
 
 ```{applies_to}
 stack: ga 9.5+
 serverless: ga
 ```
 
-In addition to the three visibility levels, you can configure access controls for individual users on a per-agent basis. This allows you to grant specific users view or edit access to an agent, giving you more granular control over who can interact with and modify your agents.
+In addition to the three access control levels, you can grant individual users access to a specific agent. Use this when the agent's access control level is too broad or too narrow for a particular person.
 
 To configure per-agent access controls:
 
-1. Edit the agent and scroll to the **Organization** section.
-2. Select a base visibility level.
-3. Add individual users and assign each one a **View** or **Edit** access level.
+1. Edit the agent and go to the **Organization** section. You can also select **Manage access** for the agent on the **Agents** page.
+2. Select an access control level.
+3. Add individual users and assign each one an access level.
 
-Users you add to the access list can interact with the agent according to the access level you assign, regardless of the base visibility setting. For example, you can set an agent to **Private** and then grant specific users view or edit access.
+Each user you add gets one of three access levels. These are separate from the agent's access control level, which applies to everyone in the space:
 
-::::{note}
-Per-agent access controls only apply to **Private** and **Shared** agents. Any user in your organization can view and use a **Public** agent.
-::::
+**User**
+:   Can find, view, and run the agent.
+
+**Editor**
+:   Everything a **User** can do, plus editing the agent's configuration.
+
+**Manager**
+:   Everything an **Editor** can do, plus deleting the agent and managing who has access to it.
+
+Adding a user can only increase their access, never reduce it: they get whichever grants more, the level you assign or the agent's access control level. For example, you can set an agent to **Private** and then give one colleague **Editor** access.
+
+You can grant per-agent access at any access control level, including **Public**. What changes is which levels you can assign: on **Public** and **Shared** agents, **User** isn't offered, because anyone in the space can already find and run the agent.
 
 ## Best practices for custom agents
 

explore-analyze/ai-features/agent-builder/glossary.md

@@ -32,6 +32,13 @@ $$$a2a-server$$$
 A2A server
 :   The {{agent-builder}} endpoint that exposes agents to external A2A clients. Use it to integrate {{agent-builder}} agents with third-party agent frameworks. See [](a2a-server.md).
 
+$$$access-control$$$
+$$$visibility$$$
+Access control
+:   A custom agent's sharing setting that controls who can view and edit it. The levels, from least to most restrictive, are **Public** (anyone can view and edit), **Shared** (anyone can view; only the owner or an administrator can edit), and **Private** (only the owner or an administrator). See [](custom-agents.md#access-control-settings).
+
+    {applies_to}`stack: ga =9.4` This setting is labeled **Visibility**.
+
 $$$agent$$$
 Agent
 :   A capability that iteratively uses a large language model (LLM), system context, and a set of tools and skills to complete a task. Each agent translates a user's natural language request into a sequence of tool calls and reasoning steps to answer questions, take actions, or support workflows. {{agent-builder}} ships with built-in agents and lets you create custom agents. See [](agent-builder-agents.md#how-agents-work).
@@ -118,7 +125,7 @@ Conversation history
 
 $$$custom-agent$$$
 Custom agent
-:   An agent you create with your own system prompt, tools, skills, and visibility settings. Custom agents are space-aware and exist only in the {{kib}} space where they were created. See [](custom-agents.md#create-a-custom-agent).
+:   An agent you create with your own system prompt, tools, skills, and access control settings. Custom agents are space-aware and exist only in the {{kib}} space where they were created. See [](custom-agents.md#create-a-custom-agent).
 
 $$$custom-instructions$$$
 Custom instructions
@@ -334,12 +341,6 @@ $$$tool$$$
 Tool
 :   A modular function an agent can call to search, retrieve, or manipulate {{es}} data. Tools are the primary mechanism for grounding agent capabilities in your data. {{agent-builder}} provides built-in tools; you can also create custom tools of four types: {{esql}}, index search, MCP, and workflow. See [](tools.md#how-agents-use-tools).
 
-## V
-
-$$$visibility$$$
-Visibility
-:   A custom agent's sharing setting that controls who can see and edit it. Options are **Public** (anyone in the space), **Shared** (anyone can view; only owners and admins can edit), and **Private** (only owners and admins). See [](custom-agents.md#visibility-settings).
-
 ## W
 
 $$$workflow-tool$$$

explore-analyze/ai-features/agent-builder/kibana-api.md

@@ -685,6 +685,14 @@ curl -X GET "${KIBANA_URL}/api/agent_builder/agents" \
 
 This example uses the [create an agent API]({{kib-apis}}operation/operation-post-agent-builder-agents).
 
+`access_control` is an object that takes a level in its `access_mode` property, as in `"access_control": { "access_mode": "shared" }`.
+
+{applies_to}`stack: ga =9.4` This field is named `visibility` and takes the level directly, as in `"visibility": "shared"`.
+
+{applies_to}`stack: ga 9.6+` {applies_to}`serverless: ga` If you omit `access_control`, the agent is private: only you and administrators can view and edit it.
+
+{applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` You can't grant individual users access when you create an agent. On create, `access_control` accepts only `access_mode`, and including `entries` returns a validation error. To grant access, call `PUT /api/agent_builder/agents/{id}/access_control` after the agent exists.
+
 ::::{tab-set}
 :group: api-examples
 

redirects.yml

@@ -1039,9 +1039,14 @@ redirects:
           'create-custom-eis': 'add-endpoint'
 
   # https://github.com/elastic/docs-content/pull/6582
+  # https://github.com/elastic/docs-content-internal/issues/1609
   'explore-analyze/ai-features/agent-builder/custom-agents.md':
     to: 'explore-analyze/ai-features/agent-builder/custom-agents.md'
     many:
+      - to: 'explore-analyze/ai-features/agent-builder/custom-agents.md'
+        anchors:
+          'visibility-settings': 'access-control-settings'
+          'set-visibility': 'set-access-control'
       - to: 'explore-analyze/ai-features/agent-builder/agent-builder-agents.md'
         anchors:
           'enable-elastic-capabilities': 'elastic-capabilities'