Elastic Agent Builder Kibana APIs overview

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 enable you to programmatically work with Elastic Agent Builder abstractions such as agents, tools, and skills.

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.

export KIBANA_URL="your-kibana-url"
export API_KEY="your-api-key"

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

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-id> before /api/agent_builder in your requests.

For example, to list tools in a space with the ID my-space:

curl -X GET "${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 doesn't require the /s/<space-id> prefix.

When you have projects linked through cross-project search, Elastic Agent Builder APIs that search your data use the default cross-project search scope for the space in the request URL. Requests without /s/<space-id> use the default space.

To override that default, include a project_routing expression in the body of the send chat message API or the send chat message (streaming) API. The run a tool API uses the space default and does not accept this field. For routing expression syntax, refer to Using project routing to limit cross-project search scope. For an example, refer to Chat and conversations.

The following sections provide quick examples for each API endpoint grouped by resource type.

Use these APIs to create, list, update, delete, and run tools.

Example: List all tools

This example uses the list tools API.

GET kbn://api/agent_builder/tools

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

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

Example: Create a tool with default values for optional parameters Stack 9.3+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

This example creates an ES|QL tool with optional parameters that have default values, which are automatically used when the agent doesn't provide them.

POST kbn://api/agent_builder/tools
{
  "id": "sales-analysis-tool",
  "type": "esql",
  "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters",
  "tags": ["analytics", "sales"],
  "configuration": {
    "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit",
    "params": {
      "start_date": {
        "type": "date",
        "description": "Start date for analysis. When not provided by the agent, defaults to '2024-01-01T00:00:00Z'",
        "optional": true,
        "defaultValue": "2024-01-01T00:00:00Z"
      },
      "region": {
        "type": "string",
        "description": "Sales region to filter by. If omitted, defaults to 'ALL' to include all regions",
        "optional": true,
        "defaultValue": "ALL"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum results to return. When not specified, automatically limits to 50 results",
        "optional": true,
        "defaultValue": 50
      }
    }
  }
}

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": "sales-analysis-tool",
       "type": "esql",
       "description": "Analyze sales data with optional time filtering and automatic defaults for unspecified parameters",
       "tags": ["analytics", "sales"],
       "configuration": {
         "query": "FROM sales | WHERE timestamp >= ?start_date AND region == ?region | STATS total_sales=SUM(amount) BY product | LIMIT ?limit",
         "params": {
           "start_date": {
             "type": "date",
             "description": "Start date for analysis. When not provided by the agent, defaults to \"2024-01-01T00:00:00Z\"",
             "optional": true,
             "defaultValue": "2024-01-01T00:00:00Z"
           },
           "region": {
             "type": "string",
             "description": "Sales region to filter by. If omitted, defaults to \"ALL\" to include all regions",
             "optional": true,
             "defaultValue": "ALL"
           },
           "limit": {
             "type": "integer",
             "description": "Maximum results to return. When not specified, automatically limits to 50 results",
             "optional": true,
             "defaultValue": 50
           }
         }
       }
     }'

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 "${KIBANA_URL}/api/agent_builder/tools/{id}" \
     -H "Authorization: ApiKey ${API_KEY}"

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 "${KIBANA_URL}/api/agent_builder/tools/{id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"

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

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 "${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?"}
       }
     }'

Use these APIs to create, list, update, and delete skills.

Example: List all skills

This example uses the list skills API.

GET kbn://api/agent_builder/skills

curl -X GET "${KIBANA_URL}/api/agent_builder/skills" \
     -H "Authorization: ApiKey ${API_KEY}"

Example: Create a skill

This example uses the create a skill API.

POST kbn://api/agent_builder/skills
{
  "id": "my-log-triage-skill",
  "name": "Log Triage",
  "description": "Guides triage of application log errors: classify by severity, identify the affected service and host, and suggest remediation steps. Use when a user asks to investigate or summarize log errors.",
  "content": "## When to Use This Skill\n\nUse this skill when:\n- A user asks to investigate or summarize log errors\n- A user wants to understand the cause of application failures\n\n## Log Triage Process\n\n### 1. Identify the affected service\n- Query recent error logs using `platform.core.execute_esql`\n- Extract `service.name`, `host.name`, and `log.level` fields\n\n### 2. Classify by severity\n- Group errors by type and frequency\n- Note any spike in error rate\n\n### 3. Suggest remediation\n- Summarize the most common errors\n- Suggest next steps based on error patterns",
  "tool_ids": [
    "platform.core.execute_esql",
    "platform.core.generate_esql",
    "platform.core.list_indices"
  ]
}

curl -X POST "${KIBANA_URL}/api/agent_builder/skills" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "my-log-triage-skill",
       "name": "Log Triage",
       "description": "Guides triage of application log errors: classify by severity, identify the affected service and host, and suggest remediation steps. Use when a user asks to investigate or summarize log errors.",
       "content": "## When to Use This Skill\n\n...",
       "tool_ids": [
         "platform.core.execute_esql",
         "platform.core.generate_esql",
         "platform.core.list_indices"
       ]
     }'

Example: Create a skill with referenced content

This example uses the create a skill API with referenced_content to attach supporting files the agent can read selectively.

POST kbn://api/agent_builder/skills
{
  "id": "my-log-triage-skill",
  "name": "Log Triage",
  "description": "Guides triage of application log errors. Use when a user asks to investigate or summarize log errors.",
  "content": "## Log Triage Process\n\nFor example ES|QL queries, see `./queries`.",
  "tool_ids": ["platform.core.execute_esql"],
  "referenced_content": [
    {
      "name": "queries",
      "relativePath": "./queries",
      "content": "# Example Queries\n\n## Recent errors by service\n```esql\nFROM logs-* | WHERE log.level == \"error\" | STATS count = COUNT(*) BY service.name | SORT count DESC | LIMIT 10\n```"
    }
  ]
}

curl -X POST "${KIBANA_URL}/api/agent_builder/skills" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "my-log-triage-skill",
       "name": "Log Triage",
       "description": "Guides triage of application log errors. Use when a user asks to investigate or summarize log errors.",
       "content": "## Log Triage Process\n\nFor example ES|QL queries, see `./queries`.",
       "tool_ids": ["platform.core.execute_esql"],
       "referenced_content": [
         {
           "name": "queries",
           "relativePath": "./queries",
           "content": "# Example Queries\n\n## Recent errors by service\n```esql\nFROM logs-* | WHERE log.level == \"error\" | STATS count = COUNT(*) BY service.name | SORT count DESC | LIMIT 10\n```"
         }
       ]
     }'

Example: Get a skill by ID

This example uses the get a skill by ID API.

GET kbn://api/agent_builder/skills/{skillId}

curl -X GET "${KIBANA_URL}/api/agent_builder/skills/{skillId}" \
     -H "Authorization: ApiKey ${API_KEY}"

Example: Update a skill

This example uses the update a skill API.

PUT kbn://api/agent_builder/skills/{skillId}
{
  "description": "Updated description with more specific trigger conditions.",
  "content": "## When to Use This Skill\n\n(updated instructions)",
  "tool_ids": [
    "platform.core.execute_esql",
    "platform.core.generate_esql"
  ]
}

curl -X PUT "${KIBANA_URL}/api/agent_builder/skills/{skillId}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Updated description with more specific trigger conditions.",
       "content": "## When to Use This Skill\n\n(updated instructions)",
       "tool_ids": [
         "platform.core.execute_esql",
         "platform.core.generate_esql"
       ]
     }'

Example: Delete a skill

This example uses the delete a skill API.

DELETE kbn://api/agent_builder/skills/{skillId}

curl -X DELETE "${KIBANA_URL}/api/agent_builder/skills/{skillId}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"

Use these APIs to create, list, update, and delete agents, and to track token consumption.

Example: List all agents

This example uses the list agents API.

GET kbn://api/agent_builder/agents

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

Example: Create an agent

This example uses the create an agent API.

Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. If you omit access_control, the agent is private: only you and administrators can view and edit it.

Stack 9.5+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. You can't grant individual users access when you create an agent. On create, access_control accepts only access_mode, and including entries returns a validation error. To grant access, call PUT /api/agent_builder/agents/{id}/access_control after the agent exists.

Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. To assign connectors to the agent, list their IDs in configuration.connector_ids. If you omit connector_ids, the agent can't run any connectors.

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",
  "access_control": { "access_mode": "shared" },
  "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 "${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",
       "access_control": { "access_mode": "shared" },
       "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"
             ]
           }
         ]
       }
     }'

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 "${KIBANA_URL}/api/agent_builder/agents/{id}" \
     -H "Authorization: ApiKey ${API_KEY}"

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

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 "${KIBANA_URL}/api/agent_builder/agents/{id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"

Use this API to retrieve per-conversation token usage data for a given agent. This endpoint requires the manageAgents privilege and provides cross-user visibility into token consumption across all conversations for the specified agent.

The response includes input and output token counts, round counts, LLM call counts, and warnings for conversations with high token usage. No message content or tool results are exposed.

To understand how token usage is calculated and how to view per-response totals in the UI, refer to Monitor token usage.

Example: Get token consumption for an agent

This example uses the get agent consumption data API with default pagination.

POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{
  "size": 25,
  "sort_field": "updated_at",
  "sort_order": "desc"
}

curl -X POST "${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "size": 25,
       "sort_field": "updated_at",
       "sort_order": "desc"
     }'

Example: Filter consumption data by username and warnings

This example filters results to specific users and conversations that have high-token warnings, sorted by total token count.

POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{
  "size": 10,
  "sort_field": "total_tokens",
  "sort_order": "desc",
  "usernames": ["elastic", "admin"],
  "has_warnings": true
}

curl -X POST "${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "size": 10,
       "sort_field": "total_tokens",
       "sort_order": "desc",
       "usernames": ["elastic", "admin"],
       "has_warnings": true
     }'

Example: Paginate through consumption results

To paginate, pass the search_after value from the previous response.

POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{
  "size": 10,
  "sort_field": "updated_at",
  "sort_order": "desc",
  "search_after": [1709391000000, "2025-03-02T14:30:00Z"]
}

curl -X POST "${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "size": 10,
       "sort_field": "updated_at",
       "sort_order": "desc",
       "search_after": [1709391000000, "2025-03-02T14:30:00Z"]
     }'

Use these APIs to send messages to agents and manage conversation history.

Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. The input parameter of the send chat message API and the send chat message (streaming) API accepts up to 100,000 characters. A request with a longer input returns a 400 error.

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

Example: Chat as a service account Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Unavailable Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Unavailable This functionality is not available in Elastic Cloud Serverless.

This example calls the send chat message API as a user-managed service account. The account needs the privileges described in Service accounts.

Send this request with curl or another HTTP client. Dev Tools Console runs as the signed-in user, not as the service account, so this example has no Console version.

Before you send the request, set SERVICE_ACCOUNT_TOKEN to the account's service token. The request sends the token in a Bearer authorization header, which Kibana accepts by default. If you changed the accepted schemes, refer to HTTP authentication.

This example creates a public conversation. To create a private conversation that only the account can access, omit access_control.

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

The response's author object identifies the service account as the author of the message:

{
  "author": {
    "id": "service_account:kibana/automation",
    "type": "service_account",
    "username": "kibana/automation"
  }
}

When you get the conversation, its user object, which identifies the owner, has the same values.

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

Example: Route a request to a specific model Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

By default, a request uses the default model for Elastic Agent Builder, as set on the Feature settings page. To override the model for a single request, pass either connector_id or inference_id in the request body:

• inference_id takes an inference endpoint ID. Use this parameter for new integrations.
• connector_id takes a connector ID. Generative AI connectors are deprecated.

Both parameters route the request to the same underlying model and are mutually exclusive. If you send both, the request fails with a 400 error.

POST kbn://api/agent_builder/converse
{
  "input": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent",
  "inference_id": "my-inference-endpoint-id"
}

curl -X POST "${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",
       "inference_id": "my-inference-endpoint-id"}'

Example: Scope a chat across projects Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

By default, the cross-project search scope is the default scope for the space in the request URL. Requests without /s/<space-id> use the CPS scope from the default space.

Include a project_routing expression in the body to override the space's CPS scope. The _alias:my_search_project expression in this example searches only the project with that alias. For routing expression syntax, refer to Using project routing to limit cross-project search scope.

This example uses the send chat message API.

POST kbn://api/agent_builder/converse
{
  "input": "Show recent errors",
  "agent_id": "elastic-ai-agent",
  "project_routing": "_alias:my_search_project"
}

curl -X POST "${KIBANA_URL}/api/agent_builder/converse" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "input": "Show recent errors",
       "agent_id": "elastic-ai-agent",
       "project_routing": "_alias:my_search_project"
     }'

Example: Create a conversation Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

This example uses the create a conversation API.

Every field is optional. If you omit agent_id, the conversation uses the default Elastic AI Agent. If you omit title, the conversation is named New conversation. If you omit access_control, the conversation is private to you.

POST kbn://api/agent_builder/conversations
{
  "agent_id": "elastic-ai-agent"
}

curl -X POST "${KIBANA_URL}/api/agent_builder/conversations" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{"agent_id": "elastic-ai-agent"}'

The response includes the conversation's access_control and your permissions on it:

{
  "id": "8e5fd2c3-04d7-4b1a-b295-5d486afd8584",
  "agent_id": "elastic-ai-agent",
  "title": "New conversation",
  "access_control": {
    "access_mode": "private",
    "entries": []
  },
  "permissions": {
    "rename": true,
    "delete": true,
    "update_access_control": true
  }
}

To share the conversation at creation time, include an access_control object with the same shape as the update conversation access control example.

Example: Add events to a conversation Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

This example uses the add events to a conversation API.

Use this API to add information to a conversation without the agent responding. For example, an integration can post incident updates as they happen. The agent reads notes the next time it runs on the conversation, so a later request can ask it to summarize them.

Kibana features can define their own event types, and each type defines the shape of its data payload. Some event types are only shown in the conversation and aren't sent to the agent. Elastic Agent Builder provides the text_note event type, which takes a required text field (up to 1,000 characters) and an optional title field (up to 256 characters). Other fields in data are discarded. Notes appear in the conversation in Agent Chat.

POST kbn://api/agent_builder/conversations/{conversation_id}/_add_events
{
  "events": [
    {
      "type": "text_note",
      "data": {
        "title": "Status update",
        "text": "Checkout service latency is back to normal."
      }
    }
  ]
}

curl -X POST "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}/_add_events" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "events": [
         {
           "type": "text_note",
           "data": {
             "title": "Status update",
             "text": "Checkout service latency is back to normal."
           }
         }
       ]
     }'

The response returns each added event with the ID, author, and timestamp that Kibana assigned to it:

{
  "events": [
    {
      "type": "text_note",
      "data": {
        "title": "Status update",
        "text": "Checkout service latency is back to normal."
      },
      "id": "cb684ca4-c5f6-4cd3-bbbc-7411ce893a5c",
      "actor": {
        "type": "user",
        "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0",
        "username": "elastic"
      },
      "created_at": "2026-10-13T12:55:51.379Z"
    }
  ]
}

Keep the following in mind:

• If any event in the request is invalid, the whole request fails with a 400 error and no events are added.
• Each request can add between 1 and 10 events.
• Events are append-only. You can't update or remove an event after you add it.
• You must own the conversation or be a member of it, or the conversation must be public. You must also be able to use the conversation's agent. Otherwise, the request returns a 404 error.

To add events from a workflow, use the ai.conversation.add_event step.

Example: List conversations

This example uses the list conversations API.

GET kbn://api/agent_builder/conversations

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

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 "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \
     -H "Authorization: ApiKey ${API_KEY}"

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 "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true"

Example: Update conversation access control Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

This example uses the update conversation access control API.

Share a conversation with specific users, or make it readable by anyone who can access its agent. Only the conversation owner can call this endpoint. To learn what members can do, refer to Conversation access control.

Each request replaces the entire access control. To stop sharing, send private with an empty entries list.

The id of each entry is a Kibana user profile ID, not a username.

Serverless Unavailable Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Unavailable This functionality is not available in Elastic Cloud Serverless. To add a service account as a member, use service_account: followed by the account's principal as the id, such as service_account:kibana/automation. Keep type set to user.

PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control
{
  "access_mode": "private",
  "entries": [
    {
      "type": "user",
      "id": "<USER_PROFILE_UID>",
      "role": "member"
    }
  ]
}

curl -X PUT "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}/access_control" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
       "access_mode": "private",
       "entries": [
         {"type": "user", "id": "<USER_PROFILE_UID>", "role": "member"}
       ]
     }'

To make a conversation readable by anyone who can access its agent, set access_mode to public and send an empty entries list:

PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control
{
  "access_mode": "public",
  "entries": []
}

Keep these constraints in mind:

• entries is required. Send an empty list when access_mode is public, or to unshare.
• entries must be empty when access_mode is public.
• A conversation can have at most 100 members.
• Each user can appear only once. Repeated IDs are rejected.
• member is the only supported role, and user is the only supported entry type.
• An entry that names the owner is accepted but not stored.
• Entry IDs are not validated. An ID that does not match a real user profile is stored and simply never grants access to anyone. Serverless Unavailable Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Unavailable This functionality is not available in Elastic Cloud Serverless. An ID that does not match a service account is also stored, and it grants access if a matching service account is created later.
• If you do not own the conversation, the request fails with a 404 error rather than a permissions error.

Use this API to retrieve the A2A agent card configuration for a specific agent.

Example: Get A2A agent card configuration

GET kbn://api/agent_builder/a2a/{agentId}.json

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

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

Try the hands-on API tutorial to get a feel for the flow of working with Agent Builder programmatically.