---
title: Elastic Agent Builder: Agents
description: Agents are AI models (LLMs) defined with custom instructions and a set of assigned tools. Users chat with agents using natural language, in the Agent...
url: https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/agent-builder-agents
applies_to:
  - Serverless Elasticsearch projects: Preview
  - Serverless Observability projects: Unavailable
  - Serverless Security projects: Unavailable
  - Elastic Stack: Preview since 9.2
---

# Elastic Agent Builder: Agents
Agents are AI models (LLMs) defined with custom instructions and a set of assigned [tools](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/tools). Users [chat](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/chat) with agents using natural language, in the Agent Builder UI or programmatically.
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 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.
<note>
  The process of tool selection, execution, and analysis consumes tokens. To understand how usage is calculated, refer to [Token usage in Elastic Agent Builder](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/monitor-usage).
</note>

Elastic 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.
</note>


## 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. The default agent cannot be edited directly.
  ![Chat with agent and clone agent buttons](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/images/chat-and-clone-buttons.png)
- **Custom agents**: You can **chat**, **edit**, **clone**, or **delete** an agent from the management overview.
  ![Agent context menu showing Chat, Edit, Clone, and Delete options](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/images/chat-edit-clone-delete.png)


## Create a new agent in the GUI

Follow these steps to create a new agent:
<stepper>
  <step title="Navigate to the Agents page">
    Navigate to the **Agents** page to access the agent management interface.
  </step>

  <step title="Create a new agent">
    Select the **New agent** button to being creating a new agent.
    ![Select the New agent button to create a new agent](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/images/new-agent-button.png)
  </step>

  <step title="Configure essential settings">
    Configure the essential agent settings in the **settings** tab:
    1. Enter an **Agent ID**, a unique identifier for reference in code.
    2. Add **Custom instructions**.Custom instructions define the agent's personality and determine how it interacts with users and performs tasks.
       <note>
       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.
       </note>
    3. Set the **Display name** for users.
    4. Add a **Display description** to explain the agent's purpose.
  </step>

  <step title="Assign tools">
    Switch to the **Tools** tab to assign [tools](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/tools) to your agent.Select the combination of built-in and custom tools available to the agent, based on your use case.
  </step>

  <step title="Customize appearance (optional)">
    Optionally customize the agent's appearance and organization:
    - Add **Labels** to organize your agents.
    - Select an **Avatar color** and **Avatar symbol** to help visually distinguish the agent.
  </step>

  <step title="Save your changes">
    Select **Save** to create your agent, or **Save and chat** to create the agent and immediately begin a conversation with it.
    ![Save and Save and chat buttons](https://www.elastic.co/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/images/save-and-chat-buttons.png)
  </step>
</stepper>


## Agents API

The Agents API enables programmatic access to agent creation and management actions.

### Quick overview

For an overview, refer to [Agents API](/elastic/docs-builder/docs/2472/explore-analyze/ai-features/agent-builder/kibana-api#agents).

### API reference

For the complete API reference, refer to the [Kibana API reference](https://www.elastic.co/docs/api/doc/kibana/operation/operation-get-agent-builder-agents).