---
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/v9/operation/operation-post-agent-builder-converse
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/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/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/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
  The action to perform. "regenerate" re-executes the last round with the original input. Requires conversation_id.
  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).
- `capabilities` (object) — optional
  Controls agent capabilities during conversation. Currently supports visualization rendering for tabular tool results.
  - `visualizations` (boolean) — optional
    When true, allows the agent to render tabular data from tool results as interactive visualizations using custom XML elements in responses.
- `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) — 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) — optional
  The user input message to send to the agent.
- `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.

## 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"
    }
  ]
}
```