使用 AceDataCloud AI Chat v2 建置 Agentic 應用程式

聊天端點可以回傳文字。一個 agent 端點可以檢查檔案、搜尋網頁、呼叫已授權的工具、詢問缺少的資訊，並將每個步驟串流回傳到您的介面。

這就是 AceDataCloud AI Chat v2 背後的實際差異。位於 POST https://api.acedata.cloud/aichat2/conversations 的端點保留了原始對話 API 的簡單請求風格，同時新增了多模態內容區塊、自主多輪工具使用、MCP 連線、結構化串流事件、可恢復的對話，以及對話 CRUD 操作。

AI Chat v2 架構：多模態輸入、agent 工具與結構化事件

本指南著重於從基本聊天機器人轉向正式環境 agent 體驗時重要的整合決策。

AI Chat v2 有哪些改變？

AI Chat v2 是對原始 /aichat/conversations 介面的全面升級。其主要能力包括：

  • **多模態輸入：**在一個 message 陣列中傳送有序的 text、image_url 與 file_url 區塊。
  • **自主工具使用：**模型可以跨多個回合呼叫內建工具與使用者授權的 MCP 伺服器。
  • **具型別的串流：**將文字、工具活動、引用、卡片、成品、錯誤與完成資料呈現為獨立事件。
  • **暫停與恢復：**處理 ask_user_question 事件，並透過工具結果繼續相同的對話。
  • **對話管理：**透過相同端點上的操作進行擷取、批次擷取、更新與刪除。
  • **向後相容的請求：**現有的 model + question 用戶端可以透過變更端點路徑來遷移。

重要的架構轉變是，您的前端不再必須將回應視為單一不透明字串。它可以成為一個由事件驅動的工作區。

從向後相容的路徑開始

風險最低的遷移刻意保持很小。保留現有的請求主體，並且只變更端點：

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "Summarize the three most important points in this request.",
    "stateful": true
  }'

在 JSON 模式中，回應會保留熟悉的結構：

{
  "answer": "...",
  "id": "conversation-uuid"
}

保留回傳的 id。在下一個請求中傳送它，即可繼續受管理的對話，而不需要您的用戶端重新傳送完整訊息歷程。

stateful 預設為 true。當某個回合不應被儲存時，請明確將其設為 false。

這第一個遷移步驟可讓您在引入工具或新的串流 UI 前，驗證驗證機制、模型可用性、延遲與應用程式行為。

當順序與模態很重要時使用 message

較舊的 question 欄位適合純文字提示。對於混合文字與圖片或檔案的內容，請使用有序的 message 陣列：

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

支援的內容區塊如下：

區塊 必要值 最適合的用途
text text 指示、背景資訊與問題
image_url image_url.url 螢幕截圖、圖表、產品圖片
file_url file_url.url PDF、CSV、TXT 與其他檔案

AI Chat v2 仍然識別較舊的 references 陣列。圖片副檔名會被轉換為圖片區塊，而其他 URL 則會成為檔案區塊。這種相容性在遷移期間很有用，但當內容順序重要時，message 是更好的長期契約。

圍繞事件設計用戶端，而不只是 token

使用 accept 標頭選擇回應格式：

用戶端 標頭 格式
瀏覽器 UI text/event-stream Server-Sent Events
Node、Python、CLI、worker application/x-ndjson 每行一個 JSON 事件
簡單後端請求 application/json 最終 {answer, id} 物件

最小化的 Python NDJSON 消費者可以在保留其他事件類型的同時組合文字：

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "Research the topic, cite sources, and return a concise brief.",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers, stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []

    for raw_line in response.iter_lines():
        if not raw_line:
            continue

        event = json.loads(raw_line)
        event_type = event.get("type")

        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

正式環境介面應為每個事件系列定義轉譯器或處理程式：

  • text_delta 更新答案區域。
  • tool_use 與 tool_result 驅動活動狀態與稽核檢視。
  • citation 將來源附加到相關輸出。
  • card 呈現結構化預覽。
  • artifact 公開獨立產生的交付成果。
  • 僅應在所選模型公開 thinking 時處理它。
  • error 終止或恢復目前回合。
  • done 關閉串流，並記錄 token 使用量與終止原因。

如果您的介面只需要最終答案，請串接每個 text_delta 中的 content。這等同於 JSON 模式中回傳的 answer。

讓 agent 使用工具——但要讓活動可見

工具呼叫預設為啟用。AI Chat v2 可以使用內建能力，例如網頁搜尋、頁面擷取與檔案讀取。它也可以掛載使用者授權的 MCP 連線，例如 Google Drive、Notion、Slack 或 GitHub。

串流會清楚公開這個邊界：

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

透過 tool_id 配對 tool_use 與 tool_result。這支援進度指示器、延遲測量、錯誤處理，以及供操作人員閱讀的稽核軌跡。

使用 max_turns 限制單一請求中可發生的自主工具回合數。可接受的範圍為 1–500；文件記載的預設值為 500。較低的值可減少開放式執行。設定 max_turns: 1 會強制單一回應並防止工具呼叫。

實用的部署模式是：

  1. 在產品 UI 中，以沒有工具的 JSON 模式開始。
  2. 新增 NDJSON 或 SSE，並呈現 text_delta 加上 done。
  3. 將工具活動顯示為摺疊式時間軸。
  4. 新增引用與成品呈現。
  5. 根據任務複雜度與成本容忍度，設定明確的 max_turns。
  6. 僅在檢閱其確認模型後，才啟用具寫入能力的連線。

將問題處理為可恢復的狀態機

agent 有時需要釐清資訊。在這種情況下，串流可以發出 ask_user_question，而對話會進入 awaiting_user_input 狀態。

您的用戶端應該：

  1. 儲存對話 id 與 tool_id。
  2. 呈現問題及其選項。
  3. 收集使用者的回應。
  4. 使用相同的對話 id 傳送另一個請求。
  5. 透過 tool_results 回傳待處理工具呼叫的答案。 這比假裝代理程式可以在資訊缺失的情況下完成任務更穩健。它也讓敏感操作的核准閘門成為可能。

分離互動式與無人值守執行

對於 Webhook、CI/CD 工作與監控系統，async: true 會在工作持續進行時傳回任務識別碼。結果可於稍後擷取，或傳送至 HTTP(S) 回呼 URL。

無人值守的寫入存取應明確指定。AI Chat v2 支援 allowed_skills、allowed_mcp_servers 或等效的 unattended_policy 物件。空白清單不授權任何能力。預先授權不會略過連接器本身的安全機制；不支援無人值守確認的技能仍應進行試跑或拒絕寫入。

此區別很重要：連線可用性不等於可以在沒有人在場時採取行動的權限。

正式環境檢查清單

在推出代理式介面之前，請確認：

  • API 憑證儲存在伺服器端，絕不放在瀏覽器程式碼中。
  • 模型名稱來自目前支援的模型清單，而非硬式編碼的假設。
  • 串流剖析器可容忍部分網路區塊與未知事件類型。
  • 工具事件依 tool_id 配對，並記錄錯誤。
  • 有意識地設定 max_turns。
  • 引用與成品 URL 均安全地呈現。
  • ask_user_question 保留足夠的狀態以便稍後恢復。
  • 具備寫入能力的連線保留確認機制或範圍嚴格限定的無人值守授權。
  • done.usage 與 terminal_reason 用於可觀測性。
  • 對話刪除與保留政策符合您的產品需求。

從聊天機器人到代理程式的最短路徑

AI Chat v2 不強制要求全面重寫。先變更端點並保留您目前的請求本文。接著改用多模態 message 區塊、採用結構化串流、顯示工具進度，並加入暫停與恢復處理。

結果是一個可從簡單回答成長為可稽核代理程式工作流程的用戶端——無需為檔案、工具、引用、成品或使用者澄清另外設計通訊協定。

官方資源