This is a cache of https://www.elastic.co/docs/solutions/search/agent-builder/agent-builder-agents. It is a snapshot of the page at 2025-10-31T00:30:46.801+0000.
Elastic Agent Builder: Agents | Elastic Docs
Loading

Elastic Agent Builder: Agents

Serverless Elasticsearch Preview Serverless Observability Unavailable Serverless Security Unavailable Stack Preview 9.2.0

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 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.

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.

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.

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
    • 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

Follow these steps to create a new agent:

  1. Navigate to the Agents page

    Navigate to the Agents page to access the agent management interface.

  2. 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

  3. 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.

    3. Set the Display name for users.

    4. Add a Display description to explain the agent's purpose.

  4. Assign tools

    Switch to the Tools tab to assign tools to your agent.

    Select the combination of built-in and custom tools available to the agent, based on your use case.

  5. 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.

  6. 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

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

For an overview, refer to Agents API.

For the complete API reference, refer to the Kibana API reference.