Send chat message Technical Preview; added in 9.2.0

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

Spaces method and path for this operation:

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.

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

  • 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 application/json

    Indicates a successful response

POST /api/agent_builder/converse 
curl \
 --request POST 'https://localhost:5601/api/agent_builder/converse' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"input":"What is Elasticsearch?","agent_id":"elastic-ai-agent","connector_id":"my-connector-id"}'
Request example
Example request to send a message to the agent as a part of the conversation 
{
  "input": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent",
  "connector_id": "my-connector-id"
}
Response examples (200)
Example response containing the chain of events representing a conversation with the agent 
{
  "steps": [
    {
      "type": "reasoning",
      "reasoning": "Searching for official documentation or content that explains what Elasticsearch is"
    },
    {
      "type": "tool_call",
      "params": {
        "query": "what is elasticsearch definition overview introduction"
      },
      "results": [
        {
          "data": {
            "message": "Could not figure out which index to use"
          },
          "type": "error"
        }
      ],
      "tool_id": "platform.core.search",
      "progression": [
        {
          "message": "Selecting the best target for this query"
        }
      ],
      "tool_call_id": "tooluse_shOdUwKIRwC9YhqGzeg0cQ"
    }
  ],
  "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‑tuned relevancy, and powerful analytics that scale with ease."
  },
  "conversation_id": "696ccd6d-4bff-4b26-a62e-522ccf2dcd16"
}