---
title: Create and manage custom agents in Elastic Agent Builder
description: Learn how to create and manage custom agents in Agent Builder. Define custom instructions, assign tools, and iterate on agent behavior for specific workflows.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/custom-agents
products:
  - Elastic Cloud Serverless
  - Elastic Observability
  - Elastic Security
  - Elasticsearch
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3, Preview in 9.2
---

# 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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/builtin-agents-reference), 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 <applies-to>Elastic Stack: Generally available since 9.4</applies-to>: as the default agent for each space, it can be edited directly.
</note>

Custom agents are space-aware: they are only available in the [Kibana space](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/deploy-manage/manage-spaces) where they were created. In contrast, built-in agents are available across all spaces.
<agent-skill url="https://github.com/elastic/agent-skills/tree/main/skills/kibana/agent-builder">
  A skill is available to help AI agents with this topic.
</agent-skill>


## Create a custom agent

Follow these steps to create a new custom agent:
<stepper>
  <step title="Navigate to the Agents page">
    <applies-switch>
      <applies-item title="{ stack: ga 9.4+, serverless: ga }" applies-to="Elastic Cloud Serverless: Generally available, Elastic Stack: Generally available since 9.4">
        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**.
        </tip>
      </applies-item>

      <applies-item title="{ stack: ga =9.3 }" applies-to="Elastic Stack: Generally available in 9.3">
        Navigate to **Agents** in the main navigation.
      </applies-item>
    </applies-switch>
  </step>

  <step title="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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/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="Enable Elastic capabilities (optional)">
    <applies-to>
      - Elastic Stack: Generally available since 9.4
    </applies-to>
    Optionally enable the **Enable Elastic capabilities** toggle to automatically assign all Elastic-built [tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference), [skills](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/builtin-skills-reference), and plugins to your agent. This toggle is disabled by default for custom agents.For more information, refer to [Elastic capabilities](/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/agent-builder-agents#elastic-capabilities).
  </step>

  <step title="Configure pre-execution workflows (optional)">
    <applies-to>
      - Elastic Stack: Generally available since 9.4
    </applies-to>
    Administrators can assign workflows that run once after each user message, before the agent makes any LLM calls in response. Use pre-execution workflows to prepare prompt context or stop an agent run before the LLM starts.For details, refer to [Pre-execution workflows](/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/agents-and-workflows#pre-execution-workflows).
  </step>

  <step title="Set access control">
    <applies-to>
      - Elastic Cloud Serverless: Generally available
      - Elastic Stack: Generally available since 9.4
    </applies-to>
    Configure **Access control** for your agent in the **Organization** section. Access control determines who can view and edit the agent.<applies-to>Elastic Stack: Generally available in 9.4</applies-to> This setting is labeled **Visibility**.New agents get one of these levels by default:
    - <applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> **Private**: only you and administrators can view and edit the agent until you grant access to someone else.
    - <applies-to>Elastic Stack: Generally available from 9.4 to 9.5</applies-to> **Public**: anyone in the space can view and edit the agent.
    For more information, refer to [Access control settings](#access-control-settings). You can also configure [per-agent access controls](#per-agent-access-controls) for more granular control.
  </step>

  <step title="Assign tools">
    Switch to the **Tools** tab to assign [tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/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="Assign skills (optional)">
    <applies-to>
      - Elastic Stack: Generally available since 9.4
    </applies-to>
    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**](/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/chat#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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/skills).
  </step>

  <step title="Assign plugins (optional)">
    <applies-to>
      - Elastic Cloud Serverless: Preview
      - Elastic Stack: Preview since 9.4
    </applies-to>
    Switch to the **Plugins** tab to assign plugins to your agent. Each plugin bundles a set of related skills into a single install. Before you can assign a plugin, install it from the global **Plugins** page in **Manage components**.
    For more information, refer to [Plugins in Elastic Agent Builder](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/plugins).
    <note>
      The **Plugins** option is hidden until you turn on the `agentBuilder:experimentalFeatures` [advanced setting](/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/get-started#enable-experimental-features-optional) in Kibana.
    </note>
  </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://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/images/save-and-chat-buttons.png)
  </step>
</stepper>


## Manage custom agents

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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/images/chat-edit-clone-delete.png)

<note>
  These management options apply only to custom agents and the Elastic AI Agent <applies-to>Elastic Stack: Generally available since 9.4</applies-to>. Other built-in agents can only be chatted with or cloned, not edited or deleted.
</note>


## Access control settings

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.4
</applies-to>

Control who can view and edit your agent by configuring its access control level. To change the level, edit the agent and go to the **Organization** section.
<applies-to>Elastic Stack: Generally available in 9.4</applies-to> This setting is labeled **Visibility**.
Throughout this section, the owner is the user who created the agent, and an administrator is a user whose role grants wildcard (`*`) privileges, such as the built-in `superuser` role. Elastic Agent Builder privileges alone, including the privilege to manage agents in a space, don't make a user an administrator.
Every agent has one of three access control levels:
<definitions>
  <definition term="Public">
    Anyone can view and edit.
  </definition>
  <definition term="Shared">
    Anyone can view. Only the owner or an administrator can edit.
    <applies-to>Elastic Stack: Generally available since 9.5</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> People you grant access to can also edit.
  </definition>
  <definition term="Private">
    Only the owner or an administrator can view and edit.
    <applies-to>Elastic Stack: Generally available since 9.5</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> People you grant access to can also view it, and edit it if you give them **Editor** or **Manager**.
  </definition>
</definitions>

![The open Access control menu with Private selected, beside a panel describing each level.](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/images/agent-access-control-levels.png)

Whatever the level, only the owner or an administrator can change it. For everyone else, the setting is read-only.
<applies-to>Elastic Stack: Generally available since 9.5</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> A user you give **Manager** access can also change the level.
Who can delete an agent:
- <applies-to>Elastic Stack: Generally available since 9.5</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> The owner, an administrator, or a user you give **Manager** access. Being able to edit a **Public** agent doesn't include deleting it.
- <applies-to>Elastic Stack: Generally available in 9.4</applies-to> Anyone who can edit the agent, which on a **Public** agent means anyone.

To grant access to individual users, refer to [Per-agent access controls](#per-agent-access-controls).
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> The new default applies to new agents only. Agents that already exist keep the level they have, and agents created before access control existed are **Public**.
Most built-in agents don't have an access control level at all. They're always available to everyone who can use Elastic Agent Builder. The **Elastic AI Agent** is the exception: it does have a level, which is always **Public** and can't be changed, even by an administrator.

### Per-agent access controls

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.5
</applies-to>

In addition to the three access control levels, you can grant individual users access to a specific agent. Use this when the agent's access control level is too broad or too narrow for a particular person.
To configure per-agent access controls:
1. Edit the agent and go to the **Organization** section. You can also select **Manage access** for the agent on the **Agents** page.
2. Select an access control level.
3. Add individual users and assign each one an access level.

Each user you add gets one of three access levels. These are separate from the agent's access control level, which applies to everyone in the space:
<definitions>
  <definition term="User">
    Can find, view, and run the agent.
  </definition>
  <definition term="Editor">
    Everything a **User** can do, plus editing the agent's configuration.
  </definition>
  <definition term="Manager">
    Everything an **Editor** can do, plus deleting the agent and managing who has access to it.
  </definition>
</definitions>

Adding a user can only increase their access, never reduce it: they get whichever grants more, the level you assign or the agent's access control level. For example, you can set an agent to **Private** and then give one colleague **Editor** access.
You can grant per-agent access at any access control level, including **Public**. What changes is which levels you can assign: on **Public** and **Shared** agents, **User** isn't offered, because anyone in the space can already find and run the agent.

## Best practices for custom agents

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

### Instructions

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.


### Tool selection

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.


### Naming and organization

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.


### Testing and iteration

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.


## Agents API

The Agents API enables programmatic management of custom agents.
For an overview of agent API operations, refer to [Agents API](/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/kibana-api#agents-apis).
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).

## Related pages

- [Agents overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/agent-builder-agents)
- [Best practices for prompt engineering in Elastic Agent Builder](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/prompt-engineering)
- [Built-in agents reference](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/builtin-agents-reference)
- [Tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/tools)
- [Skills in Elastic Agent Builder](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/skills)
- [Skill creation guidelines](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/skill-creation-guidelines)
- [Plugins in Elastic Agent Builder](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/plugins)
- [Connectors in Elastic Agent Builder](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8232/explore-analyze/ai-features/agent-builder/connectors)