---
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/v9/operation/operation-post-agent-builder-converse-async
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-post-agent-builder-converse-async
products:
  - Kibana
---

# Send chat message (streaming)

Availability: 9.2+

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