新增 SSE 事件参考页并补全事件类型说明

docs/en/docs/portai/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "AI Agent",
+  "collapsible": true,
+  "collapsed": false,
+  "link": null,
+  "position": 2.7,
+  "icon": "cpu"
+}

docs/en/docs/portai/chat/_category_.json

@@ -0,0 +1,7 @@
+{
+  "position": 1,
+  "label": "Conversation",
+  "collapsible": true,
+  "collapsed": false,
+  "link": null
+}

docs/en/docs/portai/chat/continue.md

@@ -0,0 +1,127 @@
+---
+slug: continue
+title: Continue Conversation
+sidebar_position: 3
+language_tabs: false
+toc_footers: []
+includes: []
+search: true
+highlight_theme: ''
+headingLevel: 2
+---
+
+When [Start Conversation](/docs/portai/chat/conversation) returns `status = interrupted`, the Agent is waiting for more information from you. Send your answers via this endpoint and the paused run resumes from the interrupt point, until it succeeds, gets interrupted again, or fails.
+
+A single round of conversation may be interrupted multiple times: if the run returns `interrupted` again after continuing, call this endpoint again with the new `interrupt`.
+
+As with Start Conversation, choose blocking / SSE streaming response mode with the `Accept` header.
+
+<SDKLinks module="agent" klass="AgentContext" method="continue" />
+
+## Request
+
+<table className="http-basic">
+<tbody>
+<tr><td className="http-basic-key">HTTP Method</td><td>POST</td></tr>
+<tr><td className="http-basic-key">HTTP URL</td><td>/v1/babbage/agents/:id/conversations/:chat_uid/messages/:message_id/continue</td></tr>
+</tbody>
+</table>
+
+### Path Parameters
+
+| Name       | Type   | Required | Description                                                              |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| id         | string | YES      | UID of the target Agent                                                  |
+| chat_uid   | string | YES      | `chat_uid` of the interrupted conversation, from the Start Conversation response |
+| message_id | string | YES      | ID of the interrupted message, from the `message_id` in the interrupt response |
+
+### Request Body
+
+| Name                 | Type   | Required | Description                                                                                       |
+| -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| answers_by_tool_call | object | YES      | Answers keyed by `tool_call_id`; must not be empty. Each value is a map of question text → answer |
+
+The structure of `answers_by_tool_call` is "tool call ID → answers for that inquiry", where each answer set is a map of "question → answer":
+
+- The outer key corresponds to `tool_call_id` in the interrupt structure.
+- The inner key is the interrupt question text, and the value is the answer you selected or typed.
+- All questions required by the interrupt must be answered, otherwise an error is returned.
+
+### Request Example
+
+<Tabs groupId="request-example">
+  <TabItem value="curl" label="cURL (JSON)" default>
+
+```bash
+curl -X POST "https://openapi.longbridge.com/v1/babbage/agents/123/conversations/ct_9f2c1a5b/messages/43/continue" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{
+    "answers_by_tool_call": {
+      "call_abc123": {
+        "Which time range would you like to check?": "Past month"
+      }
+    }
+  }'
+```
+
+  </TabItem>
+  <TabItem value="curl-sse" label="cURL (SSE)">
+
+```bash
+curl -N -X POST "https://openapi.longbridge.com/v1/babbage/agents/123/conversations/ct_9f2c1a5b/messages/43/continue" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -d '{
+    "answers_by_tool_call": {
+      "call_abc123": {
+        "Which time range would you like to check?": "Past month"
+      }
+    }
+  }'
+```
+
+  </TabItem>
+</Tabs>
+
+## Response
+
+The response structure is identical to [Start Conversation](/docs/portai/chat/conversation#schemaconversation_response).
+
+### Response Headers
+
+- Content-Type: application/json (blocking)
+- Content-Type: text/event-stream (streaming)
+
+### Response Example
+
+Run succeeded:
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "chat_uid": "ct_9f2c1a5b",
+    "message_id": "43",
+    "status": "succeeded",
+    "answer": "Over the past month, Tesla (TSLA.US)...",
+    "references": [],
+    "elapsed_time": 2.74
+  }
+}
+```
+
+### Response Status
+
+| Status | Description        | Schema                                                                        |
+| ------ | ------------------ | ----------------------------------------------------------------------------- |
+| 200    | Success            | [conversation_response](/docs/portai/chat/conversation#schemaconversation_response) |
+| 400    | Invalid parameters | Empty `answers_by_tool_call`, message not interrupted, missing required interrupt answers, or conversation / message ownership mismatch |
+| 500    | Internal error     | None                                                                          |
+
+### Ownership Checks
+
+To prevent resuming someone else's run, the server verifies that the conversation identified by `chat_uid` belongs to the authenticated member, and the message identified by `message_id` belongs to that conversation. Failing either check returns `400`.

docs/en/docs/portai/chat/conversation.md

@@ -0,0 +1,186 @@
+---
+slug: conversation
+title: Start Conversation
+sidebar_position: 2
+language_tabs: false
+toc_footers: []
+includes: []
+search: true
+highlight_theme: ''
+headingLevel: 2
+---
+
+Ask a question to the specified Agent. You can start a brand-new conversation, or pass the `chat_uid` of an existing one to continue asking in the same conversation.
+
+The Agent generates the answer using capabilities such as market data and account access. When the Agent needs more information or confirmation from you, the run is **interrupted** (`status` is `interrupted`) — send your answers via [Continue Conversation](/docs/portai/chat/continue) to resume it.
+
+Choose the response mode with the `Accept` header: `text/event-stream` streams the run progress and answer via SSE; any other value returns a blocking response with the aggregated final result.
+
+<SDKLinks module="agent" klass="AgentContext" method="conversation" />
+
+## Request
+
+<table className="http-basic">
+<tbody>
+<tr><td className="http-basic-key">HTTP Method</td><td>POST</td></tr>
+<tr><td className="http-basic-key">HTTP URL</td><td>/v1/babbage/agents/:id/conversations</td></tr>
+</tbody>
+</table>
+
+### Path Parameters
+
+| Name | Type   | Required | Description                                        |
+| ---- | ------ | -------- | -------------------------------------------------- |
+| id   | string | YES      | UID of the target Agent; must be a published Agent |
+
+### Request Body
+
+| Name     | Type   | Required | Description                                                                                      |
+| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
+| query    | string | YES      | The user question; must not be empty                                                             |
+| chat_uid | string | NO       | Identifier of an existing conversation. Pass it to continue that conversation; omit to start a new one |
+
+### Request Example
+
+<Tabs groupId="request-example">
+  <TabItem value="curl" label="cURL (JSON)" default>
+
+```bash
+# Blocking: get the final result in one response
+curl -X POST "https://openapi.longbridge.com/v1/babbage/agents/123/conversations" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{
+    "query": "How has Tesla stock performed recently?"
+  }'
+```
+
+  </TabItem>
+  <TabItem value="curl-sse" label="cURL (SSE)">
+
+```bash
+# Streaming: receive run progress and the answer in real time
+curl -N -X POST "https://openapi.longbridge.com/v1/babbage/agents/123/conversations" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -d '{
+    "query": "How has Tesla stock performed recently?"
+  }'
+```
+
+  </TabItem>
+</Tabs>
+
+## Response
+
+### Response Headers
+
+- Content-Type: application/json (blocking)
+- Content-Type: text/event-stream (streaming)
+
+### Response Example
+
+Run succeeded:
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "chat_uid": "ct_9f2c1a5b",
+    "message_id": "42",
+    "status": "succeeded",
+    "answer": "Tesla (TSLA.US) recently...",
+    "references": [
+      { "index": 1, "title": "...", "url": "..." }
+    ],
+    "elapsed_time": 3.21
+  }
+}
+```
+
+Run interrupted (the Agent needs more information from you; the run is paused):
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "chat_uid": "ct_9f2c1a5b",
+    "message_id": "43",
+    "status": "interrupted",
+    "answer": "",
+    "references": null,
+    "elapsed_time": 1.05,
+    "interrupt": {
+      "node_id": "n_ask_human",
+      "tool_call_id": "call_abc123",
+      "questions": [
+        {
+          "question": "Which time range would you like to check?",
+          "options": [
+            { "description": "Past week" },
+            { "description": "Past month" }
+          ],
+          "multi_select": false
+        }
+      ],
+      "message_id": 43,
+      "chat_id": 1001
+    }
+  }
+}
+```
+
+In streaming mode, the server keeps pushing run progress as `event: message` events; the `event` field inside `data` identifies the event type:
+
+```
+event: message
+data: {"event":"chat_started","workflow_run_id":"745910371102313","data":{"chat_uid":"ct_9f2c1a5b","message_id":42}}
+
+event: message
+data: {"event":"message","workflow_run_id":"745910371102313","data":{"text":"Tesla"}}
+
+event: message
+data: {"event":"workflow_finished","workflow_run_id":"745910371102313","data":{"status":"succeeded","elapsed_time":3.21,"outputs":{"answer":"..."}}}
+```
+
+See [SSE Events](/docs/portai/chat/events) for the full list of event types, their payload structures, and parsing guidance.
+
+### Response Status
+
+| Status | Description                       | Schema                                                 |
+| ------ | --------------------------------- | ------------------------------------------------------ |
+| 200    | Success                           | [conversation_response](#schemaconversation_response)  |
+| 400    | Invalid parameters or risk control | Empty `query`, malformed request body, or blocked by content risk control |
+| 500    | Internal error                    | None                                                   |
+
+## Schemas
+
+### conversation_response
+
+<a id="schemaconversation_response"></a>
+
+| Name                 | Type     | Required | Description                                                    |
+| -------------------- | -------- | -------- | -------------------------------------------------------------- |
+| chat_uid             | string   | true     | Conversation identifier, used for follow-up questions and troubleshooting |
+| message_id           | string   | true     | Message ID of this round (as a string)                          |
+| status               | string   | true     | Final run status: `succeeded` / `interrupted` / `failed` / `stopped` |
+| answer               | string   | false    | Final answer text; valid when `status` is `succeeded`           |
+| references           | object[] | false    | Sources referenced by the answer; `null` if none                |
+| elapsed_time         | number   | false    | Run duration in seconds                                         |
+| interrupt            | object   | false    | Present only when `status` is `interrupted`                     |
+| ∟ node_id            | string   | true     | ID of the node that triggered the interrupt                     |
+| ∟ tool_call_id       | string   | true     | Tool call ID of this inquiry; used as the answer key when continuing |
+| ∟ questions          | object[] | true     | Questions you need to answer                                    |
+| ∟∟ question          | string   | true     | Question text                                                   |
+| ∟∟ options           | object[] | false    | Options; empty means free-form answer                           |
+| ∟∟∟ description      | string   | false    | Option text                                                     |
+| ∟∟ multi_select      | boolean  | false    | Whether multiple options may be selected                        |
+| ∟ message_id         | int64    | false    | ID of the paused message                                        |
+| ∟ chat_id            | int64    | false    | ID of the owning conversation                                   |
+| error                | object   | false    | Present only when the run failed                                |
+| ∟ code               | int32    | false    | Error code                                                      |
+| ∟ message            | string   | false    | Error message                                                   |