跳到內容

跟 agent 對話

你們的系統或 App 跟 agent 對話:送訊息、拿回覆、附檔案。agent 要找真人時,可以交給你們自己的客服。你們的使用者也可以替回覆打分數。

工作流適合固定的流程。問答、客服這類來回的事,用對話比較順。agent 用的知識、技能、工具權限,跟它在其他地方一樣。

你們的系統開始一次工作流、收到結果示意圖
你們的系統送一則訊息,agent 回覆。回覆可以直接拿到、用串流收,或之後回呼。

開一段對話

POST /api/v1/conversations

{ "message": "我的訂單 A123 出貨了嗎?", "end_user": { "id": "cust-42", "name": "王小姐" } }
  • end_user 是你們系統裡的使用者。我們記在對話上,主控台看得到。它不是 Dot Agents 的成員,不帶任何權限。
  • 回應是這一輪的回覆:
{ "conversation_id": "5d1e…", "run_id": "0ee4…", "status": "done", "text": "A123 已經在昨天出貨…", "files": [] }

接著講

POST /api/v1/conversations/{id}/messages,內文一樣是 { "message": "…" }。

三種拿回覆的方式

mode 怎麼拿
wait(預設) 最多等 25 秒。做完就在回應裡。還沒做完回 202,做完再回呼 conversation.reply
stream 用 server-sent events 一段一段送:delta(回覆的字)、working(在查資料)、done(整則回覆)
callback 馬上回 202,做完回呼 conversation.reply

status 是 waiting 時,agent 在等你們決定一件事。見交給你們決定的事。

附檔案

  1. 上傳:POST /api/v1/files,用 multipart/form-data,欄位叫 file。最多 8 個。
  2. 回應會給每個檔案一個 id。
  3. 送訊息時把它們放進 files:{ "message": "看這份報價", "files": [{ "id": "…" }] }。

agent 回覆裡的檔案,files 會給下載網址。網址長而隨機,請不要公開分享。agent 在這一輪做出來的文件(例如 PDF、Excel)與圖片也會放在這裡。只有新做的檔案會給,agent 只是打開來看的內部檔案不會。對外的串接要先在 API 子分頁的工具權限打開「文件產生」,才做得出文件。

轉真人

API 串接的「轉真人交給」選 你們的客服 時,agent 可以把對話交給你們的人:

  1. agent 決定轉真人,回覆的 status 是 handed_off,我們回呼 conversation.handoff。
  2. 之後使用者再傳的訊息,agent 不回。回應的 status 是 held,我們回呼 message.created。
  3. 你們的客服用 POST /api/v1/conversations/{id}/messages 回覆,內文寫 { "as": "human", "message": "…", "by": "客服小美" }。
  4. 處理完,用 POST /api/v1/conversations/{id}/release 交還 agent。

選「不提供」時,agent 不會轉真人,會說明它能做什麼。

看整段對話

GET /api/v1/conversations/{id} 列出每一則訊息。author 是 end_user(你們的使用者)、agent 或 human(真人)。

替回覆打分數

POST /api/v1/runs/{run_id}/feedback

{ "rating": "down", "note": "答非所問" }

設定的人在主控台看得到這些回饋,可以拿來改進 agent。

相關頁

本頁對應 v0.168.0