Send chat message Technical Preview

View as Markdown
POST /api/agent_builder/converse
Api key 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.

  • attachments array[object]

    Optional attachments to send with the message.

    Hide attachments attributes Show attachments attributes object
    • data object Required

      Payload of the attachment.

      Additional properties are allowed.

    • hidden boolean

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

    • id string

      Optional id for the attachment.

    • type string Required

      Type of the attachment.

  • browser_api_tools array[object]

    Optional browser API tools to be registered as LLM tools with browser.* namespace. These tools execute on the client side.

    Hide browser_api_tools attributes Show browser_api_tools attributes object
    • description string Required

      Description of what the browser API tool does.

    • id string Required

      Unique identifier for the browser API tool.

  • 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://<KIBANA_URL>/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"
}