Create an agent

Base URL: https://{kibana_url}

POST /api/agent_builder/agents
POST /s/{space_id}/api/agent_builder/agents

Refer to 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.

Required authorization

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Header parameters

Request body

access_control object
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.
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

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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 Shell

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

Request Console 1 / 2 languages

Example request for creating a custom agent with special prompt and tools

Console Kibana Dev Tools

POST kbn:/api/agent_builder/agents
{
  "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"
}

Generated from the API spec

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/agents" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Generated from the API spec

Response

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

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

Required authorization

Authentication

Header parameters

Request body { }

Response

Request body