diff --git a/solutions/search/agent-builder/a2a-server.md b/solutions/search/agent-builder/a2a-server.md index 45b08710f8..7077b6b963 100644 --- a/solutions/search/agent-builder/a2a-server.md +++ b/solutions/search/agent-builder/a2a-server.md @@ -7,9 +7,9 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Agent-to-Agent (A2A) server @@ -33,5 +33,5 @@ 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). +Both A2A endpoints require API key authentication. For more information about the A2A protocol, refer to the [A2A protocol specification](https://a2aprotocol.ai/docs/guide/a2a-protocol-specification-python#protocol-flow-diagram). ::: diff --git a/solutions/search/agent-builder/agent-builder-agents.md b/solutions/search/agent-builder/agent-builder-agents.md index d3350c4a3d..8d9ea140f3 100644 --- a/solutions/search/agent-builder/agent-builder-agents.md +++ b/solutions/search/agent-builder/agent-builder-agents.md @@ -7,24 +7,27 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # {{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. +Agents are AI models (LLMs) defined with custom instructions and a set of assigned [tools](tools.md). Users [chat](chat.md) with agents using natural language, in the Agent Builder UI or programmatically. -Each agent manages the conversation flow, interprets user requests, and provides responses based on its configured tools, instructions, and behavior settings. +An agent parses user requests to define a goal and then runs tools in a loop to achieve that goal. The agent 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. +When you ask a question to an agent, it analyzes your request to define a specific goal. It selects the most appropriate tools and determines the right arguments to use. The agent evaluates the information returned after each action 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. +:::{note} +The default `Elastic AI Agent` is immutable and cannot be edited. To customize agent behavior, you need to create a custom agent by cloning the default agent or creating a new one from scratch. +::: + ## Manage your agents The **Agents** page provides a centralized view of all your agents. From this page you can: @@ -34,7 +37,7 @@ The **Agents** page provides a centralized view of all your agents. From this pa - 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. + - **Elastic AI Agent**: you can **chat** or **clone** the default agent using the chat or clone buttons. The default agent cannot be edited directly. :::{image} images/chat-and-clone-buttons.png :alt: Chat with agent and clone agent buttons :width: 120px @@ -45,7 +48,7 @@ The **Agents** page provides a centralized view of all your agents. From this pa :width: 130px ::: -## How to create a new agent +## Create a new agent in the GUI Follow these steps to create a new agent: @@ -58,10 +61,10 @@ 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. +Select the **New agent** button to being creating a new agent. :::{image} images/new-agent-button.png -:alt: Click the New agent button to create a new agent +:alt: Select the New agent button to create a new agent :width: 150px ::: @@ -73,13 +76,13 @@ Click the **New agent** button to start creating a new agent. 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**.

Custom instructions define the agent's personality and determine how it will interact with users and perform tasks. +1. Add **Custom instructions**.

Custom instructions define the agent's personality and determine how it interacts 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. + Agent Builder adds your custom instructions 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 +1. Set the **Display name** for users. +1. Add a **Display description** to explain the agent's purpose. :::: @@ -96,13 +99,13 @@ Select the combination of built-in and custom tools available to the agent, base 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 +- Select 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. +Select **Save** to create your agent, or **Save and chat** to create the agent and immediately begin a conversation with it. :::{image} images/save-and-chat-buttons.png :alt: Save and Save and chat buttons @@ -110,4 +113,16 @@ Click **Save** to create your agent, or **Save and chat** to create the agent an ::: :::: -::::: \ No newline at end of file +::::: + +## Agents API + +The Agents API enables programmatic access to agent creation and management actions. + +### Quick overview + +For an overview, refer to [Agents API](kibana-api.md#agents). + +### Serverless API reference + +For the complete API reference, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). \ No newline at end of file diff --git a/solutions/search/agent-builder/chat.md b/solutions/search/agent-builder/chat.md index df244a1b40..e14655502f 100644 --- a/solutions/search/agent-builder/chat.md +++ b/solutions/search/agent-builder/chat.md @@ -7,13 +7,77 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: -# {{agent-builder}}: Agent Chat UI +# {{agent-builder}}: Agent Chat + +**Agent Chat** is the synchronous chat interface for natural language conversations with your [agents](agent-builder-agents.md). + +The chat GUI and programmatic interfaces enable real-time communication where you can ask questions, request data analysis, and receive immediate responses from your configured agents. + +## Get started + +:::{tip} +Refer to the [getting started](get-started.md) guide to enable the feature and ingest some data. +::: + +Once the feature is enabled, find **Agents** in the navigation menu to begin chatting. +You can also search for **Agent Builder** in the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md). + +This takes you to the chat GUI: + +:::{image} images/agent-builder-chat-UI-get-started.png +::: +:alt: The main Agent Chat GUI showing the chat window, message input box, and agent selection panel + +## Agent Chat GUI + +### Chat and select agent + +Use the text input area to chat with an agent in real time. By default, you chat with the built-in Elastic AI Agent. + +:::{image} images/agent-builder-chat-input.png +:alt: Text input area for chatting with agents +:width: 850px +::: + +#### Agent selector + +Use the agent selector to switch agents, to navigate to the agent management section, or to create a new agent. + +:::{image} images/agent-builder-agent-selector.png +:alt: Agent selector dropdown and message input field +:width: 850px +::: + +### Find conversation history + +Use the left sidebar to access previous conversations. + +:::{image} images/agent-builder-chat-history.png +:alt: Chat history panel showing conversation list +:width: 250px +::: + +## Agent Chat API + +The Agent Chat API provides programmatic access to chat functionality through REST endpoints. + +### Quick overview + +For a quick overview of the REST API for conversations, refer to [Chat and conversations API](kibana-api.md#chat-and-conversations). + +### Serverless API reference + +For the complete API reference, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). + + + + + -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. diff --git a/solutions/search/agent-builder/get-started.md b/solutions/search/agent-builder/get-started.md index bc58fbb3de..56272f2636 100644 --- a/solutions/search/agent-builder/get-started.md +++ b/solutions/search/agent-builder/get-started.md @@ -7,24 +7,24 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Get started with {{agent-builder}} :::{tip} -See the [overview page](../elastic-agent-builder.md) for full list of docs pages. +Refer to the [overview page](../elastic-agent-builder.md) for the full list of Agent Builder docs. ::: -% TODO: Delete this tip when unhide pages +% TODO: Remove 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). +If you don't already have an Elastic deployment, refer to [Select 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. @@ -35,16 +35,16 @@ You can set up a new [space](/deploy-manage/manage-spaces.md) to use the solutio ::::{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. +{{agent-builder}} is turned off by default in the initial release, so you 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** +4. Select **Save changes** -Refresh the browser page and find **Agents** in the navigation menu to start using the feature. +Refresh the browser page and find **Agents** in the navigation menu to begin 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). @@ -52,30 +52,32 @@ You can also search for **Agent Builder** in the [global search bar](/explore-an ::::{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. +Before you begin with agents, you need some data in your {{es}} cluster. Otherwise, you will 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). +If you're not ready to add your own data, you can: +- Use the Elastic [sample data](/manage-data/ingest/sample-data.md). +- Generate synthetic financial data using [this Python tool](https://github.com/jeffvestal/synthetic-financial-data?tab=readme-ov-file#synthetic-financial-data-generator-). (This requires your [{{es}} URL and an API key](/solutions/search/search-connection-details.md)). + % TODO: we can link to a an agent builder tutorial if we add one in the docs ::: :::: -::::{step} Start chatting +::::{step} Begin 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. +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 begin chatting immediately. Learn more in [Agent Chat](chat.md). - :::: -::::{step} Start building agents and tools +::::{step} Begin 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. +Once you've tested the default **Elastic AI Agent** with the [built-in Elastic tools](tools.md), you can begin [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. :::: diff --git a/solutions/search/agent-builder/images/agent-builder-agent-selector.png b/solutions/search/agent-builder/images/agent-builder-agent-selector.png new file mode 100644 index 0000000000..f50463d38e Binary files /dev/null and b/solutions/search/agent-builder/images/agent-builder-agent-selector.png differ diff --git a/solutions/search/agent-builder/images/agent-builder-chat-UI-get-started.png b/solutions/search/agent-builder/images/agent-builder-chat-UI-get-started.png new file mode 100644 index 0000000000..8747903ab0 Binary files /dev/null and b/solutions/search/agent-builder/images/agent-builder-chat-UI-get-started.png differ diff --git a/solutions/search/agent-builder/images/agent-builder-chat-history.png b/solutions/search/agent-builder/images/agent-builder-chat-history.png new file mode 100644 index 0000000000..eb6f189912 Binary files /dev/null and b/solutions/search/agent-builder/images/agent-builder-chat-history.png differ diff --git a/solutions/search/agent-builder/images/agent-builder-chat-input.png b/solutions/search/agent-builder/images/agent-builder-chat-input.png new file mode 100644 index 0000000000..d449c894ff Binary files /dev/null and b/solutions/search/agent-builder/images/agent-builder-chat-input.png differ diff --git a/solutions/search/agent-builder/images/copy-mcp-server-url-button.png b/solutions/search/agent-builder/images/copy-mcp-server-url-button.png new file mode 100644 index 0000000000..e20214ab8a Binary files /dev/null and b/solutions/search/agent-builder/images/copy-mcp-server-url-button.png differ diff --git a/solutions/search/agent-builder/images/new-tool-button.png b/solutions/search/agent-builder/images/new-tool-button.png new file mode 100644 index 0000000000..3cdd7da220 Binary files /dev/null and b/solutions/search/agent-builder/images/new-tool-button.png differ diff --git a/solutions/search/agent-builder/images/test-icon.png b/solutions/search/agent-builder/images/test-icon.png new file mode 100644 index 0000000000..1993b817cd Binary files /dev/null and b/solutions/search/agent-builder/images/test-icon.png differ diff --git a/solutions/search/agent-builder/images/tool-save-save-and-test-buttons.png b/solutions/search/agent-builder/images/tool-save-save-and-test-buttons.png new file mode 100644 index 0000000000..e352479879 Binary files /dev/null and b/solutions/search/agent-builder/images/tool-save-save-and-test-buttons.png differ diff --git a/solutions/search/agent-builder/images/tools-overview.png b/solutions/search/agent-builder/images/tools-overview.png new file mode 100644 index 0000000000..fc9eb602d7 Binary files /dev/null and b/solutions/search/agent-builder/images/tools-overview.png differ diff --git a/solutions/search/agent-builder/kibana-api.md b/solutions/search/agent-builder/kibana-api.md index 8e76fd1806..a4272cda5f 100644 --- a/solutions/search/agent-builder/kibana-api.md +++ b/solutions/search/agent-builder/kibana-api.md @@ -7,17 +7,16 @@ applies_to: --- :::{warning} -These pages are hidden from the docs TOC and have `noindexed` meta headers. +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. + +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Work with {{agent-builder}} using the APIs -These APIs allow you to programmatically work with the {{agent-builder}} abstractions. - -## API reference +This page provides a quick overview of the main Kibana API endpoints for {{agent-builder}}. For complete details including all available parameters, request/response schemas, and error handling, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). -For the full API documentation, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). -% TODO: Update link once page is live +These APIs allow you to programmatically work with the {{agent-builder}} abstractions. ## Using the APIs @@ -28,10 +27,17 @@ GET kbn://api/agent_builder/tools To use these APIs with tools like `curl`, replace the `kbn://` protocol with your Kibana URL. - +:::{note} +Set the required environment variables before running curl commands: ```bash -curl -X GET "https:///api/agent_builder/tools" \ - -H "Authorization: ApiKey " +export KIBANA_URL="your-kibana-url" +export API_KEY="your-api-key" +``` +::: + +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools" \ + -H "Authorization: ApiKey ${API_KEY}" ``` :::{tip} To generate API keys, search for `API keys` in the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md). @@ -39,122 +45,639 @@ To generate API keys, search for `API keys` in the [global search bar](/explore- ::: ## 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 -: ```console - GET kbn://api/agent_builder/tools - ``` +**Example:** List all tools +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/tools +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Create a tool +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/tools +{ + "id": "example-esql-tool", + "type": "esql", + "description": "An ES|QL query tool for analyzing financial trades with time filtering", + "tags": ["analytics", "finance", "updated"], + "configuration": { + "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit", + "params": { + "startTime": { + "type": "date", + "description": "Start time for the analysis in ISO format" + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return" + } + } + } +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "example-esql-tool", + "type": "esql", + "description": "Example ES|QL query tool for analyzing financial trades with time filtering", + "tags": ["analytics", "finance"], + "configuration": { + "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit", + "params": { + "startTime": { + "type": "date", + "description": "Start time for the analysis in ISO format" + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return" + } + } + } + }' +``` +::: + +:::: + +**Example:** Get a tool by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/tools/{id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools/{id}" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Delete a tool by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +DELETE kbn://api/agent_builder/tools/{id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/tools/{id}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" +``` +::: + +:::: + +**Example:** Update a tool by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +PUT kbn://api/agent_builder/tools/{toolId} +{ + "description": "Updated ES|QL query tool for analyzing financial trades with time filtering", + "tags": ["analytics", "finance", "updated"], + "configuration": { + "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit", + "params": { + "startTime": { + "type": "date", + "description": "Start time for the analysis in ISO format" + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return" + } + } + } +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X PUT "https://${KIBANA_URL}/api/agent_builder/tools/{toolId}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "description": "Updated ES|QL query tool for analyzing financial trades with time filtering", + "tags": ["analytics", "finance", "updated"], + "configuration": { + "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit", + "params": { + "startTime": { + "type": "date", + "description": "Start time for the analysis in ISO format" + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return" + } + } + } + }' +``` +::: -Create a tool -: ```console - POST kbn://api/agent_builder/tools - ``` +:::: -Get a tool by ID -: ```console - GET kbn://api/agent_builder/tools/{id} - ``` +**Example:** Run a tool +::::{tab-set} +:group: api-examples -Delete a tool by ID -: ```console - DELETE kbn://api/agent_builder/tools/{id} - ``` +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/tools/_execute +{ + "tool_id": "platform.core.search", + "tool_params": { + "query": "can you find john doe's email from the employee index?" + } +} +``` +::: -Update a tool by ID -: ```console - PUT kbn://api/agent_builder/tools/{toolId} - ``` +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "tool_id": "platform.core.search", + "tool_params": { + "query": "can you find john doe's email from the employee index?"} + } + }' +``` +::: -Execute a tool -: ```console - POST kbn://api/agent_builder/tools/_execute - ``` +:::: ### Agents -List all agents -: ```console - GET kbn://api/agent_builder/agents - ``` - -Create an agent -: ```console - POST kbn://api/agent_builder/agents - ``` - -Get an agent by ID -: ```console - GET kbn://api/agent_builder/agents/{id} - ``` - -Update an agent by ID -: ```console - PUT kbn://api/agent_builder/agents/{id} - ``` - -Delete an agent by ID -: ```console - DELETE kbn://api/agent_builder/agents/{id} - ``` - -### Chat and Conversations - -Chat with an agent -: ```console - POST kbn://api/agent_builder/converse - ``` - -Chat with an agent and stream events -: ```console - POST kbn://api/agent_builder/converse/async - ``` - -List conversations -: ```console - GET kbn://api/agent_builder/conversations - ``` - -Get conversation by ID -: ```console - GET kbn://api/agent_builder/conversations/{conversation_id} - ``` - -Delete conversation by ID -: ```console - DELETE kbn://api/agent_builder/conversations/{conversation_id} - ``` - -### MCP Server - -Get MCP server configuration -: ```console - GET kbn://api/agent_builder/mcp - ``` - -Create or configure MCP server -: ```console - POST kbn://api/agent_builder/mcp - ``` - -Delete MCP server configuration -: ```console - DELETE kbn://api/agent_builder/mcp - ``` - -### A2A Protocol +**Example:** List all agents +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/agents +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/agents" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Create an agent +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/agents +{ + "id": "new-agent-id", + "name": "Search Index Helper", + "description": "Hi! I can help you search the data within the indices starting with \"content-\" prefix.", + "labels": ["custom-indices", "department-search"], + "avatar_color": "#BFDBFF", + "avatar_symbol": "SI", + "configuration": { + "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".", + "tools": [ + { + "tool_ids": [ + "platform.core.search", + "platform.core.list_indices", + "platform.core.get_index_mapping", + "platform.core.get_document_by_id" + ] + } + ] + } +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/agents" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "new-agent-id", + "name": "Search Index Helper", + "description": "Hi! I can help you search the data within the indices starting with \"content-\" prefix.", + "labels": ["custom-indices", "department-search"], + "avatar_color": "#BFDBFF", + "avatar_symbol": "SI", + "configuration": { + "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".", + "tools": [ + { + "tool_ids": [ + "platform.core.search", + "platform.core.list_indices", + "platform.core.get_index_mapping", + "platform.core.get_document_by_id" + ] + } + ] + } + }' +``` +::: + +:::: + +**Example:** Get an agent by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/agents/{id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Update an agent by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +PUT kbn://api/agent_builder/agents/{id} +{ + "name": "Search Index Helper", + "description": "Updated description - Search for anything in \"content-*\" indices!", + "labels": ["custom-indices", "department-search", "elastic-employees"], + "avatar_color": "#BFDBFF", + "avatar_symbol": "SI", + "configuration": { + "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".", + "tools": [{ + "tool_ids": [ + "platform.core.search", + "platform.core.list_indices", + "platform.core.get_index_mapping", + "platform.core.get_document_by_id" + ] + }] + } +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X PUT "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Search Index Helper", + "description": "Updated description - Search for anything in \"content-*\" indices!", + "labels": ["custom-indices", "department-search", "elastic-employees"], + "avatar_color": "#BFDBFF", + "avatar_symbol": "SI", + "configuration": { + "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".", + "tools": [{ + "tool_ids": [ + "platform.core.search", + "platform.core.list_indices", + "platform.core.get_index_mapping", + "platform.core.get_document_by_id" + ] + }] + } + }' +``` +::: + +:::: + +**Example:** Delete an agent by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +DELETE kbn://api/agent_builder/agents/{id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" +``` +::: + +:::: + +### Chat and conversations + +**Example:** Chat with an agent +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/converse +{ + "input": "What is Elasticsearch?", + "agent_id": "elastic-ai-agent" +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/converse" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "What is Elasticsearch?", + "agent_id": "elastic-ai-agent"}' +``` +::: + +:::: + +**Example:** Chat with an agent and stream events +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +POST kbn://api/agent_builder/converse/async +{ + "input": "Hello again let's have an async chat", + "agent_id": "elastic-ai-agent", + "conversation_id": "" +} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/converse/async" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Hello again let us have an async chat", + "agent_id": "elastic-ai-agent", + "conversation_id": "" + }' +``` +::: + +:::: + +**Example:** List conversations +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/conversations +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/conversations" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Get conversation by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/conversations/{conversation_id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + +**Example:** Delete conversation by ID +::::{tab-set} +:group: api-examples + +:::{tab-item} Console +:sync: console +```console +DELETE kbn://api/agent_builder/conversations/{conversation_id} +``` +::: + +:::{tab-item} curl +:sync: curl +```bash +curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "kbn-xsrf: true" +``` +::: + +:::: + +### MCP server API + +Refer to [](mcp-server.md) for more information. + + +Communicate with the MCP server using JSON-RPC 2.0. + +```bash +curl -X POST "https://${KIBANA_URL}/api/agent_builder/mcp" \ + -H "Authorization: ApiKey ${API_KEY}" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "kbn-xsrf: true" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list" + }' +``` + +:::{note} +This endpoint uses the JSON-RPC protocol. The MCP server is used by AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this Kibana API endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and does not work from the Dev Tools Console. +::: + +### A2A protocol Refer to [](a2a-server.md) for more information. -Get A2A agent card configuration -: ```console - GET kbn://api/agent_builder/a2a/{agentId}.json - ``` +**Example:** Get A2A agent card configuration +::::{tab-set} +:group: api-examples -Execute A2A agent task -: ```console - POST kbn://api/agent_builder/a2a/{agentId} - ``` +:::{tab-item} Console +:sync: console +```console +GET kbn://api/agent_builder/a2a/{agentId}.json +``` +::: +:::{tab-item} curl +:sync: curl +```bash +curl -X GET "https://${KIBANA_URL}/api/agent_builder/a2a/{agentId}.json" \ + -H "Authorization: ApiKey ${API_KEY}" +``` +::: + +:::: + + +% TODO: Execute A2A agent task section - commented out until ready +% Execute A2A agent task +% ::::{tab-set} +% :group: api-examples +% +% :::{tab-item} Console +% :sync: console +% :::{note} +% This endpoint uses the JSON-RPC protocol, which cannot be executed in the Dev Tools Console. +% Use curl or another HTTP client. +% ::: +% +% :::{tab-item} curl +% :sync: curl +% ```bash +% curl -X POST "https://${KIBANA_URL}/api/agent_builder/a2a/{agentId}" \ +% -H "Authorization: ApiKey ${API_KEY}" \ +% -H "kbn-xsrf: true" \ +% -H "Content-Type: application/json" \ +% -d '{ +% "jsonrpc": "2.0", +% "method": "complete", +% "params": { +% "messages": [ +% { +% "role": "user", +% "content": "Hello from A2A protocol" +% } +% ] +% }, +% "id": "task-123" +% }' +% ``` +% ::: +% +% :::: + + + + + +## API reference + +For the full API documentation, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). +% TODO: Update link once page is live \ No newline at end of file diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index e34daab523..0d509ea9bf 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -7,54 +7,58 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Limitations and known issues in {{agent-builder}} -## Model selection +## Limitations -Initially, {{agent-builder}} only supports working with the [Elastic Managed LLM](kibana://reference/connectors-kibana/elastic-managed-llm.md) running on the Elastic Inference Service, on {{ech}} and {{serverless-full}}. +### Agent Builder not enabled by default -Locally this picks the first AI connector available. +While in private technical preview, {{agent-builder}} is not enabled by default. Refer to [Get started](get-started.md#enable-agent-builder) for instructions. + +### Model selection + +Initially, {{agent-builder}} only supports working with the [Elastic Managed LLM](kibana://reference/connectors-kibana/elastic-managed-llm.md) running on the [Elastic Inference Service](/explore-analyze/elastic-inference/eis.md) {applies_to}`serverless: preview` {applies_to}`ess: preview 9.2`. + +Learn about [pricing](https://www.elastic.co/pricing/serverless-search) for the Elastic Managed LLM. ## Known issues +### Incompatible LLMs + +While Elastic offers LLM [connectors](kibana://reference/connectors-kibana.md) for many different vendors and models, not all LLMs are robust enough to be used with {{agent-builder}}. We recommend using the [Elastic Managed LLM](kibana://reference/connectors-kibana/elastic-managed-llm.md) (the default). + +The following errors suggest your selected model may not be compatible with {{agent-builder}}: + +```console-response +Error: Invalid function call syntax +``` + +```console-response +Error executing agent: No tool calls found in the response. +``` + +### Misinterpreted SQL syntax as ES|QL + +The `.execute_esql` tool is designed only for [{{esql}}](elasticsearch://reference/query-languages/esql.md) syntax, not other query languages. + +When using SQL syntax with the default agent, it attempts to use the `.execute_esql` tool instead of recognizing the input as SQL. -- **Default agent can misinterpret SQL syntax as ES|QL** - - The `.execute_esql` tool is designed only for [{{esql}}](elasticsearch://reference/query-languages/esql.md) syntax, not other query languages - - When using SQL syntax with the default agent, it attempts to use the `.execute_esql` tool instead of recognizing the input as SQL - - This results in parsing errors like this: - ```console-response - [ - { - "type": "error", - "data": { - "message": "parsing_exception\n\tCaused by:\n\t\tinput_mismatch_exception: null\n\tRoot causes:\n\t\tparsing_exception: line 1:15: mismatched input 'WHERE' expecting {, '|', ',', 'metadata'}", - "stack": "ResponseError: parsing_exception\n\tCaused by:\n\t\tinput_mismatch_exception: null\n\tRoot causes:\n\t\tparsing_exception: line 1:15: mismatched input 'WHERE' expecting {, '|', ',', 'metadata'}\n at KibanaTransport._request (Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:591:17)\n at processTicksAndRejections (node:internal/process/task_queues:105:5)\n at Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:697:22\n at KibanaTransport.request (Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:694:14)" - } - } - ] - ``` - -- **Not all LLMs are compatible** - - While Elastic offers LLM connectors for many different vendors and models, not all LLMs are robust enough to be used with {{agent-builder}}. - - Errors such as: - ```console-response - Error: Invalid function call syntax - ``` - or - ``` - Error executing agent: No tool calls found in the response. - ``` - may indicate that your selected model is ill-equipped for the precise response structure necessary for {{agent-builder}}. - - We recommend using the [Elastic Managed LLM](kibana://reference/connectors-kibana/elastic-managed-llm.md) - -- **{{agent-builder}} is not accessible** - - {{agent-builder}} was added in a private preview in September, 2025 for Serverless, and in 9.2.0 for Elastic Cloud. - - While in this preview stage, {{agent-builder}} is not enabled by default. - - To enable it, you must go to Stack Management -> Kibana -> Advanced Settings -> Elastic Agent Builder, and enable it. +This results in parsing errors like this: +```console-response +[ + { + "type": "error", + "data": { + "message": "parsing_exception\n\tCaused by:\n\t\tinput_mismatch_exception: null\n\tRoot causes:\n\t\tparsing_exception: line 1:15: mismatched input 'WHERE' expecting {, '|', ',', 'metadata'}", + "stack": "ResponseError: parsing_exception\n\tCaused by:\n\t\tinput_mismatch_exception: null\n\tRoot causes:\n\t\tparsing_exception: line 1:15: mismatched input 'WHERE' expecting {, '|', ',', 'metadata'}\n at KibanaTransport._request (Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:591:17)\n at processTicksAndRejections (node:internal/process/task_queues:105:5)\n at Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:697:22\n at KibanaTransport.request (Desktop/Dev/kibana/node_modules/@elastic/elasticsearch/node_modules/@elastic/transport/src/Transport.ts:694:14)" + } + } +] +``` \ No newline at end of file diff --git a/solutions/search/agent-builder/mcp-server.md b/solutions/search/agent-builder/mcp-server.md index 3d8e8fa529..123cf26c07 100644 --- a/solutions/search/agent-builder/mcp-server.md +++ b/solutions/search/agent-builder/mcp-server.md @@ -6,12 +6,12 @@ applies_to: elasticsearch: preview --- -# MCP server +# Model Context Protocol (MCP) server :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: The [**Model Context Protocol (MCP) server**](https://modelcontextprotocol.io/docs/getting-started/intro) provides a standardized interface for external clients to access {{agent-builder}} tools. @@ -23,32 +23,42 @@ The MCP server is available at: ``` {KIBANA_URL}/api/agent_builder/mcp ``` +:::{tip} +You can copy your MCP server URL directly in the Tools GUI. Refer to [](tools.md#copy-your-mcp-server-url). +::: ## Configuring MCP clients -Most MCP clients (such as Claude Desktop, Cursor, VS Code, etc.) have similar configuration patterns. To connect to your Elastic instance, you'll need to provide your Kibana URL and API key in the client's configuration file, typically in the following format: +Most MCP clients (such as Claude Desktop, Cursor, VS Code, etc.) have similar configuration patterns. To connect to your Elastic instance, you need to provide your Kibana URL and API key in the client's configuration file, typically in the following format: ```json - { "mcpServers": { "elastic-agent-builder": { "command": "npx", "args": [ "mcp-remote", - "/api/agent_builder/mcp", + "${KIBANA_URL}/api/agent_builder/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { - "AUTH_HEADER": "ApiKey " + "KIBANA_URL": "${KIBANA_URL}", + "AUTH_HEADER": "ApiKey ${API_KEY}" } } } ``` :::{note} -Replace `` with your actual Kibana URL and `` with your API key. For information on generating API keys, see [API keys](https://www.elastic.co/docs/solutions/search/search-connection-details). +Set the following environment variables: + +```bash +export KIBANA_URL="your-kibana-url" +export API_KEY="your-api-key" +``` + +For information on generating API keys, refer to [API keys](https://www.elastic.co/docs/solutions/search/search-connection-details). -Tools will be executed with the scope assigned to the API key. Make sure your API key has the appropriate permissions to only access the indices and data that you want to expose via the MCP server. +Tools execute with the scope assigned to the API key. Make sure your API key has the appropriate permissions to only access the indices and data that you want to expose through the MCP server. ::: diff --git a/solutions/search/agent-builder/programmatic-access.md b/solutions/search/agent-builder/programmatic-access.md index 63029c15b4..0474ff65b0 100644 --- a/solutions/search/agent-builder/programmatic-access.md +++ b/solutions/search/agent-builder/programmatic-access.md @@ -7,7 +7,9 @@ applies_to: --- :::{warning} -These pages are hidden from the docs TOC and have `noindexed` meta headers. +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. + +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Work programmatically with {{agent-builder}} diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index ac1238e155..57a6535853 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -7,17 +7,25 @@ applies_to: --- :::{warning} -WIP +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. -These pages are hidden from the docs TOC and have `noindexed` meta headers. +**Go to the docs [landing page](/solutions/search/elastic-agent-builder.md).** ::: # Tools in {{agent-builder}} -Agents use tools to search, retrieve, and take meaningful steps on your behalf. +[Agents](agent-builder-agents.md) use tools to search, retrieve, and take meaningful steps on your behalf. Tools can be thought of as functions: modular, reusable actions that agents can call to interact with your {{es}} data. +Each tool is defined by several key fields: + +- **`id`**: The unique identifier that agents use to reference the tool (e.g., `.get_document_by_id`) +- **`type`**: Specifies whether the tool is `builtin` (pre-defined) or `esql` (custom) +- **`description`**: Natural language explanation of what the tool does, used by the AI to determine when to use it +- **`configuration`**: Contains the tool's logic - empty for built-in tools, or query and parameters for custom ESQL tools +- **`schema`**: Defines the input parameters the tool requires, written in JSON Schema format + ## How agents use tools Tools enable agents to work with {{es}} data. When an agent receives a natural language query, it does the following: @@ -46,6 +54,16 @@ Key built-in tools include: Built-in tools serve as building blocks for more complex interactions and provide the foundation for agent capabilities. +:::{note} + +Tool namespacing helps organize and identify tools by their source. Built-in tools use a consistent prefix (`platform.core`) to indicate they are built-in capabilities. This convention: + +- Prevents naming conflicts between system and custom tools +- Makes it easy to identify tool sources +- Provides a consistent pattern for tool identification + +::: + ## Custom tools You can extend the built-in tool catalog with your own custom tool definitions. Custom tools offer flexibility in how they interact with your data: @@ -55,17 +73,7 @@ You can extend the built-in tool catalog with your own custom tool definitions. This flexibility allows you to create tools that match your specific use cases and data access patterns. -### Find available tools - -Find the list of available tools on the **Tools** landing page in the UI. - -You can also use the following API call, which returns detailed information about built-in tools, including their parameters and descriptions. - -``` -GET kbn://api/agent_builder/tools -``` - -## Tool parameters +### Tool parameters Parameters enable tools to be dynamic and adaptable to different queries. Each parameter has: @@ -73,97 +81,69 @@ Parameters enable tools to be dynamic and adaptable to different queries. Each p - A **type** (such as keyword, number, boolean) - A **description** that helps the agent understand when and how to use it -For tools with explicit queries, parameters are defined in the query using the syntax `?parameter_name` and must be configured when creating the tool. +For {{esql}} tools, parameters are defined in the query using the syntax `?parameter_name` and must be configured when creating the tool. Parameters can be: - **Manually defined**: You explicitly define the parameters a tool needs -- **Inferred from query**: For tools with explicit queries, you can use the "Infer parameters from query" button to automatically detect parameters in your query statement +- **Inferred from query**: For {{esql}} tools, you can use the "Infer parameters from query" button to automatically detect parameters in your query statement + +The tool's `schema` field defines these parameters using JSON Schema format, specifying: +- **`type`**: Always `"object"` for tool parameters +- **`properties`**: Dictionary defining each parameter's type and description +- **`required`**: Array listing mandatory parameters +- **`additionalProperties`**: Set to `false` to reject undefined parameters Providing clear, descriptive parameter names and descriptions helps agents properly use your tools when answering queries. ## Create custom tools -You can create custom tools to help agents interact with your data in specific ways. This section covers how to create and test tools through both the UI and API. +You can create custom tools to help agents interact with your data in specific ways. This section covers how to create and test tools in the UI + +1. Navigate to the **Tools** page in Kibana +2. Click **New tool** -### Use the UI + :::{image} images/new-tool-button.png + :alt: New tool button for creating custom tools + :width: 150px + ::: -1. Navigate to the Tools page in Kibana -2. Click the blue **New tool** button -3. Select the tool type you want to create 4. Fill in the required fields: - **Name**: Enter a descriptive name for your tool - **Description**: Write a clear explanation of what the tool does and when it should be used - - Tool-specific configuration (explicit query or index settings) - - **Parameters**: For tools with explicit queries, define any parameters your query needs + - **Tool type**: Choose either **{{esql}}** query or **Index search** + - **Parameters**: For tools with {{esql}} queries, define any parameters your query needs - **Tags**: (Optional) Add labels to categorize and organize your tools -5. Click **Save** to create your tool - -### Use the API - -You can also create tools programmatically: - -For tools with explicit {{esql}} queries: - -```json -POST kbn://api/agent_builder/tools -{ - "id": "recent_orders", <1> - "description": "Find recent orders for a specific customer. Use this tool when users ask about their recent orders or purchase history.", <2> - "configuration": { - "query": "FROM orders | WHERE customer_id == ?customer_id | SORT @timestamp DESC | LIMIT 5", <3> - "params": { - "customer_id": { <4> - "type": "keyword", - "description": "The unique identifier for the customer" - } - } - }, - "type": "esql", <5> - "tags": ["orders", "customers"] <6> -} -``` - -1. A unique identifier for your tool that will be used in API calls -2. Detailed description that helps the agent understand when to use this tool -3. {{esql}} query with parameters prefixed by `?` -4. Parameter definition including type and description -5. Tool type specifier (use "esql" for tools with explicit {{esql}} queries) -6. Optional tags for categorization - -For index search tools: - -```json -POST kbn://api/agent_builder/tools -{ - "id": "search_products", <1> - "description": "Search the products catalog for specific items. Use this when users are looking for product information.", <2> - "configuration": { - "pattern": "products", <3> - "fields": ["name", "description", "category", "tags"] <4> - }, - "type": "index_search", <5> - "tags": ["products", "catalog"] <6> -} -``` - -1. Unique identifier for the tool -2. Description explaining when and how to use this tool -3. The specific index pattern this tool will search against -4. Fields within the index that should be searchable -5. Tool type specifier (use `index_search` for index search tools) -6. Optional tags for organization +5. Choose how to save your tool: + - Click **Save** to create the tool + - Click **Save and test** to create the tool and immediately open the testing interface + + :::{image} images/tool-save-save-and-test-buttons.png + :alt: Save and Save and test buttons for tool creation + :width:250px + ::: ### Testing your tools -After creating a tool, test it before assigning it to agents: +Before assigning tools to agents, verify they work correctly by testing them. Testing helps ensure your tool returns useful results and handles parameters correctly. -1. Find your tool in the Tools list -2. Click the test icon associated with your tool -3. Enter test values for each parameter or search query -4. Run the test to verify the tool executes correctly and returns the expected results +If you didn't click **Save and test** immediately: -Testing helps ensure your tool returns useful results and handles parameters correctly. +1. Find your tool in the Tools list +2. Click the test icon (play button) associated with your tool +:::{image} images/test-icon.png +:alt: Test icon (play button) for running tool tests +:width: 150px +::: +3. Enter test data based on your tool type: + - **For {{esql}} tools with parameters**: Enter realistic test values for each parameter in the **Inputs** section + - **For Index search tools**: Enter a sample search query to test the search functionality +4. Click **Submit** to run the test +5. Review the Response section to verify: + - The tool executes without errors + - Results are returned in the expected format + - The data matches your expectations +7. Now you can [assign the tool to an agent](#assign-tools-to-agents) ### Best practices @@ -172,23 +152,24 @@ Testing helps ensure your tool returns useful results and handles parameters cor 3. **Limit scope**: Focus each tool on a specific task rather than creating overly complex tools 4. **Use meaningful parameter names**: Choose names that clearly indicate what the parameter represents 5. **Add comprehensive parameter descriptions**: Help the agent understand what values to use -6. **Include `LIMIT` clauses in explicit queries**: Prevent returning excessive results +6. **Include `LIMIT` clauses in {{esql}} queries**: Prevent returning excessive results 7. **Use appropriate tags**: Add relevant tags to make tools easier to find and organize 8. **Limit tool count**: More tools are not always better. Try to keep each agent focused with a limited number of relevant tools. -## Tool namespaces +## Manage tools -Tool namespacing helps organize and identify tools by their source. Built-in tools use a consistent prefix (`platform.core`) to indicate they are built-in capabilities. This convention: +### Find available tools -- Prevents naming conflicts between system and custom tools -- Makes it easy to identify tool sources -- Provides a consistent pattern for tool identification +Find the list of available tools on the **Tools** landing page in the UI, or use [Tools API](kibana-api.md#tools). -## Manage tools +:::{image} images/tools-overview.png +:alt: Tools landing page showing the list of available tools with their descriptions and actions +:width:800px +::: ### List available tools -Access the complete list of available tools from the Tools page in Kibana. This view shows: +Access the complete list of available tools from the **Tools** page in Kibana. This view shows: - Tool names and descriptions - Tool types - Associated tags @@ -209,4 +190,25 @@ Custom tools can be modified or removed as needed: 2. Click the edit icon to update the tool or the delete icon to remove it 3. For updates, modify the tool properties and save your changes -Note that built-in tools cannot be modified or deleted. \ No newline at end of file +Note that built-in tools cannot be modified or deleted. + +## Tools API + +For a quick overview of how to work programmatically with tools, refer to [Tools API](kibana-api.md#tools). + +### Serverless API reference + +For the complete API reference, refer to the [Kibana serverless API reference](https://www.elastic.co/docs/api/doc/serverless/). + +## Copy your MCP server URL + +Tools can also be accessed through the Model Context Protocol (MCP) server, which provides a standardized interface for external clients to use Agent Builder tools. + +The **Tools** UI provides a **Copy your MCP server URL** button for easy access. + +:::{image} images/copy-mcp-server-url-button.png +:alt: Copy MCP server URL button for easy configuration of external clients +:width: 250px +::: + +For detailed MCP server configuration, refer to [MCP server](mcp-server.md). \ No newline at end of file diff --git a/solutions/search/elastic-agent-builder.md b/solutions/search/elastic-agent-builder.md index 82bf1ee979..4a3534cd71 100644 --- a/solutions/search/elastic-agent-builder.md +++ b/solutions/search/elastic-agent-builder.md @@ -7,9 +7,7 @@ applies_to: --- :::{warning} -WIP - -These pages are hidden from the docs TOC and have `noindexed` meta headers. +These pages are currently hidden from the docs TOC and have `noindexed` meta headers. ::: # {{agent-builder}} @@ -23,18 +21,18 @@ You can use the built-in agent for natural language conversations with any {{es} - **Interactive chat interface**: Ask questions about your {{es}} data using natural language in the Agent Chat UI. - **Agent-based architecture**: Configure AI-powered agents with customizable behaviors and tool access. - **Modular and extensible tools**: Extend your system with tools for {{es}} data access and manipulation. -- **ES|QL integration**: Create and execute [ES|QL](elasticsearch://reference/query-languages/esql.md)-powered tools for specialized data queries. +- **ES|QL integration**: Create and run [ES|QL](elasticsearch://reference/query-languages/esql.md)-powered tools for specialized data queries. - **MCP server**: Connect external MCP clients to access chat tools through a standardized interface. - **A2A server**: Enable agent-to-agent communication following the A2A protocol specification. - **Programmatic APIs**: Create, manage, and execute tools and agents through Kibana APIs. ## Key concepts -The {{agent-builder}} framework is built around several key components that work together to provide a flexible and powerful conversational experience. +The {{agent-builder}} framework consists of three key components: Agent Chat, Agents, and Tools. -### Agent Chat UI +### Agent Chat -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. +**Agent Chat** 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. [**Learn more about Agent Chat**](agent-builder/chat.md) @@ -50,6 +48,12 @@ Tools are modular, reusable functions that agents use to search, retrieve, and m [**Learn more about tools**](agent-builder/tools.md) +## Get started + +To get started you need an Elastic deployment and you must enable the feature. + +[**Get started with {{agent-builder}}**](agent-builder/get-started.md) + ## Programmatic interfaces {{agent-builder}} provides APIs and LLM integration options for programmatic access and automation. @@ -57,9 +61,9 @@ These interfaces enable you to build integrations with other applications and ex [**Learn more about programmatic access**](agent-builder/programmatic-access.md) -## Get started +## Limitations and known issues -To get started you need an Elastic deployment and you must enable the feature. +{{agent-builder}} is in technical preview. -[**Get started with {{agent-builder}}**](agent-builder/get-started.md) +[**Learn more about limitations and known issues**](agent-builder/limitations-known-issues.md)