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.

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. Assign either Read or All based on what users need to do.

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.

Elastic Agent Builder can collect agent traces into your Elasticsearch deployment. Trace data is stored in the traces-agent_builder.otel-* data stream. To read it, a role needs read and view_index_metadata on that pattern.

Access is granted at the index level. Any user who can read these data streams can read all collected traces, so trace access is not scoped per user. To control who can read traces, configure index privileges through roles in Stack Management → Roles.

The Kibana privileges described above control who can use Elastic Agent Builder at all. Individual conversations have a second layer of access control on top of that, so the owner of a conversation can decide who else can read it.

Conversations are private by default. Only the user who created a conversation, its owner, can see it.

An owner can put a conversation into one of two access modes:

• private: only the owner and the users listed as members can read and continue the conversation. This is the default.
• public: any user who can access the conversation's agent can read and continue it. Public conversations also appear in those users' conversation lists.

Members apply to private conversations only. A public conversation cannot have members.

A conversation belongs to the Kibana space it was created in. Sharing does not make it visible from another space.

Users you share a conversation with are added as members. member is the only available role. It grants two things:

• Read the conversation, including its full history.
• Continue the conversation by sending new messages.

Members cannot rename the conversation, delete it, or change who it is shared with.

You can share with individual users only. Granting access to an Elasticsearch role is not supported.

Members are identified by their Kibana user profile ID, not by username. A user who has never logged in to Kibana has no profile and cannot be added.

A user with full cluster privileges, such as a superuser, can also rename or delete a public conversation they do not own. This does not extend to private conversations, even ones shared with them, and it never includes changing who a conversation is shared with.

Sharing a conversation grants access to that conversation only. It does not grant any privilege the user does not already have.

A member still needs:

• The agentBuilder Kibana Read privilege.
• Access to the agent the conversation uses.
• Access to the space the conversation belongs to.

Access to the agent is checked every time a conversation is read, and this applies to the owner as well. If anyone loses access to a conversation's agent, or the agent is deleted, the conversation stops being readable for them and disappears from their conversation list.

Managing sharing needs only the Read privilege plus ownership. There is no separate sharing privilege, and no write privilege is involved.

When a user cannot access a conversation, Elastic Agent Builder reports it as not found rather than as a permissions error. This is deliberate, so that users cannot detect the existence of conversations they cannot read.

To share a conversation, use the Kibana API.

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"]
    }
  ]
}
		

1. For read-only access, use feature_agentBuilder.read instead of feature_agentBuilder.all. Learn more.

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. Conversations, custom agents, and custom tools are scoped to the current space. Built-in agents are space-agnostic and are available in all spaces. The default Elastic AI Agent is an exception : it is a standard persisted agent that is space-aware and automatically created per space.

When configuring roles or API keys, specify the space in the application privileges resources (for example, "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.