---
type: api
title: Send chat message
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-agent-builder-converse
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-agent-builder-converse
products:
  - Kibana
---

# Send chat message

Availability: 9.2+

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/agent_builder/converse`
- `POST` `/s/{space_id}/api/agent_builder/converse`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth)

## Description

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

Send a message to an agent and receive a complete response. This synchronous endpoint waits for the agent to fully process your request before returning the final result. Use this for simple chat interactions where you need the complete response. To learn more about agent chat, refer to the [agent chat documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/chat).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.

## Request Body

`application/json`

- `_execution_mode` (enum) — optional
  define how to execute the agent (local execution or via task_manager)
  Values: `local`, `task_manager`
- `access_control` (object) — optional
  Optional conversation access control. Defaults to private.
  - `access_mode` (enum) — required
    Access mode to apply when creating a new conversation. Set to public to make the conversation visible to other users who can access the underlying agent. This setting is ignored when continuing an existing conversation.
    Values: `private`, `public`
- `action` (enum) — optional — deprecated
  Deprecated and ignored. The "regenerate" action has been removed; the field is still accepted for backward compatibility.
  Values: `regenerate`
- `agent_id` (string · default: elastic-ai-agent) — optional
  The ID of the agent to chat with. Defaults to the default Elastic AI agent.
- `attachments` ([] object) — optional
  Optional attachments to send with the message.
  - `data` (map string to object) — optional
    Payload of the attachment. Required unless `origin` is provided (content is resolved once at send time).
  - `description` (string · max: 1024) — optional
    Human-readable label for the attachment.
  - `group_id` (string · max: 256) — optional
    Stable identifier for the logical group this attachment belongs to. Attachments sharing the same group_id were submitted together as a single logical entity.
  - `hidden` (boolean) — optional
    When true, the attachment will not be displayed in the UI.
  - `id` (string) — optional
    Optional id for the attachment.
  - `origin` (string) — optional
    Origin string (for example, saved object ID) for by-reference attachments. When provided without `data`, the content is resolved once using the attachment type’s `resolve` hook.
  - `type` (string) — required
    Type of the attachment.
- `browser_api_tools` ([] object) — optional
  Optional browser API tools to be registered as LLM tools with browser.* namespace. These tools execute on the client side.
  - `description` (string) — required
    Description of what the browser API tool does.
  - `id` (string) — required
    Unique identifier for the browser API tool.
  - `schema` (object) — required
    JSON Schema defining the tool parameters (JsonSchema7Type).
- `configuration_overrides` (object) — optional
  Runtime configuration overrides. These override the stored agent configuration for this execution only.
  - `enable_elastic_capabilities` (boolean) — optional
    Whether to enable built-in Elastic skills for this execution.
  - `instructions` (string) — optional
    Custom instructions for the agent.
  - `skill_ids` ([] string · max: 100) — optional
    Skill IDs to enable for this execution, replacing the stored skill list. Note: only fully restricts the available skill set when enable_elastic_capabilities is also set to false.
  - `tools` ([] object) — optional
    Tool selection to enable for this execution.
    - `tool_ids` ([] string) — required
- `connector_id` (string) — optional — nullable
  Optional connector ID for the agent to use for model routing. Mutually exclusive with `inference_id`; omit or use only one.
- `conversation_id` (string · max: 256) — optional
  Optional existing conversation ID to continue a previous conversation.
- `execution_id` (string) — optional
  Optional client-generated execution ID. Provide it to address this execution later (for example, to abort it). Must be unique; defaults to a server-generated ID.
- `inference_id` (string) — optional — nullable
  Optional inference endpoint ID for model routing (public alias for the same internal identifier as `connector_id`). Mutually exclusive with `connector_id`.
- `input` (string · max: 100000) — optional
  The user input message to send to the agent.
- `project_routing` (string · max: 2048) — optional
  Cross-project search routing expression resolved from the header project picker, applied to the run's searches. Serverless (CPS) only; ignored elsewhere.
- `prompts` (map string to anyOf) — optional
  Use this field to respond to a `confirmation`, `authorization`, or `ask_user_question` prompt. Send an `allow` boolean to answer a `confirmation` prompt, an `authorized` boolean to answer an `authorization` prompt, or an `answers` array (one entry per question) to answer an `ask_user_question` prompt.
- `read_only` (boolean) — optional
  When true, the created conversation is presented as read-only in the UI: its history is shown but no message input is offered. This carries no authorization meaning — the conversation can still be continued through the API. This setting is ignored when continuing an existing conversation.
- `reasoning_level` (enum) — optional
  Reasoning effort level for the LLM. One of: none, minimal, low, medium, high, xhigh. Support depends on the underlying model and provider.
  Values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`

## Response

Indicates a successful response

## Code Examples

#### Console

```console
POST kbn://api/agent_builder/converse
{
  "input": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent",
  "access_control": {
    "access_mode": "public"
  }
}
```

#### curl

```curl
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",
    "access_control": {
      "access_mode": "public"
    }
  }'
```

## Response Examples

#### Converse response

Example response containing the chain of events representing a conversation with the agent

```json
{
  "access_control": {
    "access_mode": "private"
  },
  "conversation_id": "696ccd6d-4bff-4b26-a62e-522ccf2dcd16",
  "response": {
    "message": "Elasticsearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. As the heart of the Elastic Stack, it centrally stores your data for lightning fast search, fine\u2011tuned relevancy, and powerful analytics that scale with ease."
  },
  "steps": [
    {
      "reasoning": "Searching for official documentation or content that explains what Elasticsearch is",
      "type": "reasoning"
    },
    {
      "params": {
        "query": "what is elasticsearch definition overview introduction"
      },
      "progression": [
        {
          "message": "Selecting the best target for this query"
        }
      ],
      "results": [
        {
          "data": {
            "message": "Could not figure out which index to use"
          },
          "type": "error"
        }
      ],
      "tool_call_id": "tooluse_shOdUwKIRwC9YhqGzeg0cQ",
      "tool_id": "platform.core.search",
      "type": "tool_call"
    }
  ]
}
```