Send chat message

Base URL
https://{kibana_url}
  • POST /api/agent_builder/converse
Auth

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.

Required authorization

Privileges agentBuilder:read

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

_execution_mode enum

define how to execute the agent (local execution or via task_manager)

Values: local task_manager
access_control object

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

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

attachments object[]

Optional attachments to send with the message.

data map string to object

Payload of the attachment. Required unless origin is provided (content is resolved once at send time).

description string · max length: 1024

Human-readable label for the attachment.

group_id string · max length: 256

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

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

id string

Optional id for the attachment.

origin string

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

Runtime configuration overrides. These override the stored agent configuration for this execution only.

enable_elastic_capabilities boolean

Whether to enable built-in Elastic skills for this execution.

instructions string

Custom instructions for the agent.

skill_ids string[] · max items: 100

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[]

Tool selection to enable for this execution.

tool_ids string[] required
connector_id string 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 length: 256

Optional existing conversation ID to continue a previous conversation.

execution_id string

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

The user input message to send to the agent.

project_routing string · max length: 2048

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

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

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

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

200

Indicates a successful response

application/json
Base URL
https://{kibana_url}