Agents

Create agent conversation with streaming response

Start a new conversation with the specified agent and stream the AI response as Server-Sent Events (SSE). The first user message is saved and forwarded to the upstream agent backend; subsequent tokens, tool calls, and lifecycle events are emitted on the open SSE connection.

AG-UI is the sole wire protocol. The request must include chatMode: quick; see AgentStreamSSEEvent for the event vocabulary.

post/agents/{agentKey}/conversations/stream

Path parameters

agentKeystring required

Stable key identifying the agent that owns this conversation.

Request body

querystring required

User prompt for the first turn. Saved as the initial user_query message and sent to the agent backend.

recordIdsstring[]

Optional record ids to include as context for this turn. Each id must be a 24-character MongoDB ObjectId.

chatMode'quick' required

Required execution mode. Scoped agent conversations currently support only quick.

modelKeystring

AI model configuration id for this turn. Omit to use the agent's default model.

modelNamestring

Provider model name (the underlying LLM identifier).

modelFriendlyNamestring

Friendly UI label for the selected model.

timezonestring

Client IANA timezone, such as America/New_York. Helps the agent resolve relative date references in the prompt.

currentTimestring date-time

Client time in ISO 8601 / RFC 3339 format (UTC Z or numeric offset). Sent alongside timezone for time-aware answers.

toolsstring[]

Allowed tool ids for this turn, such as jira.create_issue. Omit to let the agent use its default toolset; send [] to disable tools for this turn.

protocol'agui'

AG-UI is the only supported wire protocol. When present must be "agui". Omitting the field is equivalent — the server always uses the AG-UI vocabulary (see AgentStreamSSEEvent). Kept in the schema for backward compatibility with callers that already send it.

Example request

{
  "query": "what are some latest tech news?",
  "modelKey": "5c1832f4-fa19-4167-b913-307fad3a6551",
  "modelName": "gpt-5.4-mini",
  "modelFriendlyName": "GPT 5.4 mini",
  "chatMode": "quick",
  "timezone": "Asia/Kolkata",
  "currentTime": "2026-05-19T12:58:01+05:30",
  "tools": [],
  "filters": {
    "apps": [
      "2605c882-61d4-4aa2-b480-a68c957c151d",
      "ed6d6cc4-70bd-4838-9aeb-488e910c833a",
      "aeab9ddc-fb9b-47c8-ad98-bd4744e19555"
    ],
    "kb": [
      "8747da12-4724-4a95-ac92-827b88d79647"
    ]
  },
  "appliedFilters": {
    "apps": [
      {
        "id": "2605c882-61d4-4aa2-b480-a68c957c151d",
        "name": "US Headlines, abcnews",
        "nodeType": "app",
        "connector": "RSS"
      },
      {
        "id": "ed6d6cc4-70bd-4838-9aeb-488e910c833a",
        "name": "ABC News RSS",
        "nodeType": "app",
        "connector": "RSS"
      },
      {
        "id": "aeab9ddc-fb9b-47c8-ad98-bd4744e19555",
        "name": "Hacker news rss",
        "nodeType": "app",
        "connector": "RSS"
      }
    ],
    "kb": [
      {
        "id": "8747da12-4724-4a95-ac92-827b88d79647",
        "name": "Siddhant Ota's Private",
        "nodeType": "recordGroup",
        "connector": "KB"
      }
    ]
  }
}

Response

SSE stream (text/event-stream)

Changes

Changed in 1 of the 15 revisions of this API.42115

Aug 12, 20265798f431973a42115See the full diff
- ▲
  the request property chatMode became required
  request-property-became-required
- ▲
  removed the enum value auto of the request property chatMode
  request-property-enum-value-removed
- ▲
  removed the enum value deep of the request property chatMode
  request-property-enum-value-removed
- ▲
  removed the enum value verification of the request property chatMode
  request-property-enum-value-removed
- ●
  added the new CUSTOM enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new HEARTBEAT enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new REASONING_END enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new REASONING_MESSAGE_CONTENT enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new REASONING_MESSAGE_END enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new REASONING_MESSAGE_START enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new REASONING_START enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new RUN_ERROR enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new RUN_FINISHED enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new RUN_STARTED enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new STATE_DELTA enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new STATE_SNAPSHOT enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new STEP_FINISHED enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new STEP_STARTED enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TEXT_MESSAGE_CONTENT enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TEXT_MESSAGE_END enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TEXT_MESSAGE_START enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TOOL_CALL_ARGS enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TOOL_CALL_END enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TOOL_CALL_RESULT enum value to the event response property for the response status 200
  response-property-enum-value-added
- ●
  added the new TOOL_CALL_START enum value to the event response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property agentCapabilities
  new-optional-request-property
- ○
  added the new optional request property protocol
  new-optional-request-property
- ○
  removed the answer_chunk enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the complete enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the connected enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the error enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the metadata enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the restreaming enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the status enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_call enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_calls enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_error enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_execution_complete enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_result enum value from the event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the tool_success enum value from the event response property for the response status 200
  response-property-enum-value-removed
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history