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

# Send chat message (streaming)

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

## Paths

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

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

## Description

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

Send a message to an agent and receive real-time streaming events. This asynchronous endpoint provides live updates as the agent processes your request, allowing you to see intermediate steps and progress. Use this for interactive experiences where you want to monitor the agent's thinking process.

## Event types

The endpoint emits Server-Sent Events (SSE) with the following custom event types:

`conversation_id_set`

Sets the conversation ID.

Schema:
```json
{
  "conversation_id": "uuid"
}
```

---

`conversation_created`

Fires when a new conversation is persisted and assigned an ID.

Schema:
```json
{
  "conversation_id": "uuid",
  "title": "conversation title"
}
```

---

`conversation_updated`

Fires when a conversation is updated.

Schema:
```json
{
  "conversation_id": "uuid",
  "title": "updated conversation title"
}
```

---

`reasoning`

Handles reasoning-related data.

Schema:
```json
{
  "reasoning": "plain text reasoning content",
  "transient": false
}
```

---

`tool_call`

Triggers when a tool is invoked.

Schema:
```json
{
  "tool_call_id": "uuid",
  "tool_id": "tool_name",
  "params": {}
}
```

---

`tool_progress`

Reports progress of a running tool.

Schema:
```json
{
  "tool_call_id": "uuid",
  "message": "progress message"
}
```

---

`tool_result`

Returns results from a completed tool call.

Schema:
```json
{
  "tool_call_id": "uuid",
  "tool_id": "tool_name",
  "results": []
}
```

**Note:** `results` is an array of `ToolResult` objects.

---

`message_chunk`

Streams partial text chunks.

Schema:
```json
{
  "message_id": "uuid",
  "text_chunk": "partial text"
}
```

---

`message_complete`

Indicates message stream is finished.

Schema:
```json
{
  "message_id": "uuid",
  "message_content": "full text content of the message"
}
```

---

`thinking_complete`

Marks the end of the thinking/reasoning phase.

Schema:
```json
{
  "time_to_first_token": 0
}
```

**Note:** `time_to_first_token` is in milliseconds.

---

`round_complete`

Marks end of one conversation round.

Schema:
```json
{
  "round": {}
}
```

**Note:** `round` contains the full round json object.

---

## Event flow

A typical conversation round emits events in this sequence:

1. `reasoning` (potentially multiple, some transient)
2. `tool_call` (if tools are used)
3. `tool_progress` (zero or more progress updates)
4. `tool_result` (when tool completes)
5. `thinking_complete`
6. `message_chunk` (multiple, as text streams)
7. `message_complete`
8. `round_complete`

<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/async
{
  "input": "Hello again let's have an async chat",
  "agent_id": "elastic-ai-agent",
  "conversation_id": "<CONVERSATION_ID>"
}
```

#### curl

```curl
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>"
  }'
```

## Response Examples

#### Converse async response

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

```json
[
  {
    "data": {
      "data": {
        "conversation_id": "c250305b-1929-4248-b568-b9e3f065fda5"
      }
    },
    "event": "conversation_id_set"
  },
  {
    "data": {
      "data": {
        "reasoning": "Starting with a general search to understand what content is available."
      }
    },
    "event": "reasoning"
  },
  {
    "data": {
      "data": {
        "params": {
          "query": "latest documents"
        },
        "tool_call_id": "tooluse__2aJELgyRYqD8SDOKSiwtg",
        "tool_id": "platform.core.search"
      }
    },
    "event": "tool_call"
  },
  {
    "data": {
      "data": {
        "results": [
          {
            "data": {
              "message": "Could not figure out which index to use"
            },
            "type": "error"
          }
        ],
        "tool_call_id": "tooluse__2aJELgyRYqD8SDOKSiwtg"
      }
    },
    "event": "tool_result"
  },
  {
    "data": {
      "data": {
        "round": {
          "id": "a5692d54-bc06-4a6e-aea1-412779c73f66",
          "input": {
            "message": "Hello"
          },
          "response": {
            "message": "Hello! How can I help you today?"
          }
        }
      }
    },
    "event": "round_complete"
  },
  {
    "data": {
      "data": {
        "access_control": {
          "access_mode": "private"
        },
        "conversation_id": "c250305b-1929-4248-b568-b9e3f065fda5",
        "title": "Hello"
      }
    },
    "event": "conversation_created"
  }
]
```