added step-by-step agent management guides with screenshots, split programmatic access into separate API/MCP/A2A pages

**Major changes:**
- Renamed "Conversations" to "Agent Chat" throughout
- Expanded agent management section with detailed UI instructions and screenshots
- Added comprehensive step-by-step agent creation guide with visual elements
- Restructured getting started guide to be more user-friendly
- Updated programmatic access to be overview-only, with separate dedicated pages for APIs, MCP, and A2A
- Renamed system tools to "built-in tools" consistently
- Updated API endpoints from `/api/chat/` to `/api/agent_builder/`
- Enhanced tool configuration examples with better parameter descriptions
- Added troubleshooting for SQL vs ES|QL syntax confusion
- Removed self-deployment references (serverless/cloud only)
- Updated model details (Claude Sonnet 3.7 via Elastic Inference Service)
- Reorganized table of contents with new file structure for programmatic access

**Key improvements:**
- Better user onboarding flow
- More detailed UI guidance with screenshots
- Clearer separation between built-in and custom tools
- Enhanced API documentation structure
- More comprehensive limitations section

Author: leemthompo

solutions/search/agent-builder/a2a-server.md

@@ -0,0 +1,31 @@
+---
+navigation_title: "A2A server"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+# Agent-to-Agent (A2A) server
+
+The [**Agent-to-Agent (A2A) server**](https://github.com/a2aproject/A2A) enables external A2A clients to communicate with {{agent-builder}} agents.
+
+## Agent cards endpoint
+
+Returns metadata for a specific agent. The `agentId` is a path parameter that corresponds to your agent IDs:
+
+```
+GET /api/agent_builder/a2a/{agentId}.json
+```
+
+## A2A protocol endpoint
+
+Interact with agents following the A2A protocol specification:
+
+```
+POST /api/agent_builder/a2a/{agentId}
+```
+
+:::{important}
+Both A2A endpoints require API key authentication. For more information about the A2A protocol, see the [A2A protocol specification](https://a2aprotocol.ai/docs/guide/a2a-protocol-specification-python#protocol-flow-diagram).
+:::

solutions/search/agent-builder/agent-builder-agents.md

@@ -2,34 +2,106 @@
 navigation_title: "Agents"
 applies_to:
   stack: preview 9.2
-  deployment: 
-    self: unavailable
   serverless:
     elasticsearch: preview
 ---
 
-# Agents
+# {{agent-builder}}: Agents
 
-Agents are AI assistants that engage in natural language conversations with users and interact with your {{es}} data through tools. Each agent manages the conversation flow, interprets user requests, and provides responses based on its configured tools, instructions, and behavior settings.
+Agents engage in natural language conversations with users and interact with your {{es}} data through tools.
+Fundamentally, an agent is defined by its custom instructions and the set of tools it's assigned.
+
+Each agent manages the conversation flow, interprets user requests, and provides responses based on its configured tools, instructions, and behavior settings.
 
 ## How agents work
 
 When you ask a question to an agent, it analyzes your request, selects the most appropriate tool, and determines the right arguments to use. After receiving results, the agent evaluates the information and decides whether to use additional tools or formulate a response. This iterative process of tool selection, execution, and analysis continues until the agent can provide a complete answer.
 
-{{agent-builder}} includes a default agent with access to all system tools. You can create specialized agents with custom instructions and selected tools to address specific use cases or workflows.
+{{agent-builder}} includes a default agent (named `Elastic AI Agent`) with access to all built-in tools. You can create specialized agents with custom instructions and selected tools to address specific use cases or workflows.
+
+## Manage your agents
+
+The **Agents** page provides a centralized view of all your agents. From this page you can:
+
+- View all your agents with their names and labels
+- Search for specific agents using the search bar
+- Filter agents by labels using the **Labels** dropdown
+- Create new agents using the **+ New agent** button
+- Start chatting with an agent or perform other actions
+    - **Elastic AI Agent**: you can **chat** or **clone** the default agent using the chat or clone buttons.
+      :::{image} images/chat-and-clone-buttons.png
+      :alt: Chat with agent and clone agent buttons
+      :width: 120px
+      :::
+    - **Custom agents**: You can **chat**, **edit**, **clone**, or **delete** an agent from the management overview.
+      :::{image} images/chat-edit-clone-delete.png
+      :alt: Agent context menu showing Chat, Edit, Clone, and Delete options
+      :width: 130px
+      :::
+
+## How to create a new agent
+
+Follow these steps to create a new agent:
+
+:::::{stepper}
+::::{step} Navigate to the Agents page
+
+Navigate to the **Agents** page to access the agent management interface.
+
+::::
+
+::::{step} Create a new agent
+
+Click the **New agent** button to start creating a new agent.
+
+:::{image} images/new-agent-button.png
+:alt: Click the New agent button to create a new agent
+:width: 150px
+:::
+
+
+::::
+
+::::{step} Configure essential settings
+
+Configure the essential agent settings in the **settings** tab:
+
+1. Enter an **Agent ID**, a unique identifier for reference in code.
+1. Add **Custom instructions**.<br><br>Custom instructions are appended to the system prompt that enables core agent features like visualization and citations. The custom instructions define the agent's personality and determine how it will interact with users and perform tasks.
+    :::{note}
+    Your custom instructions are added to the system prompt to define the agent's behavior. The system prompt enables core features like visualization and citations.
+    :::
+
+1. Set the **Display name** that users will see.
+1. Add a **Display description** to explain the agent's purpose
+
+::::
+
+::::{step} Assign tools
+
+Switch to the **Tools** tab to assign [tools](tools.md) to your agent.
+
+Select the combination of built-in and custom tools available to the agent, based on your use case.
+
+::::
+
+::::{step} Customize appearance (optional)
+
+Optionally customize the agent's appearance and organization:
+
+- Add **Labels** to organize your agents
+- Choose an **Avatar color** and **Avatar symbol** to help visually distinguish the agent
+
+::::
+
+::::{step} Save your changes
 
-## Create a new agent
+Click **Save** to create your agent, or **Save and chat** to create the agent and immediately start a conversation with it.
 
-To create a new agent:
+:::{image} images/save-and-chat-buttons.png
+:alt: Save and Save and chat buttons
+:width: 270px
+:::
 
-1. Navigate to the Agents subpage under **Chat**
-2. Click the **New agent** button in the top right corner
-3. Configure the agent settings:
-   - Enter an **Agent ID** - unique identifier for reference in code
-   - Add **Custom instructions** (optional) to guide the agent's behavior
-   - Add **Labels** (optional) to organize your agents
-   - Set the **Display name** that users will see
-   - Add a **Display description** to explain the agent's purpose
-   - Choose an **Avatar color** and **Avatar symbol** (both optional)
-4. Switch to the **Tools** tab to assign [tools](tools.md) to the agent
-5. Click the **Save** button to create your agent
+::::
+:::::

solutions/search/agent-builder/chat.md

@@ -0,0 +1,13 @@
+---
+navigation_title: "Agent Chat UI"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+# {{agent-builder}}: Agent Chat UI
+
+
+The **Agent Chat** UI is the synchronous chat interface for interacting with agents through natural language. The chat UI enables real-time communication where you can ask questions, request data analysis, and receive immediate responses from your configured agents.
+

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

@@ -1,84 +1,71 @@
 ---
+navigation_title: "Get started"
 applies_to:
   stack: preview 9.2
-  deployment: 
-    self: unavailable
   serverless:
     elasticsearch: preview
 ---
 
-# Get started 
+# Get started with {{agent-builder}}
 
 Learn how get started by enabling the {{agent-builder}} features and begin chatting with your data.
 
-{{agent-builder}} is disabled by default. Follow these steps to enable the features and start using Chat.
-
 :::::{stepper}
-::::{step} Choose your deployment type
+::::{step} Set up an Elastic deployment
 
-- **Option 1:** [{{es}} {{serverless-short}}](/solutions/search/serverless-elasticsearch-get-started.md)
-- **Option 2:** [{{ech}}](/deploy-manage/deploy/elastic-cloud/cloud-hosted.md)
+If you don't already have an Elastic deployment, refer to [Choose your deployment type](/solutions/search/get-started.md#choose-your-deployment-type).
 
-:::{tip}
-Not sure which deployment type to choose? Learn more in [Compare {{ech}} and {{serverless-short}}](/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md).
+:::{note}
+For {{ech}} deployments, make sure you are using the solution navigation instead of classic navigation.
+You can set up a new [space](/deploy-manage/manage-spaces.md) to use the solution nav.
 :::
 
 ::::
 
-::::{step} Enable features
+::::{step} Enable {{agent-builder}}
 
-Choose your preferred method to enable the {{agent-builder}} features.
+{{agent-builder}} is disabled by default in the initial release, so you'll need to enable the feature to get started.
 
-::::{tab-set}
+You can enable the features using the UI:
 
-:::{tab-item} API
-:sync: api
+1. Navigate to **Stack Management > Settings**
+2. Find **AI > Agent Builder** in the left-hand navigation
+3. Toggle **{{agent-builder}}** to on
+4. Click **Save changes**
 
-Run the following command in the Dev Tools [Console](/explore-analyze/query-filter/tools/console.md):
+Refresh the browser page and find **Agents** in the navigation menu to start using the feature.
+You can also search for **Agent Builder** in the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md).
 
-```console
-POST kbn://internal/kibana/settings
-{
-   "changes": {
-      "agentBuilder:enabled": true
-   }
-}
-```
 
-:::
+::::
 
-:::{tab-item} {{ech}} UI
-:sync: stack
-```{applies_to}
-serverless: unavailable
-```
+::::{step} Ingest some data
 
-On {{ech}} deployments, you can also enable the features in **Advanced Settings**:
+Before you get started with agents, you need some data in your {{es}} cluster. Otherwise, you'll just be chatting to the underlying LLM without any retrieval-augmented context.
 
-1. Access your Kibana settings through **Stack Management > Advanced Settings**.
-2. Enable the `agentBuilder` settings:
-```json
-uiSettings.overrides:
-  agentBuilder:enabled: true
-```
+To learn about adding data for search use cases, go to [](/solutions/search/ingest-for-search.md).
+For a broader overview of ingestion options, go to [](/manage-data/ingest.md).
 
+:::{tip}
+If you're not ready to add your own data, you can use the Elastic [sample data](/manage-data/ingest/sample-data.md) or create small data sets when you follow the instructions in the [quickstarts](/solutions/search/get-started/quickstarts.md).
+% TODO: we can link to a an agent builder tutorial if we add one in the docs
 :::
 
 ::::
 
-::::
-
 ::::{step} Start chatting
 
-Refresh the browser page and find **Chat/Conversations** in the navigation menu to start using the feature.
-You can also search for **Chat** in the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md).
+The **Agent Chat** UI provides a conversational interface where you can interact with agents and explore your data using natural language. {{agent-builder}} includes a default agent named `Elastic AI Agent` with access to all built-in tools, so you can start chatting immediately.
 
-The Chat UI provides a conversational interface where you can interact with agents and explore your data using natural language. Learn more in [Conversations](conversations.md).
+Learn more in [Agent Chat](chat.md).
 
-:::{note}
-For {{ech}} deployments, make sure you are using the solution navigation instead of classic navigation.
-You can set up a new [space](/deploy-manage/manage-spaces.md) to use the solution nav.
-:::
 
 ::::
+
+::::{step} Start building agents and tools
+
+Once you've tested the built-in **Elastic AI Agent** with the [built-in tools](tools.md#built-in-tools), you'll want to start [building your own agents](agent-builder-agents.md#create-a-new-agent) with custom instructions and creating your own [tools](tools.md) to assign them.
+
+::::
+
 :::::

solutions/search/agent-builder/kibana-api.md

@@ -0,0 +1,96 @@
+---
+navigation_title: "Kibana APIs"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+# Work with {{agent-builder}} using the APIs
+
+These APIs allow you to programmatically work with the {{agent-builder}} abstractions.
+
+## API reference
+
+For the full API documentation, refer to the [Kibana API reference](https://www.elastic.co/docs/api/doc/kibana/).
+
+For information on generating API keys, see [API keys](https://www.elastic.co/docs/solutions/search/search-connection-details).
+
+## Available APIs
+% TODO: we may remove this list once the API reference is live, but probably helpful in the short term
+
+### Tools
+
+List all tools
+:   `GET kbn://api/agent_builder/tools`
+
+Create a tool
+:   `POST kbn://api/agent_builder/tools`
+
+Get a tool by ID
+:   `GET kbn://api/agent_builder/tools/{id}`
+
+Delete a tool by ID
+:   `DELETE kbn://api/agent_builder/tools/{id}`
+
+Update a tool by ID
+:   `PUT kbn://api/agent_builder/tools/{toolId}`
+
+Execute a tool
+:   `POST kbn://api/agent_builder/tools/_execute`
+
+### Agents
+
+List all agents
+:   `GET kbn://api/agent_builder/agents`
+
+Create an agent
+:   `POST kbn://api/agent_builder/agents`
+
+Get an agent by ID
+:   `GET kbn://api/agent_builder/agents/{id}`
+
+Update an agent by ID
+:   `PUT kbn://api/agent_builder/agents/{id}`
+
+Delete an agent by ID
+:   `DELETE kbn://api/agent_builder/agents/{id}`
+
+### Chat and Conversations
+
+Chat with an agent
+:   `POST kbn://api/agent_builder/converse`
+
+Chat with an agent and stream events
+:   `POST kbn://api/agent_builder/converse/async`
+
+List conversations
+:   `GET kbn://api/agent_builder/conversations`
+
+Get conversation by ID
+:   `GET kbn://api/agent_builder/conversations/{conversation_id}`
+
+Delete conversation by ID
+:   `DELETE kbn://api/agent_builder/conversations/{conversation_id}`
+
+### MCP Server
+
+Get MCP server configuration
+:   `GET kbn://api/agent_builder/mcp`
+
+Create or configure MCP server
+:   `POST kbn://api/agent_builder/mcp`
+
+Delete MCP server configuration
+:   `DELETE kbn://api/agent_builder/mcp`
+
+### A2A Protocol
+
+Refer to [](a2a-server.md) for more information.
+
+Get A2A agent card configuration
+:   `GET kbn://api/agent_builder/a2a/{agentId}.json`
+
+Execute A2A agent task
+:   `POST kbn://api/agent_builder/a2a/{agentId}`
+