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

docset.yml

@@ -295,3 +295,4 @@ 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"
+  agent-builder: "Elastic Agent Builder"

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

@@ -0,0 +1,35 @@
+---
+navigation_title: "Agents"
+applies_to:
+  stack: preview 9.2
+  deployment: 
+    self: unavailable
+  serverless:
+    elasticsearch: preview
+---
+
+# 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.
+
+## 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.
+
+## Create a new agent
+
+To create a new agent:
+
+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/conversations.md

@@ -0,0 +1,15 @@
+---
+navigation_title: "Conversations"
+applies_to:
+  stack: preview 9.2
+  deployment: 
+    self: unavailable
+  serverless:
+    elasticsearch: preview
+---
+
+# Conversations UI in {{agent-builder}}
+
+
+The **Conversations** 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,84 @@
+---
+applies_to:
+  stack: preview 9.2
+  deployment: 
+    self: unavailable
+  serverless:
+    elasticsearch: preview
+---
+
+# Get started 
+
+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
+
+- **Option 1:** [{{es}} {{serverless-short}}](/solutions/search/serverless-elasticsearch-get-started.md)
+- **Option 2:** [{{ech}}](/deploy-manage/deploy/elastic-cloud/cloud-hosted.md)
+
+:::{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).
+:::
+
+::::
+
+::::{step} Enable features
+
+Choose your preferred method to enable the {{agent-builder}} features.
+
+::::{tab-set}
+
+:::{tab-item} API
+:sync: api
+
+Run the following command in the Dev Tools [Console](/explore-analyze/query-filter/tools/console.md):
+
+```console
+POST kbn://internal/kibana/settings
+{
+   "changes": {
+      "agentBuilder:enabled": true
+   }
+}
+```
+
+:::
+
+:::{tab-item} {{ech}} UI
+:sync: stack
+```{applies_to}
+serverless: unavailable
+```
+
+On {{ech}} deployments, you can also enable the features in **Advanced Settings**:
+
+1. Access your Kibana settings through **Stack Management > Advanced Settings**.
+2. Enable the `agentBuilder` settings:
+```json
+uiSettings.overrides:
+  agentBuilder:enabled: true
+```
+
+:::
+
+::::
+
+::::
+
+::::{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 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).
+
+:::{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.
+:::
+
+::::
+:::::

solutions/search/agent-builder/limitations-known-issues.md

@@ -0,0 +1,26 @@
+---
+navigation_title: "Limitations & known issues"
+applies_to:
+  stack: preview 9.2
+  deployment: 
+    self: unavailable
+  serverless:
+    elasticsearch: preview
+---
+
+# Limitations and known issues in {{agent-builder}}
+
+## Model Selection
+
+Today we only use the `rainbow-sprinkles` model running on the Elastic Inference Service which is Claude 3.7, on Cloud / Serverless. Locally this picks the first AI connector available. Currently we do not have UI controls to select which connector (and therefore which model) to use. 
+
+
+{{agent-builder}} has some limitations to be aware of:
+
+Known Bugs
+Unable to follow up with a question in a conversation (resolved in latest 9.2-snapshot, affects serverless)
+Unable to use MCP server (resolved in latest 9.2-snapshot, affects serverless) 
+
+
+
+We're continuously working to improve these areas and welcome your feedback to help shape the future development of {{agent-builder}}.

solutions/search/agent-builder/programmatic-access.md

@@ -0,0 +1,103 @@
+---
+navigation_title: "Programmatic access"
+applies_to:
+  stack: preview 9.2
+  deployment: 
+    self: unavailable
+  serverless:
+    elasticsearch: preview
+---
+
+# Work programmatically with {{agent-builder}}
+
+{{agent-builder}} provides comprehensive APIs and additional integration options for programmatic access and automation.
+
+- **APIs**: RESTful APIs for creating, managing, and executing tools programmatically
+- **MCP server**: A standardized interface at `/api/chat/mcp` that allows external MCP clients (such as Claude Desktop) to access {{agent-builder}} tools
+- **A2A server**: Agent-to-agent communication endpoints that follow the A2A protocol specification, enabling external A2A clients to interact with {{agent-builder}} agents
+
+These interfaces enable you to build integrations with other applications and extend {{agent-builder}}'s capabilities to fit your specific requirements.
+
+## Working with the API
+
+The Chat API allows you to programmatically create and manage tools. You can use this API to:
+- Create new tools
+- Update existing tool configurations
+- Delete tools when they're no longer needed
+- List available tools
+
+Here's an example API call to create a new custom {{esql}} tool:
+
+```console
+POST kbn://api/chat/tools
+{
+  "id": "recent_orders",
+  "description": "Find recent orders for a customer",
+  "configuration": {
+    "query": "FROM orders | WHERE customer_id == ?customer_id | SORT @timestamp DESC | LIMIT 5",
+    "params": {
+      "customer_id": {
+        "type": "keyword",
+        "description": "Customer identifier"
+      }
+    }
+  },
+  "type": "esql",
+  "tags": ["orders", "customers"]
+}
+```
+
+## MCP server
+
+The [**Model Context Protocol (MCP) server**](https://modelcontextprotocol.io/docs/getting-started/intro) server provides a standardized interface for external clients to access {{agent-builder}} tools.
+
+### MCP server endpoint
+
+The MCP server is available at:
+
+```
+/api/chat/mcp
+```
+
+### Configuring Claude Desktop for MCP integration
+
+To use Claude Desktop with your Elastic instance:
+
+```json
+{
+  "mcpServers": {
+    "elastic": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://your-kibana-url/api/chat/mcp",
+        "--header",
+        "Authorization:${AUTH_HEADER}"
+      ],
+      "env": {
+        "AUTH_HEADER": "ApiKey your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## 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.
+
+### Agentcards endpoint
+
+Get metadata about available agents:
+
+```
+GET /api/chat/a2a/{agentId}.json
+```
+
+### A2A protocol endpoint
+
+Interact with agents following the A2A protocol specification:
+
+```
+POST /api/chat/a2a/{agentId}
+```