Permissions and access control in Elastic Agent Builder

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

Use this page to learn how to configure security roles and API keys for Elastic Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query.

Elastic Agent Builder requires privileges at three levels:

• Kibana feature access
• Elasticsearch cluster access
• Elasticsearch index access

Elastic Agent Builder access control is managed by the agentBuilder Kibana feature:

• "Read" access to the agentBuilder feature: Required to use agents, send chat messages, view tools, and access conversations.
• "All" access to the agentBuilder feature: Required to create, update, or delete custom agents and tools.
• "Read" access to the "Actions and Connectors" feature: Required to use AI connectors with agents.

Learn more about Kibana privileges.

Elastic Agent Builder requires cluster-level privileges for AI-powered query generation:

• monitor_inference: Required when the agent uses an AI connector that calls the Elasticsearch Inference API (such as the Elastic default LLM or other AI connectors configured to use the Inference API). The built-in tools search and generate_esql, as well as index search tools, use this API to generate queries from natural language. This privilege is not required when the agent uses other Kibana GenAI connectors.

Learn more about cluster privileges.

Tools execute queries against Elasticsearch indices as the current user. Required privileges depend on which indices the tools access:

• read: Required for tools that query data.
• view_index_metadata: Required for tools that inspect index structure. Also required for the built-in search tool and index search tools, which may use index exploration capabilities internally.

Learn more about index privileges.

You can grant users access to Elastic Agent Builder using these methods:

• Roles to bundle privileges for users.
• API keys for programmatic access.
• Spaces to scope access to specific environments.

Roles are Elasticsearch security constructs that bundle together Kibana feature privileges and Elasticsearch privileges. To grant users access to Elastic Agent Builder, create a role that includes the required privileges.

Example role for users who need full Elastic Agent Builder access:

POST /_security/role/agent-builder-full
{
  "cluster": ["monitor_inference"],
  "indices": [
    {
      "names": ["logs-*", "metrics-*"],
      "privileges": ["read", "view_index_metadata"]
    }
  ],
  "applications": [
    {
      "application": "kibana-.kibana",
      "privileges": [
        "feature_agentBuilder.all",
        "feature_actions.read"
      ],
      "resources": ["space:default"]
    }
  ]
}
		

When using the Elastic Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges.

Unlike roles, which use UI-friendly feature privilege names like feature_agentBuilder.all, API keys use the underlying API privilege names (read_onechat, manage_onechat). This is because API keys interact directly with the Kibana API layer rather than through the UI.

Refer to these pages for API key configuration examples:

• MCP server
• Kibana API

Learn more about API keys.

Elastic Agent Builder respects Kibana Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space.

When configuring roles or API keys, specify the Space in the application privileges resources (e.g., "resources": ["space:production"]). Users and API keys cannot access resources in other Spaces.

Learn how to Copy your MCP server URL.

Learn more about Kibana Spaces.