Loading

Create and manage custom agents in Elastic Agent Builder

Custom agents enable you to create specialized AI assistants tailored to your specific use cases and workflows. Unlike built-in agents, which are pre-configured by Elastic, custom agents give you full control over instructions, tools, and behavior.

Note

Built-in agents are immutable and cannot be edited. To customize agent behavior, you need to create a custom agent by cloning an agent or creating a new one from scratch. The Elastic AI Agent is an exception : as the default agent for each space, it can be edited directly.

Custom agents are space-aware: they are only available in the Kibana space where they were created. In contrast, built-in agents are available across all spaces.

Agent skill available

A skill is available to help AI agents with this topic.

Learn more about agent skills for Elastic

Get the skill

Follow these steps to create a new custom agent:

  1. Navigate to the Agents page

    Select Manage components at the bottom of the left sidebar, then select Agents.

    Tip

    You can also reach this page from the agent selector: open the selector in the left sidebar and select New Agent.

    Navigate to Agents in the main navigation.

  2. Create a new agent

    Select the New agent button to begin 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. Enable Elastic capabilities

    Use the Enable Elastic Capabilities toggle to activate built-in Elastic tools and skills for your agent. This toggle is disabled by default.

    For more information, refer to Enable Elastic Capabilities.

  5. Set visibility

    Configure the Visibility for your agent in the Organization section. Visibility controls who can view and edit the agent. The default setting is Public.

    For more information, refer to Visibility settings.

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

  7. Assign skills (optional)

    Switch to the Skills tab to assign skills to your agent. Skills are reusable instruction sets that give the agent specialized expertise for particular types of tasks.

    You can assign skills that already exist in your deployment's skill library—you create and manage those from Manage components > Skills—or you can create new skills inline from this tab. For an overview of skills, built-in versus custom skills, and APIs, refer to Skills in Elastic Agent Builder.

  8. Assign plugins (optional)

    Switch to the Plugins tab to assign plugins to your agent. Plugins extend agents with additional skills and capabilities. Before you can assign a plugin, it must first be installed from the global Plugins page in Manage components.

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

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

From the Agents page, you can perform various actions on custom agents:

  • Chat: Start a conversation with the agent.
  • Edit: Modify the agent's settings, instructions, tools, or appearance.
  • Clone: Create a copy of the agent as a starting point for a new agent.
  • Delete: Remove the agent from your workspace.
Agent context menu showing Chat, Edit, Clone, and Delete options
Note

These management options apply only to custom agents and the Elastic AI Agent . Other built-in agents can only be chatted with or cloned, not edited or deleted.

Control who can view and edit your agent by configuring its visibility. To change visibility, edit the agent and scroll to the Organization section.

Public
Anyone can view and edit.
Shared
Anyone can view. Only the owner or an administrator can edit.
Private
Only the owner or an administrator can view and edit.
Agent visibility dropdown showing Public, Shared, and Private.

When the Enable Elastic Capabilities toggle is enabled, it automatically assigns all current and future Elastic-built skills, plugins, and tools to the agent. The set of assigned capabilities is dynamic and grows as Elastic adds new built-in content.

To review which skills and tools are active, open the agent's Skills or Tools tab after enabling the toggle. Elastic-provided items are marked with a lock icon.

Disable this toggle to manage skill, plugin, and tool assignments manually.

Enable Elastic Capabilities toggle ON

When creating custom agents, follow these best practices to ensure optimal performance and usability:

  1. Be specific and clear: Write instructions that clearly define the agent's role and capabilities.
  2. Define boundaries: Specify what the agent should and shouldn't do to prevent unexpected behavior.
  3. Include examples: Provide examples of how the agent should respond to common queries.
  4. Keep it focused: Agents with narrow, well-defined purposes typically perform better than generalist agents.
  1. Assign relevant tools only: Limit tools to those directly related to the agent's purpose.
  2. Fewer is better: Too many tools can confuse the agent's decision-making process.
  3. Test tool combinations: Verify that the selected tools work well together for your use case.
  1. Use descriptive names: Choose names that clearly convey the agent's purpose.
  2. Write meaningful descriptions: Help users understand when to use each agent.
  3. Apply labels consistently: Use labels to organize agents by team, use case, or department.
  4. Choose distinctive avatars: Select unique colors and symbols to make agents easily recognizable.
  1. Test thoroughly: Verify the agent works correctly with various queries before deploying.
  2. Iterate based on feedback: Refine instructions and tool assignments based on actual usage.
  3. Monitor performance: Track how well the agent addresses user needs and adjust as necessary.

The Agents API enables programmatic management of custom agents.

For an overview of agent API operations, refer to Agents API.

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