[WIP] Agent Builder initial docs (hidden from TOC and search engines) (elastic#2857)

> [!WARNING]
> We are merging this in `hidden` mode. The pages will be live but not
indexed by search engines or visible in the docs TOC/nav.

Author: leemthompo

.gitignore

@@ -2,6 +2,10 @@
 .artifacts
 .DS_store
 
+# Jetbrains files
+.idea
+*.iml
+
 # Add LLM/AI related files
 AGENTS.md
 .github/copilot-instructions.md

docset.yml

@@ -294,4 +294,6 @@ subs:
   ece-apis: https://www.elastic.co/docs/api/doc/cloud-enterprise/
   intake-apis: https://www.elastic.co/docs/api/doc/observability-serverless/
   models-app: "Trained Models"
-  kube-stack-version: 0.6.3
+  agent-builder: "Elastic Agent Builder"
+  kube-stack-version: 0.6.3
+

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

@@ -0,0 +1,37 @@
+---
+navigation_title: "A2A server"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+WIP
+
+These pages are hidden from the docs TOC and have `noindexed` meta headers.
+:::
+
+# 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

@@ -0,0 +1,113 @@
+---
+navigation_title: "Agents"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+WIP
+
+These pages are hidden from the docs TOC and have `noindexed` meta headers.
+:::
+
+# {{agent-builder}}: Agents
+
+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 (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 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
+
+Click **Save** to create your agent, or **Save and chat** to create the agent and immediately start a conversation with it.
+
+:::{image} images/save-and-chat-buttons.png
+:alt: Save and Save and chat buttons
+:width: 270px
+:::
+
+::::
+:::::

solutions/search/agent-builder/chat.md

@@ -0,0 +1,19 @@
+---
+navigation_title: "Agent Chat UI"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+WIP
+
+These pages are hidden from the docs TOC and have `noindexed` meta headers.
+:::
+
+# {{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

@@ -0,0 +1,82 @@
+---
+navigation_title: "Get started"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+---
+
+:::{warning}
+WIP
+
+These pages are hidden from the docs TOC and have `noindexed` meta headers.
+:::
+
+# Get started with {{agent-builder}}
+
+:::{tip}
+See the [overview page](../elastic-agent-builder.md) for full list of docs pages.
+:::
+% TODO: Delete this tip when unhide pages
+
+Learn how get started by enabling the {{agent-builder}} features and begin chatting with your data.
+
+:::::{stepper}
+::::{step} Set up an Elastic deployment
+
+If you don't already have an Elastic deployment, refer to [Choose your deployment type](/solutions/search/get-started.md#choose-your-deployment-type).
+
+:::{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 {{agent-builder}}
+
+{{agent-builder}} is disabled by default in the initial release, so you'll need to enable the feature to get started.
+
+You can enable the features using the UI:
+
+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**
+
+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).
+
+
+::::
+
+::::{step} Ingest some data
+
+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.
+
+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
+
+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.
+
+Learn more in [Agent Chat](chat.md).
+
+
+::::
+
+::::{step} Start building agents and tools
+
+Once you've tested the default **Elastic AI Agent** with the [built-in Elastic tools](tools.md), 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#create-custom-tools) to assign them.
+
+::::
+
+:::::