diff --git a/.gitignore b/.gitignore index c4f17bc242..011dd3465d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,10 @@ .artifacts .DS_store +# Jetbrains files +.idea +*.iml + # Add LLM/AI related files AGENTS.md .github/copilot-instructions.md diff --git a/docset.yml b/docset.yml index bacc98d4cf..a904166be5 100644 --- a/docset.yml +++ b/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 \ No newline at end of file + agent-builder: "Elastic Agent Builder" + kube-stack-version: 0.6.3 + diff --git a/solutions/search/agent-builder/a2a-server.md b/solutions/search/agent-builder/a2a-server.md new file mode 100644 index 0000000000..45b08710f8 --- /dev/null +++ b/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). +::: diff --git a/solutions/search/agent-builder/agent-builder-agents.md b/solutions/search/agent-builder/agent-builder-agents.md new file mode 100644 index 0000000000..d3350c4a3d --- /dev/null +++ b/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**.

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 +::: + +:::: +::::: \ No newline at end of file diff --git a/solutions/search/agent-builder/chat.md b/solutions/search/agent-builder/chat.md new file mode 100644 index 0000000000..df244a1b40 --- /dev/null +++ b/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. + diff --git a/solutions/search/agent-builder/get-started.md b/solutions/search/agent-builder/get-started.md new file mode 100644 index 0000000000..bc58fbb3de --- /dev/null +++ b/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. + +:::: + +::::: diff --git a/solutions/search/agent-builder/images/chat-and-clone-buttons.png b/solutions/search/agent-builder/images/chat-and-clone-buttons.png new file mode 100644 index 0000000000..0f1f1c6880 Binary files /dev/null and b/solutions/search/agent-builder/images/chat-and-clone-buttons.png differ diff --git a/solutions/search/agent-builder/images/chat-edit-clone-delete.png b/solutions/search/agent-builder/images/chat-edit-clone-delete.png new file mode 100644 index 0000000000..10e0d0675b Binary files /dev/null and b/solutions/search/agent-builder/images/chat-edit-clone-delete.png differ diff --git a/solutions/search/agent-builder/images/new-agent-button.png b/solutions/search/agent-builder/images/new-agent-button.png new file mode 100644 index 0000000000..75c30fec3f Binary files /dev/null and b/solutions/search/agent-builder/images/new-agent-button.png differ diff --git a/solutions/search/agent-builder/images/save-and-chat-buttons.png b/solutions/search/agent-builder/images/save-and-chat-buttons.png new file mode 100644 index 0000000000..574812f2e3 Binary files /dev/null and b/solutions/search/agent-builder/images/save-and-chat-buttons.png differ diff --git a/solutions/search/agent-builder/kibana-api.md b/solutions/search/agent-builder/kibana-api.md new file mode 100644 index 0000000000..65dd7993ff --- /dev/null +++ b/solutions/search/agent-builder/kibana-api.md @@ -0,0 +1,161 @@ +--- +navigation_title: "Kibana APIs" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +WIP + +These pages are hidden from the docs TOC and have `noindexed` meta headers. +::: + +# 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/). + +## Using the APIs + +The examples in this documentation use Dev Tools [Console](/explore-analyze/query-filter/tools/console.md) syntax. +```console +GET kbn://api/agent_builder/tools +``` + +To use these APIs with tools like `curl`, replace the `kbn://` protocol with your Kibana URL. + + +```bash +curl -X GET "https:///api/agent_builder/tools" \ + -H "Authorization: ApiKey " +``` +:::{tip} +To generate API keys, search for `API keys` in the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md). +[Learn more](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 +: ```console + GET kbn://api/agent_builder/tools + ``` + +Create a tool +: ```console + POST kbn://api/agent_builder/tools + ``` + +Get a tool by ID +: ```console + GET kbn://api/agent_builder/tools/{id} + ``` + +Delete a tool by ID +: ```console + DELETE kbn://api/agent_builder/tools/{id} + ``` + +Update a tool by ID +: ```console + PUT kbn://api/agent_builder/tools/{toolId} + ``` + +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 + +Refer to [](a2a-server.md) for more information. + +Get A2A agent card configuration +: ```console + GET kbn://api/agent_builder/a2a/{agentId}.json + ``` + +Execute A2A agent task +: ```console + POST kbn://api/agent_builder/a2a/{agentId} + ``` + diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md new file mode 100644 index 0000000000..2cf4ce3827 --- /dev/null +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -0,0 +1,62 @@ +--- +navigation_title: "Limitations & known issues" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +WIP + +These pages are hidden from the docs TOC and have `noindexed` meta headers. +::: + +# Limitations and known issues in {{agent-builder}} + +## Model selection + +Initally, {{agent-builder}} only supports working with the [Elastic Managed LLM](kibana://reference/connectors-kibana/elastic-managed-llm.md) running on the Elastic Inference Service which uses Claude Sonnet 3.7, on {{ech}} and {{serverless-full}}. + +Locally this picks the first AI connector available. + +This can be changed under Stack Management -> AI -> GenAI Settings -> Default AI Connector. + +## Known issues + + +- **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. + + \ No newline at end of file diff --git a/solutions/search/agent-builder/mcp-server.md b/solutions/search/agent-builder/mcp-server.md new file mode 100644 index 0000000000..fd0f408073 --- /dev/null +++ b/solutions/search/agent-builder/mcp-server.md @@ -0,0 +1,48 @@ +--- +navigation_title: "MCP server" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +# MCP server + +:::{warning} +WIP + +These pages are hidden from the docs TOC and have `noindexed` meta headers. +::: + +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. + +## MCP server endpoint + +The MCP server is available at: + +``` +{KIBANA_URL}/api/agent_builder/mcp +``` + +## 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: + +```json +{ + "mcpServers": { + "elastic-agent-builder": { + "command": "npx", + "args": ["@elastic/agent-builder-mcp"], + "env": { + "KIBANA_URL": "", + "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). +::: diff --git a/solutions/search/agent-builder/programmatic-access.md b/solutions/search/agent-builder/programmatic-access.md new file mode 100644 index 0000000000..ca9c9a5232 --- /dev/null +++ b/solutions/search/agent-builder/programmatic-access.md @@ -0,0 +1,24 @@ +--- +navigation_title: "Programmatic access" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +WIP + +These pages are hidden from the docs TOC and have `noindexed` meta headers. +::: + +# Work programmatically with {{agent-builder}} + +{{agent-builder}} provides comprehensive APIs and additional integration options for programmatic access and automation. + +These interfaces enable you to build integrations with other applications and extend Agent Builder's capabilities to fit your specific requirements. + +- **[Kibana API](kibana-api.md)**: RESTful APIs for working with {{agent-builder}} programmatically +- **[MCP server](mcp-server.md)**: A standardized interface that allows external MCP clients (such as Claude Desktop or Cursor) to access {{agent-builder}} tools +- **[A2A server](a2a-server.md)**: Agent-to-agent communication endpoints that follow the A2A protocol specification, enabling external A2A clients to interact with {{agent-builder}} agents + diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md new file mode 100644 index 0000000000..ac1238e155 --- /dev/null +++ b/solutions/search/agent-builder/tools.md @@ -0,0 +1,212 @@ +--- +navigation_title: "Tools" +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview +--- + +:::{warning} +WIP + +These pages are hidden from the docs TOC and have `noindexed` meta headers. +::: + +# Tools in {{agent-builder}} + +Agents 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. + +## How agents use tools + +Tools enable agents to work with {{es}} data. When an agent receives a natural language query, it does the following: + +1. Analyzes the semantic intent of the request +2. Selects appropriate tools from its available toolset +3. Maps the request parameters to tool input parameters +4. Executes the tools in sequence as needed +5. Processes the structured output data + +Each tool is an atomic operation with a defined signature - accepting typed parameters and returning structured results in a format the agent can parse, transform, and incorporate into its response generation. + +## Built-in tools + +{{agent-builder}} ships with a comprehensive set of built-in tools that provide core capabilities for working with your {{es}} data. These tools are ready to use. They cannot be modified or deleted. + +Key built-in tools include: + +- **`.execute_esql`**: Executes an {{esql}} query and returns the results in a tabular format +- **`.generate_esql`**: Generates an {{esql}} query from a natural language query +- **`.get_document_by_id`**: Retrieves the full content of an {{es}} document based on its ID and index name +- **`.get_index_mapping`**: Retrieves mappings for the specified index or indices +- **`.index_explorer`**: Lists relevant indices and corresponding mappings based on a natural language query +- **`.list_indices`**: Lists the indices in the {{es}} cluster the current user has access to +- **`.search`**: A powerful tool for searching and analyzing data within a specific {{es}} index + +Built-in tools serve as building blocks for more complex interactions and provide the foundation for agent capabilities. + +## 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: + +- **Scoped tools**: Define tools that are scoped to a specific index or pattern, allowing the LLM to decide how to query those indices based on the user's request +- **Explicit query tools**: Define tools with explicit {{esql}} queries for precise, pre-defined data retrieval operations + +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 + +Parameters enable tools to be dynamic and adaptable to different queries. Each parameter has: + +- A **name** that identifies it +- 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. + +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 + +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. + +### Use the UI + +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 + - **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 + +### Testing your tools + +After creating a tool, test it before assigning it to agents: + +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 + +Testing helps ensure your tool returns useful results and handles parameters correctly. + + +### Best practices + +1. **Write descriptive names**: Use clear, action-oriented names +2. **Provide detailed descriptions**: Explain when and how the tool should be used +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 +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 + +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 + +## Manage tools + +### List available tools + +Access the complete list of available tools from the Tools page in Kibana. This view shows: +- Tool names and descriptions +- Tool types +- Associated tags +- Actions (edit, delete, test) + +### Assign tools to agents + +Tools must be assigned to agents before they can be used: +1. Navigate to the agent configuration page +2. Select the **Tools** tab +3. Add the desired tools to the agent +4. Save the agent configuration + +### Update and delete tools + +Custom tools can be modified or removed as needed: +1. From the Tools page, find the tool you want to modify +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 diff --git a/solutions/search/elastic-agent-builder.md b/solutions/search/elastic-agent-builder.md new file mode 100644 index 0000000000..f51ba17033 --- /dev/null +++ b/solutions/search/elastic-agent-builder.md @@ -0,0 +1,63 @@ +--- +navigation_title: "Agent Builder" +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-builder}} is an AI-powered conversation framework for working with {{es}} data using natural language. It features both a chat UI for synchronous interaction and extensive programmatic access through APIs, MCP and A2A servers. + +## Key capabilities + +- **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. +- **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. + +### 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. + +[**Learn more about Agent Chat**](agent-builder/chat.md) + +### Agents + +Agents are powered by custom LLM instructions and the ability to use tools to answer questions, take action, or support workflows. Each agent translates natural language requests into specific actions using the tools assigned to it. + +[**Learn more about agents**](agent-builder/agent-builder-agents.md) + +### Tools [tools-concept] + +Tools are modular, reusable functions that agents use to search, retrieve, and manipulate {{es}} data. Tools are the primary mechanism for connecting agent capabilities to your data. + +[**Learn more about tools**](agent-builder/tools.md) + +## Programmatic interfaces + +{{agent-builder}} provides APIs and LLM integration options for programmatic access and automation. +These interfaces enable you to build integrations with other applications and extend {{agent-builder}}'s capabilities to fit your specific requirements. + +[**Learn more about programmatic access**](agent-builder/programmatic-access.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) + diff --git a/solutions/toc.yml b/solutions/toc.yml index d7e204f1b1..311bdd4f0f 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -45,6 +45,16 @@ toc: - file: search/semantic-search/semantic-search-elser-ingest-pipelines.md - file: search/semantic-search/cohere-es.md - file: search/using-openai-compatible-models.md + - hidden: search/elastic-agent-builder.md + - hidden: search/agent-builder/get-started.md + - hidden: search/agent-builder/chat.md + - hidden: search/agent-builder/agent-builder-agents.md + - hidden: search/agent-builder/tools.md + - hidden: search/agent-builder/programmatic-access.md + - hidden: search/agent-builder/kibana-api.md + - hidden: search/agent-builder/mcp-server.md + - hidden: search/agent-builder/a2a-server.md + - hidden: search/agent-builder/limitations-known-issues.md - file: search/rag.md children: - file: search/rag/playground.md