> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.datagol.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream a Message to the Agent

> Sends a user message and streams the AI response as Server-Sent Events (SSE). This endpoint is on the AI Core service (ai.datagol.ai).



## OpenAPI

````yaml /openapi/agents-openapi.yaml post /ai/api/v2/messages/streaming
openapi: 3.1.0
info:
  title: DataGOL Custom Agents API
  description: >-
    Complete API for creating, configuring, sharing, and interacting with Custom
    AI Agents on the DataGOL platform. Covers agent CRUD, permissions,
    conversations, and streaming.
  version: 1.0.0
  contact:
    name: DataGOL Support
    url: https://datagol.ai
servers:
  - url: https://be.datagol.ai
    description: Backend API (Production) — agent management, conversations, permissions
  - url: https://ai.datagol.ai
    description: AI Core (Production) — streaming, chat completion, conversation naming
security:
  - ServiceAccountAuth: []
  - BearerAuth: []
tags:
  - name: Custom Agents
    description: Create, read, and manage Custom AI Agents.
  - name: Permissions
    description: View and manage who has access to an agent.
  - name: Conversations
    description: Open and list conversation sessions backed by an agent.
  - name: Messaging
    description: Send messages and stream AI responses.
  - name: Reference Data
    description: >-
      Lookup APIs for workspaces, connectors, and team members used when
      building agent configs.
paths:
  /ai/api/v2/messages/streaming:
    post:
      tags:
        - Messaging
      summary: Stream a Message to the Agent
      description: >-
        Sends a user message and streams the AI response as Server-Sent Events
        (SSE). This endpoint is on the AI Core service (ai.datagol.ai).
      operationId: streamMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamingMessageRequest'
            example:
              agentType: CustomAgent
              type: CustomAgent
              conversationId: ae5ee879-e967-45e4-bca0-c6c78d10bd23
              message: Summarise the data
              parameters:
                customAgentId: 1526da2b-3264-4118-b141-87857369b0bd
              selectedLlmModel: gpt-5.2
      responses:
        '200':
          description: >
            Below is the mapping of each event type, its structure, and required
            frontend handling.


            | Response Type (`response_type`) | Content Structure (`content`) |
            Frontend Behavior & Handling Rules |

            | :--- | :--- | :--- |

            | **`message_id`** | `integer` (e.g., `7903`) | **First event of
            every agent turn.** Provides the server-assigned numeric ID. Stash
            it if you need a handle; otherwise, safely ignore it. |

            | **`text`** | `string` (Markdown chunk) | **Streaming text chunk.**
            Delivered incrementally. **Append** each chunk to the in-progress
            message; do not replace it. |

            | **`tool_call`** | `object` (`{action, input, tool_call_id}`) |
            **Agent invoking a tool.** Render an inline "running tool..."
            indicator in the UI. Track `tool_call_id`. |

            | **`subagent_task_end`** | `object` (`{tool_call_id,
            tool_response}`) | **Tool finished.** Match `tool_call_id` to stop
            the spinner. <br><br>**CRITICAL:** `tool_response[0].text` is a
            **double-encoded JSON string**. You must call `JSON.parse()` a
            *second* time to extract the actual structured payload. |

            | **`html`** | `string` (HTML/SVG fragment) | **Rich
            visualization.** <br><br>**SECURITY RULE:** Render this content
            strictly inside a sandboxed `<iframe srcdoc="...">` so encapsulated
            styles do not leak. **Do not** inject via `dangerouslySetInnerHTML`.
            |

            | *(Any other type)* | *Varies / Unknown* |
            **Forward-compatibility.** Safely ignore unlisted types to prevent
            application crashes as new events are introduced. |
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/StreamEvent'
              examples:
                message_id:
                  summary: Turn starts — server assigns a message id
                  value: |
                    data: {"response_type":"message_id","content":7903}
                text_chunk:
                  summary: Incremental assistant text chunk
                  value: >
                    data: {"response_type":"text","content":"Here is a summary
                    of the top 5 customers:\n\n"}
                tool_call:
                  summary: Agent invokes an MCP tool
                  value: >
                    data:
                    {"response_type":"tool_call","content":{"action":"sales-activity_get_table_schema","input":{"workbook_id":"ca45078d-ed26-4752-a7a7-4aed24af033c"},"tool_call_id":"toolu_01XJ5vBNkPboGSf3iD8Vpxyz"}}
                subagent_task_end:
                  summary: >-
                    Tool result returned (tool_response[0].text is
                    double-JSON-encoded)
                  value: >
                    data:
                    {"response_type":"subagent_task_end","content":{"tool_call_id":"toolu_01XJ5vBNkPboGSf3iD8Vpxyz","tool_response":[{"type":"text","text":"{\"columns\":[{\"id\":\"col_1\",\"title\":\"order_id\",\"type\":\"TEXT\"}],\"primaryKeyColumnName\":\"col_1\"}"}]}}
                html_visualization:
                  summary: Rich HTML chart or table visualization
                  value: >
                    data: {"response_type":"html","content":"<div
                    style=\"font-family:sans-serif\"><table><thead><tr><th>Customer</th><th>Revenue</th></tr></thead><tbody><tr><td>Acme
                    Corp</td><td>$1,200,000</td></tr></tbody></table></div>"}
components:
  schemas:
    StreamingMessageRequest:
      type: object
      required:
        - agentType
        - type
        - conversationId
        - message
        - parameters
        - selectedLlmModel
      properties:
        agentType:
          type: string
          enum:
            - CustomAgent
          description: Must be CustomAgent.
        type:
          type: string
          enum:
            - CustomAgent
          description: Duplicates agentType for internal routing.
        conversationId:
          type: string
          format: uuid
          description: The conversation ID returned by POST /ai/api/v2/conversations.
          example: ae5ee879-e967-45e4-bca0-c6c78d10bd23
        message:
          type: string
          description: The user's message text to send to the agent.
          example: Summarise the data
        parameters:
          type: object
          properties:
            customAgentId:
              type: string
              format: uuid
              description: >-
                UUID of the Custom Agent. Must match the agent backing this
                conversation.
              example: 1526da2b-3264-4118-b141-87857369b0bd
        selectedLlmModel:
          type: string
          description: >-
            Model for this specific message. Can be changed per message to
            switch models mid-conversation.
          example: gpt-5.2
    StreamEvent:
      discriminator:
        propertyName: response_type
        mapping:
          message_id:
            $ref: '#/components/schemas/StreamEventMessageId'
          text:
            $ref: '#/components/schemas/StreamEventText'
          tool_call:
            $ref: '#/components/schemas/StreamEventToolCall'
          subagent_task_end:
            $ref: '#/components/schemas/StreamEventSubagentTaskEnd'
          html:
            $ref: '#/components/schemas/StreamEventHtml'
    StreamEventMessageId:
      type: object
      description: >
        First event of every agent turn. Contains the server-assigned numeric id
        for this message. Stash it if you need a handle to the in-progress
        message; otherwise you can safely ignore it.
      properties:
        response_type:
          type: string
          enum:
            - message_id
        content:
          type: integer
          description: Server-assigned message id.
          example: 7903
    StreamEventText:
      type: object
      description: >
        A streaming text chunk from the assistant. Delivered incrementally —
        often a few words or one bullet point at a time, with markdown
        formatting. **Append** each chunk to the in-progress assistant message;
        do not replace it.
      properties:
        response_type:
          type: string
          enum:
            - text
        content:
          type: string
          description: Partial assistant text chunk (markdown).
          example: |+
            Here is a summary of the top 5 customers by revenue:

    StreamEventToolCall:
      type: object
      description: >
        The agent is invoking a tool (e.g. an MCP tool or built-in capability).
        Render an inline "running tool …" indicator in the UI. When the matching
        `subagent_task_end` event arrives (same `tool_call_id`), mark the tool
        as finished.
      properties:
        response_type:
          type: string
          enum:
            - tool_call
        content:
          $ref: '#/components/schemas/StreamEventToolCallContent'
    StreamEventSubagentTaskEnd:
      type: object
      description: >
        The tool invocation identified by `tool_call_id` has finished.
        `tool_response[0].text` is a JSON-encoded string — call `JSON.parse` on
        it again to obtain the actual structured payload. Mark the matching
        `tool_call` indicator as done.
      properties:
        response_type:
          type: string
          enum:
            - subagent_task_end
        content:
          $ref: '#/components/schemas/StreamEventSubagentTaskEndContent'
    StreamEventHtml:
      type: object
      description: >
        A complete HTML or SVG fragment produced by the agent — typically a
        chart, data table, or other rich visualization. Render it inside a
        sandboxed `<iframe srcdoc="…">` so its `<style>` blocks do not leak into
        the host page and any embedded scripts cannot access the host frame. Do
        **not** inject it via `dangerouslySetInnerHTML` or equivalent.
      properties:
        response_type:
          type: string
          enum:
            - html
        content:
          type: string
          description: Self-contained HTML/SVG markup ready for sandboxed rendering.
          example: >-
            <div
            style="font-family:sans-serif"><table><thead><tr><th>Customer</th><th>Revenue</th></tr></thead><tbody><tr><td>Acme
            Corp</td><td>$1,200,000</td></tr></tbody></table></div>
    StreamEventToolCallContent:
      type: object
      description: Payload for a tool_call event.
      properties:
        action:
          type: string
          description: Name of the tool being invoked (e.g. the MCP tool name).
          example: sales-activity_get_table_schema
        input:
          type: object
          description: Argument map passed to the tool. Shape varies per tool.
          example:
            workbook_id: ca45078d-ed26-4752-a7a7-4aed24af033c
        tool_call_id:
          type: string
          description: >
            Opaque identifier assigned by the server to this tool invocation.
            Match it against the `tool_call_id` in the corresponding
            `subagent_task_end` event to correlate input and output.
          example: toolu_01XJ5vBNkPboGSf3iD8Vpxyz
    StreamEventSubagentTaskEndContent:
      type: object
      description: Payload for a subagent_task_end event.
      properties:
        tool_call_id:
          type: string
          description: >
            Matches the `tool_call_id` from the earlier `tool_call` event for
            this invocation.
          example: toolu_01XJ5vBNkPboGSf3iD8Vpxyz
        tool_response:
          type: array
          description: >
            Result from the tool. Always an array with a single element of type
            `text`. The `text` field is a **double-encoded JSON string** — call
            `JSON.parse(tool_response[0].text)` to get the actual payload (e.g.
            a workbook schema, query result, etc.).
          items:
            $ref: '#/components/schemas/StreamEventToolResponse'
    StreamEventToolResponse:
      type: object
      description: >-
        A single item in the tool_response array inside a subagent_task_end
        event.
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          description: >
            JSON-encoded string containing the actual tool result payload. Call
            `JSON.parse(text)` a second time to obtain the structured data (e.g.
            a workbook schema object).
          example: '{"columns":[{"id":"col_1","title":"order_id","type":"TEXT"}]}'
  securitySchemes:
    ServiceAccountAuth:
      type: apiKey
      in: header
      name: x-auth-token
      description: >
        For server-to-server or automated access, use a DataGOL Service Account
        key.
                Pass it via the `x-auth-token` header instead of `Authorization`:
                `x-auth-token: <service-account-key>`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT token issued by the DataGOL Identity Provider. Embed `Authorization:
        Bearer <token>` in every request. Tokens contain `companyId`, `userId`,
        `roles`, and `permissions` claims.

````