---
title: "Create an agent"
method: POST
path: "/api/agent_builder/agents"
tags: ["agent builder"]
---

# Create an agent

`POST /api/agent_builder/agents`

**Spaces method and path for this operation:**

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/agent_builder/agents</span></div>

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

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.

## Headers

- `kbn-xsrf` string, required

## Request body

- object
  - `access_control` object
    - `access_mode` 'public' | 'shared' | 'private', 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).
  - `avatar_color` string — Optional hex color code for the agent avatar.
  - `avatar_symbol` string — Optional symbol/initials for the agent avatar.
  - `configuration` object, required — Configuration settings for the agent.
    - `ai_indices` string[] — Array of AI indices to associate with the agent.
    - `connector_ids` string[] — Array of connector IDs to associate with the agent.
    - `enable_elastic_capabilities` boolean — When true, enables built-in Elastic capabilities for the agent.
    - `instructions` string — Optional system instructions that define the agent behavior.
    - `plugin_ids` string[] — Array of plugin IDs to assign to the agent.
    - `skill_ids` string[] — Array of skill IDs to be available to the agent.
    - `tools` object[], required
      - `tool_ids` string[], required — Array of tool IDs that the agent can use.
    - `workflow_ids` string[]
  - `description` string, required — Description of what the agent does.
  - `id` string, required — Unique identifier for the agent.
  - `labels` string[] — Optional labels for categorizing and organizing agents.
  - `name` string, required — Display name for the agent.

## Response `200`

Indicates a successful response

---

[API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/versions/531c9e2a7d23/schema)