跟 agent 對話
你們的系統或 App 跟 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 在等你們決定一件事。見交給你們決定的事。
附檔案
- 上傳:
POST /api/v1/files,用multipart/form-data,欄位叫file。最多 8 個。 - 回應會給每個檔案一個
id。 - 送訊息時把它們放進
files:{ "message": "看這份報價", "files": [{ "id": "…" }] }。
agent 回覆裡的檔案,files 會給下載網址。網址長而隨機,請不要公開分享。agent 在這一輪做出來的文件(例如 PDF、Excel)與圖片也會放在這裡。只有新做的檔案會給,agent 只是打開來看的內部檔案不會。對外的串接要先在 API 子分頁的工具權限打開「文件產生」,才做得出文件。
轉真人
API 串接的「轉真人交給」選 你們的客服 時,agent 可以把對話交給你們的人:
- agent 決定轉真人,回覆的
status是handed_off,我們回呼conversation.handoff。 - 之後使用者再傳的訊息,agent 不回。回應的
status是held,我們回呼message.created。 - 你們的客服用
POST /api/v1/conversations/{id}/messages回覆,內文寫{ "as": "human", "message": "…", "by": "客服小美" }。 - 處理完,用
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