Loading

Permissions and access control in Elastic Agent Builder

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.

Admonition

This feature requires the appropriate Elastic Stack subscription or Serverless project feature tier.

Elastic Agent Builder requires privileges at three levels:

Elastic Agent Builder access control is managed by the agentBuilder Kibana feature. Assign either Read or All based on what users need to do.

Required to use agents, send chat messages, view tools, and access conversations.

Instead of All, you can pair Read with individual sub-features for more granular control over what users can manage:

  • Manage agents: Create, update, or delete custom agents.
  • Manage tools: Create, update, or delete custom tools.

The broadest access level. Grants everything in Read, plus the ability to create, update, or delete custom agents and tools. Includes both management sub-features by default.

Required to use agents, send chat messages, view tools, and access conversations.

The broadest access level. Grants everything in Read, plus the ability to create, update, or delete custom agents and tools.

Note

If the agent uses AI connectors, also grant Read access to the Actions and Connectors feature.

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

Note

When configuring roles in the Kibana UI, Elastic Agent Builder privileges are currently located under the Analytics section, not the Elasticsearch section.

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"]
    }
  ]
}
  1. For read-only access, use feature_agentBuilder.read instead of feature_agentBuilder.all. Learn more.
Note

For granular access, pair feature_agentBuilder.read with only the sub-feature privileges needed. To learn more, refer to Kibana privileges.

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:

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.

Important

When accessing Elastic Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: https://<deployment>/s/<space-name>/api/agent_builder/...

The default space uses the standard URL format without /s/<space-name>.

Learn more about Kibana Spaces.