This is a cache of https://www.elastic.co/docs/solutions/search/agent-builder/kibana-api. It is a snapshot of the page at 2025-10-30T00:34:55.222+0000.
Work with Elastic Agent Builder using the APIs | Elastic Docs
Loading

Work with Elastic Agent Builder using the APIs

Serverless Elasticsearch Preview Serverless Observability Unavailable Serverless Security Unavailable Stack Preview 9.2.0

This page provides a quick overview of the main Kibana API endpoints for Elastic Agent Builder. For complete details including all available parameters, request/response schemas, and error handling, refer to the Kibana API reference.

These APIs allow you to programmatically work with the Elastic Agent Builder abstractions.

The examples in this documentation use Dev Tools Console syntax.

				GET kbn://api/agent_builder/tools

To use these APIs with tools like curl, replace the kbn:// protocol with your Kibana URL.

Note

Set the required environment variables before running curl commands:

export KIBANA_URL="your-kibana-url"
export API_KEY="your-api-key"
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

To generate API keys, search for API keys in the global search bar. Learn more.

To run APIs in non-default spaces, you must include the space identifier in the URL when making API calls with curl or other external tools. Insert /s/<space_name> before /api/agent_builder in your requests.

For example, to list tools in a space named my-space:

curl -X GET "https://${KIBANA_URL}/s/my-space/api/agent_builder/tools" \
     -H "Authorization: ApiKey ${API_KEY}"

The default space does not require the /s/default prefix.

Dev Tools Console automatically uses your current space context and does not require the /s/<space_name> prefix.

Example: List all tools

This example uses the list tools API.

				GET kbn://api/agent_builder/tools
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Create a tool

This example uses the create a tool API.

				POST kbn://api/agent_builder/tools
					{
  "id": "example-esql-tool",
  "type": "esql",
  "description": "An ES|QL query tool for analyzing financial trades with time filtering",
  "tags": ["analytics", "finance", "updated"],
  "configuration": {
    "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
    "params": {
      "startTime": {
        "type": "date",
        "description": "Start time for the analysis in ISO format"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return"
      }
    }
  }
}
		
curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "example-esql-tool",
       "type": "esql",
       "description": "Example ES|QL query tool for analyzing financial trades with time filtering",
       "tags": ["analytics", "finance"],
       "configuration": {
         "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
         "params": {
           "startTime": {
             "type": "date",
             "description": "Start time for the analysis in ISO format"
           },
           "limit": {
             "type": "integer",
             "description": "Maximum number of results to return"
           }
         }
       }
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Get a tool by ID

This example uses the get a tool by ID API.

				GET kbn://api/agent_builder/tools/{id}
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/tools/{id}" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Delete a tool by ID

This example uses the delete a tool by ID API.

				DELETE kbn://api/agent_builder/tools/{id}
		
curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/tools/{id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Update a tool by ID

This example uses the update a tool API.

				PUT kbn://api/agent_builder/tools/{toolId}
					{
  "description": "Updated ES|QL query tool for analyzing financial trades with time filtering",
  "tags": ["analytics", "finance", "updated"],
  "configuration": {
    "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
    "params": {
      "startTime": {
        "type": "date",
        "description": "Start time for the analysis in ISO format"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return"
      }
    }
  }
}
		
curl -X PUT "https://${KIBANA_URL}/api/agent_builder/tools/{toolId}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Updated ES|QL query tool for analyzing financial trades with time filtering",
       "tags": ["analytics", "finance", "updated"],
       "configuration": {
         "query": "FROM financial_trades | WHERE execution_timestamp >= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
         "params": {
           "startTime": {
             "type": "date",
             "description": "Start time for the analysis in ISO format"
           },
           "limit": {
             "type": "integer",
             "description": "Maximum number of results to return"
           }
         }
       }
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Run a tool

This example uses the execute a tool API.

				POST kbn://api/agent_builder/tools/_execute
					{
  "tool_id": "platform.core.search",
  "tool_params": {
    "query": "can you find john doe's email from the employee index?"
  }
}
		
curl -X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "tool_id": "platform.core.search",
       "tool_params": {
         "query": "can you find john doe's email from the employee index?"}
       }
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: List all agents

This example uses the list agents API.

				GET kbn://api/agent_builder/agents
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/agents" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Create an agent

This example uses the create an agent API.

				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 -X POST "https://${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"
             ]
           }
         ]
       }
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Get an agent by ID

This example uses the get an agent by ID API.

				GET kbn://api/agent_builder/agents/{id}
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Update an agent by ID

This example uses the update an agent API.

				PUT kbn://api/agent_builder/agents/{id}
					{
  "name": "Search Index Helper",
  "description": "Updated description - Search for anything in \"content-*\" indices!",
  "labels": ["custom-indices", "department-search", "elastic-employees"],
  "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 -X PUT "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Search Index Helper",
       "description": "Updated description - Search for anything in \"content-*\" indices!",
       "labels": ["custom-indices", "department-search", "elastic-employees"],
       "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"
           ]
         }]
       }
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Delete an agent by ID

This example uses the delete an agent by ID API.

				DELETE kbn://api/agent_builder/agents/{id}
		
curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/agents/{id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Chat with an agent

This example uses the send chat message API.

				POST kbn://api/agent_builder/converse
					{
  "input": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent"
}
		
curl -X POST "https://${KIBANA_URL}/api/agent_builder/converse" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "input": "What is Elasticsearch?",
       "agent_id": "elastic-ai-agent"}'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Chat with an agent and stream events

This example uses the send chat message (streaming) API.

				POST kbn://api/agent_builder/converse/async
					{
  "input": "hello again let's have an async chat",
  "agent_id": "elastic-ai-agent",
  "conversation_id": "<CONVERSATION_ID>"
}
		
curl -X POST "https://${KIBANA_URL}/api/agent_builder/converse/async" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "input": "hello again let us have an async chat",
       "agent_id": "elastic-ai-agent",
       "conversation_id": "<CONVERSATION_ID>"
     }'
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: List conversations

This example uses the list conversations API.

				GET kbn://api/agent_builder/conversations
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/conversations" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Get conversation by ID

This example uses the get conversation by ID API.

				GET kbn://api/agent_builder/conversations/{conversation_id}
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Example: Delete conversation by ID

This example uses the delete conversation by ID API.

				DELETE kbn://api/agent_builder/conversations/{conversation_id}
		
curl -X DELETE "https://${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Refer to Model Context Protocol (MCP) server for more information.

Communicate with the MCP server using JSON-RPC 2.0.

curl -X POST "https://${KIBANA_URL}/api/agent_builder/mcp" \
    -H "Authorization: ApiKey ${API_KEY}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "kbn-xsrf: true" \
    -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list"
    }'

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

Note

This endpoint uses the JSON-RPC protocol. The MCP server is used by AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this Kibana API endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and does not work from the Dev Tools Console.

Refer to Agent-to-Agent (A2A) server for more information.

Example: Get A2A agent card configuration

This example uses the get A2A agent card API.

				GET kbn://api/agent_builder/a2a/{agentId}.json
		
curl -X GET "https://${KIBANA_URL}/api/agent_builder/a2a/{agentId}.json" \
     -H "Authorization: ApiKey ${API_KEY}"
Tip

If you're using Spaces, you need to prefix /api/agent_builder with /s/<space_name>. Refer to Working with Spaces.

For the full API documentation, refer to the Kibana API reference.