Loading

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.

Follow these steps to create a new custom 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 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. 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

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. Built-in agents like the Elastic AI Agent can only be chatted with or cloned, not edited or deleted.

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.