Elastic Stack (ELK Stack) agent builder API

openapi: 3.2.0
info:
  contact:
    name: Kibana Team
  description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.

    The API calls are stateless.

    Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the

    request.

    API requests return JSON output, which is a format that is machine-readable and works well for automation.


    To interact with Kibana APIs, use the following operations:


    - GET: Fetches the information.

    - PATCH: Applies partial modifications to the existing information.

    - POST: Adds new information.

    - PUT: Updates the existing information.

    - DELETE: Removes the information.


    You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.

    For example:


    ```

    GET kbn:/api/data_views

    ```


    For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).


    NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.


    ## Documentation source and versions


    This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.

    It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).


    This documentation contains work-in-progress information for future Elastic Stack releases.

    '
  title: Kibana agent builder API
  version: ''
  x-doc-license:
    name: Attribution-NonCommercial-NoDerivatives 4.0 International
    url: https://creativecommons.org/licenses/by-nc-nd/4.0/
  x-feedbackLink:
    label: Feedback
    url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: agent builder
  description: 'Agent Builder is a set of AI-powered capabilities for developing and interacting with agents that work with your Elasticsearch data.


    Most users will probably want to integrate with Agent Builder using MCP or A2A, but you can also work programmatically with tools, agents, and conversations using these Kibana APIs. Follow the [Agent Builder API tutorial](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-api-tutorial) for a guided example.


    **Elastic Agent Builder requires an Enterprise subscription.**

    '
  externalDocs:
    description: Agent Builder docs
    url: https://www.elastic.co/docs/solutions/search/agent-builder/programmatic-access
  x-displayName: Agent Builder
paths:
  /api/agent_builder/a2a/{agentId}:
    post:
      description: '**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/a2a/{agentId}</span></div>


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


        > warn

        > This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.

        To learn more about the Agent Builder A2A server, refer to the [A2A server documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/a2a-server).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
      operationId: post-agent-builder-a2a-agentid
      parameters:
      - description: The unique identifier of the agent to send the A2A task to.
        in: path
        name: agentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              a2aTaskRequestExample:
                description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.'
                value:
                  id: task-123
                  jsonrpc: '2.0'
                  method: complete
                  params:
                    messages:
                    - content: Hello from A2A protocol
                      role: user
            schema: {}
      responses:
        '200':
          content:
            application/json:
              examples:
                a2aTaskResponseExample:
                  description: Example response from A2A Task Endpoint with results of task execution
                  value:
                    id: task-123
                    jsonrpc: '2.0'
                    result:
                      conversation_id: conv-456
                      response:
                        message: Hello! How can I help you today?
                      type: response
          description: Indicates a successful response
      summary: Send A2A task
      tags:
      - agent builder
      x-state: Experimental; added in 9.2.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/agent_builder/a2a/{agentId}.json:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/agent_builder/a2a/{agentId}.json</span></div>


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


        Get agent discovery metadata in JSON format. Use this endpoint to provide agent information for A2A protocol integration and discovery. To learn more about the Agent Builder A2A server, refer to the [A2A server documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/a2a-server).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.'
      operationId: get-agent-builder-a2a-agentid.json
      parameters:
      - description: The unique identifier of the agent to get A2A metadata for.
        in: path
        name: agentId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                a2aAgentCardResponseExample:
                  description: Example response card of Elastic AI Agent
                  value:
                    capabilities:
                      pushNotifications: false
                      stateTransitionHistory: false
                      streaming: false
                    defaultInputModes:
                    - text/plain
                    defaultOutputModes:
                    - text/plain
                    description: Elastic AI Agent
                    name: Elastic AI Agent
                    protocolVersion: 0.3.0
                    provider:
                      organization: Elastic
                      url: https://elastic.co
                    securitySchemes:
                      authorization:
                        description: Authentication token
                        in: header
                        name: Authorization
                        type: apiKey
                    skills:
                    - description: A powerful tool for searching and analyzing data within your Elasticsearch cluster.
                      examples: []
                      id: platform.core.search
                      inputModes:
                      - text/plain
                      - application/json
                      name: platform.core.search
                      outputModes:
                      - text/plain
                      - application/json
                      tags:
                      - tool
                    supportsAuthenticatedExtendedCard: false
                    url: http://localhost:5601/api/agent_builder/a2a/elastic-ai-agent
                    version: 0.1.0
          description: Indicates a successful response
      summary: Get A2A agent card
      tags:
      - agent builder
      x-codeSamples:
      - lang: curl
        source: "curl \\\n  -X GET \"${KIBANA_URL}/api/agent_builder/a2a/{agentId}.json\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\"\n"
      - lang: Console
        source: 'GET kbn://api/agent_builder/a2a/{agentId}.json

          '
      x-state: Experimental; added in 9.2.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/agent_builder/agents:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</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.


        List all available agents. Use this endpoint to retrieve complete agent information including their current configuration and assigned tools. 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:read.'
      operationId: get-agent-builder-agents
      parameters: []
      responses:
        '200':
          content:
            application/json:
              examples:
                listAgentsResponseExample:
                  description: Example response that returns one built-in Elastic agent and one created by the user
                  value:
                    results:
                    - access_control: null
                      configuration:
                        tools:
                        - tool_ids:
                          - platform.core.search
                          - platform.core.list_indices
                          - platform.core.get_index_mapping
                          - platform.core.get_document_by_id
                      description: Elastic AI Agent
                      id: elastic-ai-agent
                      name: Elastic AI Agent
                      permissions:
                        update_access_control: false
                        update_agent: false
                      type: chat
                    - access_control:
                        access_mode: private
                        entries:
                        - name: alice
                          role: manager
                          type: user
                      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
                      description: Hi! I can help you search the data within the indices starting with "content-" prefix.
                      id: created-agent-id
                      labels:
                      - custom-indices
                      - department-search
                      name: Search Index Helper
                      permissions:
                        update_access_control: true
                        update_agent: true
                      type: chat
          description: Indicates a successful response
      summary: List agents
      tags:
      - agent builder
      x-codeSamples:
      - lang: curl
        source: "curl \\\n -X GET \"${KIBANA_URL}/api/agent_builder/agents\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n"
      - lang: Console
        source: 'GET kbn://api/agent_builder/agents

          '
      x-state: Added in 9.2.0
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: '**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.'
      operationId: post-agent-builder-agents
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            examples:
              createAgentRequestExample:
                description: Example request for creating a custom agent with special prompt and tools
                value:
                  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
                  description: Hi! I can help you search the data within the indices starting with "content-" prefix.
                  id: created-agent-id
                  labels:
                  - custom-indices
                  - department-search
                  name: Search Index Helper
            schema:
              additionalProperties: false
              type: object
              properties:
                access_control:
                  additionalProperties: false
                  type: object
                  properties:
                    access_mode:
                      description: '**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`.'
                      enum:
                      - public
                      - shared
                      - private
                      type: string
                  required:
                  - access_mode
                avatar_color:
                  description: Optional hex color code for the agent avatar.
                  type: string
                avatar_symbol:
                  description: Optional symbol/initials for the agent avatar.
                  type: string
                configuration:
                  additionalProperties: false
                  description: Configuration settings for the agent.
                  type: object
                  properties:
                    ai_indices:
                      description: Array of AI indices to associate with the agent.
                      items:
                        description: AI indices to associate with the agent.
                        maxLength: 256
                        type: string
                      maxItems: 100
                      type: array
                    connector_ids:
                      description: Array of connector IDs to associate with the agent.
                      items:
                        description: Connector ID to associate with the agent.
                        type: string
                      maxItems: 100
                      type: array
                    enable_elastic_capabilities:
                      description: When true, enables built-in Elastic capabilities for the agent.
                      type: boolean
                    instructions:
                      description: Optional system instructions that define the agent behavior.
                      type: string
                    plugin_ids:
                      description: Array of plugin IDs to assign to the agent.
                      items:
                        description: Plugin ID to assign to the agent.
                        type: string
                      maxItems: 100
                      type: array
                    skill_ids:
                      description: Array of skill IDs to be available to the agent.
                      items:
                        description: Skill ID to be available to the agent.
                        type: string
                      maxItems: 100
                      type: array
                    tools:
                      items:
                        additionalProperties: false
                        description: Tool selection configuration for the agent.
                        type: object
                        properties:
                          tool_ids:
                            description: Array of tool IDs that the agent can use.
                            items:
                              description: Tool ID to be available to the agent.
                              type: string
                            type: array
                        required:
                        - tool_ids
                      type: array
                    workflow_ids:
                      items:
                        description: Optional list of workflow IDs. When set, these workflows run before every agent execution, in order.
                        type: string
                      maxItems: 100
                      type: array
                  required:
                  - tools
                description:
                  description: Description of what the agent does.
                  type: string
                id:
                  description: Unique identifier for the agent.
                  type: string
                labels:
                  description: Optional labels for categorizing and organizing agents.
                  items:
                    description: Label for categorizing the agent.
                    type: string
                  type: array
                name:
                  description: Display name for the agent.
                  type: string
              required:
              - id
              - name
              - description
              - configuration
      responses:
        '200':
          content:
            application/json:
              examples:
                createAgentResponseExample:
                  description: Example response returning the definition of an agent created as a result of the request
                  value:
                    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
                    description: Hi! I can help you search the data within the indices starting with "content-" prefix.
                    id: created-agent-id
                    labels:
                    - custom-indices
                    - department-search
                    name: Search Index Helper
                    type: chat
          description: Indicates a successful response
      summary: Create an agent
      tags:
      - agent builder
      x-codeSamples:
      - lang: curl
        source: "curl \\\n  -X POST \"${KIBANA_URL}/api/agent_builder/agents\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\" \\\n  -H \"kbn-xsrf: true\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"id\": \"new-agent-id\",\n    \"name\": \"Search Index Helper\",\n    \"description\": \"Hi! I can help you search the data within the indices starting with \\\"content-\\\" prefix.\",\n    \"labels\": [\"custom-indices\", \"department-search\"],\n    \"avatar_color\": \"#BFDBFF\",\n    \"avatar_symbol\": \"SI\",\n    \"configuration\": {\n      \"instructions\": \"You are a custom agent that wants to help searching data using all indices starting with prefix \\\"content-\\\".\",\n      \"tools\": [\n        {\n          \"tool_ids\": [\n            \"platform.core.search\",\n            \"platform.core.list_indices\",\n            \"platform.core.get_index_mapping\",\n            \"platform.core.get_document_by_id\"\n          ]\n        }\n      ]\n    }\n}'\n"
      - lang: Console
        source: "POST kbn://api/agent_builder/agents\n{\n  \"id\": \"new-agent-id\",\n  \"name\": \"Search Index Helper\",\n  \"description\": \"Hi! I can help you search the data within the indices starting with \\\"content-\\\" prefix.\",\n  \"labels\": [\"custom-indices\", \"department-search\"],\n  \"avatar_color\": \"#BFDBFF\",\n  \"avatar_symbol\": \"SI\",\n  \"configuration\": {\n    \"instructions\": \"You are a custom agent that wants to help searching data using all indices starting with prefix \\\"content-\\\".\",\n    \"tools\": [\n      {\n        \"tool_ids\": [\n          \"platform.core.search\",\n          \"platform.core.list_indices\",\n          \"platform.core.get_index_mapping\",\n          \"platform.core.get_document_by_id\"\n        ]\n      }\n    ]\n  }\n}\n"
      x-state: Added in 9.2.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/agent_builder/agents/{agent_id}/consumption:
    post:
      description: '**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/{agent_id}/consumption</span></div>


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


        Returns paginated, per-conversation token consumption data for a given agent. Includes input/output token counts, round counts, LLM call counts, and warnings for conversations with high token usage. Requires the manageAgents privilege. To learn more about monitoring agent token usage, refer to the [monitor usage documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/monitor-usage).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.'
      operationId: post-agent-builder-agents-agent-id-consumption
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The unique identifier of the agent.
        in: path
        name: agent_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              consumptionDefaultExample:
                description: Get consumption data for an agent with default pagination
                value:
                  size: 25
                  sort_field: updated_at
                  sort_order: desc
              consumptionFilteredExample:
                description: Get consumption data filtered by username with warnings
                value:
                  has_warnings: true
                  size: 10
                  sort_field: total_tokens
                  sort_order: desc
                  usernames:
                  - elastic
                  - admin
            schema:
              additionalProperties: false
              type: object
              properties:
                has_warnings:
                  description: Filter to conversations with or without high-token warnings.
                  type: boolean
                search:
                  description: Free-text search filter on conversation title.
                  type: string
                search_after:
                  description: Cursor for pagination. Pass the search_after value from the previous response.
                  items: {}
                  maxItems: 10000
                  type: array
                size:
                  default: 25
                  description: Number of results per page.
                  maximum: 100
                  minimum: 1
                  type: number
                sort_field:
                  default: updated_at
                  description: Field to sort results by.
                  enum:
                  - updated_at
                  - total_tokens
                  - round_count
                  type: string
                sort_order:
                  default: desc
                  description: Sort direction.
                  enum:
                  - asc
                  - desc
                  type: string
                usernames:
                  description: Filter results to conversations by these usernames.
                  items:
                    type: string
                  maxItems: 10000
                  type: array
      responses:
        '200':
          content:
            application/json:
              examples:
                consumptionResponseExample:
                  description: Example response with per-conversation token usage data
                  value:
                    aggregations:
                      total_with_warnings: 0
                      usernames:
                      - elastic
                      - admin
                    results:
                    - conversation_id: conv-abc123
                      created_at: '2025-03-01T10:00:00Z'
                      llm_calls: 8
                      round_count: 5
                      title: Help me search my data
                      token_usage:
                        input_tokens: 15000
                        output_tokens: 3000
                        total_tokens: 18000
                      updated_at: '2025-03-01T10:15:00Z'
                      user:
                        id: uid-1
                        username: elastic
                      warnings: []
                    - conversation_id: conv-def456
                      created_at: '2025-03-02T14:00:00Z'
                      llm_calls: 20
                      round_count: 12
                      title: Analyze server logs
                      token_usage:
                        input_tokens: 250000
                        output_tokens: 8000
                        total_tokens: 258000
                      updated_at: '2025-03-02T14:30:00Z'
                      user:
                        id: uid-2
                        username: admin
                      warnings:
                      - input_tokens: 250000
                        round_id: round-7
                        type: high_input_tokens
                    search_after:
                    - 1709391000000
                    - '2025-03-02T14:30:00Z'
                    total: 2
          description: Indicates a successful response
      summary: Get agent consumption data
      tags:
      - agent builder
      x-codeSamples:
      - lang: curl
        source: "curl \\\n -X POST \"${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption\" \\\n -H \"Authorization: ApiKey ${API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"elastic-api-version: 2023-10-31\" \\\n -d '{\"size\": 25, \"sort_field\": \"updated_at\", \"sort_order\": \"desc\"}'\n"
      - lang: Console
        source: 'POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption

          {"size": 25, "sort_field": "updated_at", "sort_order": "desc"}

          '
      x-state: Experimental; added in 9.4.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/agent_builder/agents/{id}:
    delete:
      description: '**Spaces method and path for this operation:**


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


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


        Delete an agent by ID. This action cannot be undone. 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.'
      operationId: delete-agent-builder-agents-id
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The unique identifier of the agent to delete.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                deleteAgentResponseExample:
                  description: Example response showing that deletion of the agent has been successful
                  value:
                    success: true
          description: Indicates a successful response
      summary: Delete an agent
      tags:
      - agent builder
      x-codeSamples:
      - lang: curl
        source: "curl \\\n  -X DELETE \"${KIBANA_URL}/api/agent_builder/agents/{id}\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\" \\\n  -H \"kbn-xsrf: true\"\n"
      - lang: Console
        source: 'DELETE kbn://api/agent_builder/agents/{id}

          '
      x-state: Added in 9.2.0
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


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


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


        Get a specific agent by ID. Use this endpoint to retrieve the complete agent definition including all configuration details and tool assignments. 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:read.'
      operationId: get-agent-builder-agents-id
      parameters:
      - description: The unique identifier of the agent to retrieve.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getAgentByIdResponseExample:
                  description: Example response that an agent created by the user that will query elasticsearch indices starting with 'content-' prefix to answer the questions.
                  value:
                    access_control:
                      access_mode: private
                      entries:
                      - name: alice
                        role: manager
                        type: user
                    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
                

# --- truncated at 32 KB (204 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-agent-builder-api-openapi.yml