Send chat message

Base URL: https://{kibana_url}

POST /api/agent_builder/converse
POST /s/{space_id}/api/agent_builder/converse

Refer to Spaces for more information.

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

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Header parameters

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.
action enum: 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: 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.
capabilities object: Controls agent capabilities during conversation. Currently supports visualization rendering for tabular tool results.
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: 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.
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.

Response

200

Indicates a successful response

application/json

Base URL: https://{kibana_url}

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

Request Console 1 / 2 languages

Example request to create a public conversation

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

Generated from the API spec

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

Generated from the API spec

Response

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

{
  "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 Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

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

Generated from the API spec

Response

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

{
  "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 Console 1 / 2 languages

Example using inference_id (mutually exclusive with connector_id)

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

Generated from the API spec

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

Generated from the API spec

Response

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

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

Required authorization

Authentication

Header parameters

Request body { }

Response

Request body