---
type: api
title: Create an agent
description: Create a new agent. Use this endpoint to define the agent's behavior, appearance, and capabilities through comprehensive configuration options. To learn more about agents, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-post-agent-builder-agents
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-post-agent-builder-agents
products:
  - Kibana
---

# Create an agent

Availability: 9.2+

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/agent_builder/agents`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#basicauth)

## Description

Create a new agent. Use this endpoint to define the agent's behavior, appearance, and capabilities through comprehensive configuration options. To learn more about agents, refer to the [agents documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-agents).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.

## Request Body

`application/json`

- `access_control` (object) — optional
  - `access_mode` (enum) — required
    **Technical Preview; added in 9.4.0.** Access-control mode: `public` (any privileged user can read/write), `shared` (any privileged user can read, only owner can write), `private` (only owner can read/write). Agents created without an access-control mode default to `private`.
    Values: `public`, `shared`, `private`
- `avatar_color` (string) — optional
  Optional hex color code for the agent avatar.
- `avatar_symbol` (string) — optional
  Optional symbol/initials for the agent avatar.
- `configuration` (object) — required
  Configuration settings for the agent.
  - `ai_indices` ([] string · max: 100) — optional
    Array of AI indices to associate with the agent.
  - `connector_ids` ([] string · max: 100) — optional
    Array of connector IDs to associate with the agent.
  - `enable_elastic_capabilities` (boolean) — optional
    When true, enables built-in Elastic capabilities for the agent.
  - `instructions` (string) — optional
    Optional system instructions that define the agent behavior.
  - `plugin_ids` ([] string · max: 100) — optional
    Array of plugin IDs to assign to the agent.
  - `post_execution_workflow_ids` ([] string · max: 100) — optional
  - `skill_ids` ([] string · max: 100) — optional
    Array of skill IDs to be available to the agent.
  - `subagent_ids` ([] string · max: 50) — optional
    **Technical Preview; added in 9.6.0.** Allowlist of subagent IDs this agent may spawn. Missing or empty disables the `run_subagent` tool. Use '_self' to enable self-fork.
  - `tools` ([] object) — required
    - `tool_ids` ([] string) — required
      Array of tool IDs that the agent can use.
  - `workflow_ids` ([] string · max: 100) — optional
- `description` (string) — required
  Description of what the agent does.
- `id` (string) — required
  Unique identifier for the agent.
- `labels` ([] string) — optional
  Optional labels for categorizing and organizing agents.
- `name` (string) — required
  Display name for the agent.

## Response

Indicates a successful response

## Code Examples

#### Console

```console
POST kbn://api/agent_builder/agents
{
  "id": "new-agent-id",
  "name": "Search Index Helper",
  "description": "Hi! I can help you search the data within the indices starting with \"content-\" prefix.",
  "labels": ["custom-indices", "department-search"],
  "avatar_color": "#BFDBFF",
  "avatar_symbol": "SI",
  "configuration": {
    "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
    "tools": [
      {
        "tool_ids": [
          "platform.core.search",
          "platform.core.list_indices",
          "platform.core.get_index_mapping",
          "platform.core.get_document_by_id"
        ]
      }
    ]
  }
}
```

#### curl

```curl
curl \
  -X POST "${KIBANA_URL}/api/agent_builder/agents" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "new-agent-id",
    "name": "Search Index Helper",
    "description": "Hi! I can help you search the data within the indices starting with \"content-\" prefix.",
    "labels": ["custom-indices", "department-search"],
    "avatar_color": "#BFDBFF",
    "avatar_symbol": "SI",
    "configuration": {
      "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
      "tools": [
        {
          "tool_ids": [
            "platform.core.search",
            "platform.core.list_indices",
            "platform.core.get_index_mapping",
            "platform.core.get_document_by_id"
          ]
        }
      ]
    }
}'
```

## Response Examples

#### Create agent response

Example response returning the definition of an agent created as a result of the request

```json
{
  "avatar_color": "#BFDBFF",
  "avatar_symbol": "SI",
  "configuration": {
    "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \u0022content-\u0022.",
    "tools": [
      {
        "tool_ids": [
          "platform.core.search",
          "platform.core.list_indices",
          "platform.core.get_index_mapping",
          "platform.core.get_document_by_id"
        ]
      }
    ]
  },
  "description": "Hi! I can help you search the data within the indices starting with \u0022content-\u0022 prefix.",
  "id": "created-agent-id",
  "labels": [
    "custom-indices",
    "department-search"
  ],
  "name": "Search Index Helper",
  "type": "chat"
}
```