Send chat message

Server: https://{kibana_url}

POST /api/agent_builder/converse

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] Route required privileges: agentBuilder:read.

Request

_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.
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.
browser_api_tools [] object: Optional browser API tools to be registered as LLM tools with browser.* namespace. These tools execute on the client side.
configuration_overrides object: Runtime configuration overrides. These override the stored agent configuration for this execution only.
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: 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: 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

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn://api/agent_builder/converse
{
  "input": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent",
  "access_control": {
    "access_mode": "public"
  }
}

curl Shell

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

Example request to create a public conversation

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/agent_builder/converse
{
  "access_control": {
    "access_mode": "public"
  },
  "agent_id": "elastic-ai-agent",
  "connector_id": "my-connector-id",
  "input": "What is Elasticsearch?"
}

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/converse" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "access_control": {
    "access_mode": "public"
  },
  "agent_id": "elastic-ai-agent",
  "connector_id": "my-connector-id",
  "input": "What is Elasticsearch?"
}'

Response

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

Example request to send a message to the agent as a part of the conversation

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/agent_builder/converse
{
  "agent_id": "elastic-ai-agent",
  "connector_id": "my-connector-id",
  "input": "What is Elasticsearch?"
}

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/converse" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "elastic-ai-agent",
  "connector_id": "my-connector-id",
  "input": "What is Elasticsearch?"
}'

Response

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

Example using inference_id (mutually exclusive with connector_id)

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/agent_builder/converse
{
  "agent_id": "elastic-ai-agent",
  "inference_id": "my-inference-endpoint-id",
  "input": "What is Elasticsearch?"
}

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/converse" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "elastic-ai-agent",
  "inference_id": "my-inference-endpoint-id",
  "input": "What is Elasticsearch?"
}'

Response

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

Request { _execution_mode , access_control , action , agent_id , attachments , browser_api_tools , configuration_overrides , connector_id , conversation_id , execution_id , inference_id , input , project_routing , prompts , read_only , reasoning_level , }

Response

Request