Send chat message (streaming) Technical Preview

View as Markdown
POST /api/agent_builder/converse/async
Api key auth

Spaces method and path for this operation:

post /s/{space_id}/api/agent_builder/converse/async

Refer to 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:

{
  "conversation_id": "uuid"
}

conversation_created

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

Schema:

{
  "conversation_id": "uuid",
  "title": "conversation title"
}

conversation_updated

Fires when a conversation is updated.

Schema:

{
  "conversation_id": "uuid",
  "title": "updated conversation title"
}

reasoning

Handles reasoning-related data.

Schema:

{
  "reasoning": "plain text reasoning content",
  "transient": false
}

tool_call

Triggers when a tool is invoked.

Schema:

{
  "tool_call_id": "uuid",
  "tool_id": "tool_name",
  "params": {}
}

tool_progress

Reports progress of a running tool.

Schema:

{
  "tool_call_id": "uuid",
  "message": "progress message"
}

tool_result

Returns results from a completed tool call.

Schema:

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

Note: results is an array of ToolResult objects.

message_chunk

Streams partial text chunks.

Schema:

{
  "message_id": "uuid",
  "text_chunk": "partial text"
}

message_complete

Indicates message stream is finished.

Schema:

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

thinking_complete

Marks the end of the thinking/reasoning phase.

Schema:

{
  "time_to_first_token": 0
}

Note: time_to_first_token is in milliseconds.

round_complete

Marks end of one conversation round.

Schema:

{
  "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

    [Required authorization] Route required privileges: read_onechat.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • agent_id string

    The ID of the agent to chat with. Defaults to the default Elastic AI agent.

    Default value is elastic-ai-agent.

  • attachments array[object]

    Optional attachments to send with the message.

    Hide attachments attributes Show attachments attributes object
    • data object Required

      Payload of the attachment.

      Additional properties are allowed.

    • hidden boolean

      When true, the attachment will not be displayed in the UI.

    • id string

      Optional id for the attachment.

    • type string Required

      Type of the attachment.

  • browser_api_tools array[object]

    Optional browser API tools to be registered as LLM tools with browser.* namespace. These tools execute on the client side.

    Hide browser_api_tools attributes Show browser_api_tools attributes object
    • description string Required

      Description of what the browser API tool does.

    • id string Required

      Unique identifier for the browser API tool.

  • capabilities object

    Controls agent capabilities during conversation. Currently supports visualization rendering for tabular tool results.

    Additional properties are NOT allowed.

    Hide capabilities attribute Show capabilities attribute object
    • visualizations boolean

      When true, allows the agent to render tabular data from tool results as interactive visualizations using custom XML elements in responses.

  • connector_id string

    Optional connector ID for the agent to use for external integrations.

  • conversation_id string

    Optional existing conversation ID to continue a previous conversation.

  • input string Required

    The user input message to send to the agent.

Responses

  • 200 text/event-stream

    Indicates a successful response

POST /api/agent_builder/converse/async 
curl \
 --request POST 'https://<KIBANA_URL>/api/agent_builder/converse/async' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"input":"Hello","agent_id":"elastic-ai-agent","conversation_id":"c250305b-1929-4248-b568-b9e3f065fda5"}'
Request example
Example request to send a message to the agent as a part of the conversation 
{
  "input": "Hello",
  "agent_id": "elastic-ai-agent",
  "conversation_id": "c250305b-1929-4248-b568-b9e3f065fda5"
}
Response examples (200)
Example stream containing the chain of events representing a conversation with the agent 
[{"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_id" => "platform.core.search", "tool_call_id" => "tooluse__2aJELgyRYqD8SDOKSiwtg"}}, "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"}]