From 61997f36133208bb8b12c5c8bf3993a21c9c6e10 Mon Sep 17 00:00:00 2001
From: qzl <qzl@example.com>
Date: Fri, 13 Mar 2026 17:27:21 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Agent=20Chat=20Mes?=
 =?UTF-8?q?sages=20=E5=8D=8F=E8=AE=AE=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/protocols/agent-chat-messages.md | 48 +++++++++++++++++++--------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/docs/protocols/agent-chat-messages.md b/docs/protocols/agent-chat-messages.md
index 5a00f1e..dfe62f0 100644
--- a/docs/protocols/agent-chat-messages.md
+++ b/docs/protocols/agent-chat-messages.md
@@ -88,7 +88,7 @@ Frontend                          Backend
    {bucket, path, mime_type, url: signed_url}
 
 2. Send message with binary block
-   POST /api/v1/agent/run
+   POST /api/v1/agent/runs
    content: [
      {type: "text", text: "..."},
      {type: "binary", mimeType: "image/jpeg", url: signed_url}
@@ -104,12 +104,21 @@ Frontend                          Backend
 5. Return history (GET /history)
    <──────────────────────────────
    messages: [{
+     id: "msg-1",
+     seq: 1,
      role: "user",
-     content: [
-       {type: "text", text: "..."},
-       {type: "binary", mimeType: "image/jpeg", url: new_signed_url}
-     ]
-   }]
+     content: "...",
+     metadata: {
+       user_message_attachments: {bucket, path, mime_type}
+     },
+     timestamp: "2026-03-13T10:00:00Z"
+    }]
+
+6. Resolve temporary URL for rendering
+   GET /api/v1/agent/attachments/signed-url?bucket=...&path=...
+   ──────────────────────────────>
+   <──────────────────────────────
+   {bucket, path, url}
 ```
 
 ### Signed URL Format
@@ -146,7 +155,7 @@ interface AgentChatMessageMetadata {
 
 ### Example
 
-**Request (POST /run):**
+**Request (POST /runs):**
 ```json
 {
   "threadId": "thread-123",
@@ -185,16 +194,27 @@ interface AgentChatMessageMetadata {
   "messages": [
     {
       "id": "msg-1",
+      "seq": 1,
       "role": "user",
-      "content": [
-        {"type": "text", "text": "帮我看看这张图"},
-        {
-          "type": "binary",
-          "mimeType": "image/jpeg",
-          "url": "https://xxx.supabase.co/storage/v1/object/sign/agent-files/agent-inputs/u/t/r/img.jpg?token=yyy"
+      "content": "帮我看看这张图",
+      "metadata": {
+        "user_message_attachments": {
+          "bucket": "agent-files",
+          "path": "agent-inputs/u/t/r/img.jpg",
+          "mime_type": "image/jpeg"
         }
-      ]
+      },
+      "timestamp": "2026-03-13T10:00:00Z"
     }
   ]
 }
 ```
+
+**Attachment URL Response (GET /attachments/signed-url):**
+```json
+{
+  "bucket": "agent-files",
+  "path": "agent-inputs/u/t/r/img.jpg",
+  "url": "https://xxx.supabase.co/storage/v1/object/sign/agent-files/agent-inputs/u/t/r/img.jpg?token=yyy"
+}
+```