Send chat message

Server: 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] 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: 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

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 , capabilities , configuration_overrides , connector_id , conversation_id , execution_id , inference_id , input , prompts , }

Response

Request