Agent API 總覽

透過相容 Anthropic 的串流端點呼叫任何已部署的 DataGen Agent

每一個 DataGen Agent 都提供一個相容 Anthropic Messages API 的端點。把官方 Anthropic SDK（或單純用 curl）指向你的 Agent，它就會以串流方式回應。

POST {base-url}/api/agents/{agent-name}/v1/messages
GET  {base-url}/api/agents/{agent-name}/v1/models

{base-url} 在 DataGen Cloud 是 https://api.datagen.dev；自架（self-hosted） 則是 http://<你的伺服器 IP>:3001 — 詳見下方 Base URL。

背後執行的是完整的 Agent 工作階段，而不是單純呼叫模型：Agent 的檔案與 repo、 skills、MCP 工具與密鑰，在這一回合期間全部都在沙箱中可用。

{agent-name} 是 Agent 詳細頁面上顯示的名稱。以 repo 為來源的 Agent 使用 owner-repo（全小寫，/ 換成 -），例如 datagendev-executive-assistant；以儲存空間為來源的 Agent 則使用你自己命名的 名稱，例如 data-agent。

---

Base URL

本節所有範例都使用 DataGen Cloud 的網址。若你是自架，只要把主機換成自己的 伺服器即可，路徑完全相同。

部署方式	Base URL
DataGen Cloud	https://api.datagen.dev
自架	http://<伺服器 IP>:3001
自架 + TLS	https://<你的網域>

同一個端點在三種部署下的樣子：

# DataGen Cloud
https://api.datagen.dev/api/agents/invoice-agent/v1/messages

# 自架 — 你的伺服器 IP 或主機名稱，連接埠 3001
http://10.0.0.42:3001/api/agents/invoice-agent/v1/messages

# 自架 + TLS — 與網頁介面同一個網域，不需要連接埠
https://datagen.example.com/api/agents/invoice-agent/v1/messages

連接埠 3001 是 API 伺服器，不是網頁介面。 你的團隊用 3000 開啟 DataGen；整合程式呼叫的是 3001。兩者在同一台機器上。如果管理者在 .env 中改過 WASP_BACKEND_PORT，請改用該連接埠 — 也就是 .env 裡 WASP_SERVER_URL 指向的位址。

若採用 TLS 部署模式，反向代理會在同一個網域上同時提供網頁介面與 API，並把 /api/* 轉送到 API 伺服器；此時 3001 不對外開放，base URL 就是你的 DataGen 網域，不需要加連接埠。

請把 base URL 做成設定值，不要寫死在程式碼裡。日後在雲端與自架之間搬移、或替 既有安裝加上 TLS 時，只需要改一個環境變數，而不是每一個呼叫點。

---

第一次呼叫

1. 取得 API key

   在 DataGen 中開啟 Workspace Settings → API Keys 建立金鑰。請在要呼叫的 Agent 所屬的同一個 workspace 中建立 — 金鑰只能存取該 workspace 的 Agent。

2. 送出訊息

   curl -N -X POST "https://api.datagen.dev/api/agents/data-agent/v1/messages" \
     -H "X-Api-Key: $DATAGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "claude-haiku-4-5",
       "stream": true,
       "messages": [{"role": "user", "content": "你能存取哪些資料來源？"}]
     }'
   
3. 保留 conversation id

   回應會帶有 X-Conversation-Id header。下一次呼叫時把它放進 metadata.conversation_id，Agent 就會從上次結束的地方接續。詳見 對話。

兩回合的完整範例

一段可直接複製執行的腳本，涵蓋整個使用流程 — 先提問，再在同一段對話中追問：

cURL

BASE=https://api.datagen.dev
AGENT=data-agent

turn() {  # turn "<訊息>" [conversation-id]
  curl -sN -D /tmp/h -X POST "$BASE/api/agents/$AGENT/v1/messages" \
    -H "X-Api-Key: $DATAGEN_API_KEY" -H "Content-Type: application/json" \
    -d "$(jq -n --arg m "$1" --arg c "${2:-}" '{
          stream: true,
          messages: [{role: "user", content: $m}],
          metadata: (if $c == "" then {} else {conversation_id: $c} end)
        }')" |
  # 逐步印出 Agent 的回覆文字。
  sed -n 's/^data: //p' | jq -rj 'select(.delta.type == "text_delta") | .delta.text'
}

turn "列出你可以存取的資料表。"
CONV=$(grep -i '^x-conversation-id' /tmp/h | tr -d '\r' | awk '{print $2}')

turn "第一個資料表有幾筆資料？" "$CONV"

這段腳本中有三個關鍵：每次請求都要 stream: true、每次只送 一則 使用者訊息 （歷史紀錄來自對話本身，而不是陣列），以及從回應 header 讀出 conversation id 再 帶回去。

像上面這樣由程式連續送出多個回合，可能會快過伺服器的紀錄寫入，導致遺失上一回合 的脈絡。自動化情境請在兩回合之間稍作等待，詳見 接續對話。

---

與 Anthropic API 的三個差異

線路格式與 Anthropic 相同，因此既有的用戶端不必修改即可連線。真正不同的是 語意，有三點特別重要。

只有最後一則使用者訊息會送給 Agent。 伺服器只讀取 messages[] 中最新的 role: "user" 文字，其餘一律捨棄。對話歷史存在伺服器端 — 請傳 metadata.conversation_id，不要重播整個陣列。若陣列的第一則訊息陳述了某項事實、 最後一則詢問該事實，你只會得到「我不知道」。

一律使用串流。 即使 stream: false，回應仍然是 text/event-stream。官方 SDK 的非串流呼叫（messages.create()）並不會因為格式不符而拋出錯誤 — 它會回 傳一個由誤解析文字填充的 Message 物件。請使用 messages.stream() 或對應的 串流 API。

取樣參數會被忽略。 伺服器只讀取 messages、stream、model、system 與 metadata。max_tokens、temperature、top_p、stop_sequences、tools 與 tool_choice 會被接受但直接捨棄 — max_tokens 並非必填。Agent 使用的是它 自己設定的工具，你無法從用戶端注入工具定義。

還有一點與 Anthropic API 無關：Agent 是可以寫入的。

使用 API key 呼叫時預設為唯讀。 以 repo 為來源的 Agent 會讀取 repo，但不會 commit 或 push，除非你送出 metadata.read_only: false — 屆時只要該回合變更了 檔案，就會把 commit 推送到 repo 的預設分支。詳見 寫入連結的 repository。

---

驗證

每一次請求都只需要一個 header：

X-Api-Key: <你的 api key>

請在 DataGen 應用程式的 Workspace Settings → API Keys （/workspace/settings?tab=apikeys）建立金鑰；自架安裝也是同一個頁面。

金鑰決定 workspace。 金鑰是在 workspace 內建立、並屬於該 workspace，因此只能 存取該 workspace 的 Agent — 呼叫其他 workspace 的 Agent 會得到 404，即使你在網 頁介面上看得到它。若要呼叫團隊 workspace 的 Agent，請在選取該 workspace 的狀態下 建立金鑰。沒有任何 header 可以在單次請求中切換 workspace。

金鑰決定權限。 執行一個回合需要 Admin、Builder 或 Operator 金鑰； Viewer 金鑰可以讀取對話，但送出訊息時會得到 403。

金鑰遺失或無法辨識會回傳 401；已撤銷的金鑰回傳 401 {"message": "API key has been revoked"}。

---

模型

curl "https://api.datagen.dev/api/agents/data-agent/v1/models" \
  -H "X-Api-Key: $DATAGEN_API_KEY"

回傳這個 Agent 可使用的模型 id，並把 Agent 設定的預設模型排在第一位：

{
  "data": [
    {"type": "model", "id": "claude-opus-4-7",   "display_name": "Claude Opus 4.7"},
    {"type": "model", "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6"},
    {"type": "model", "id": "claude-haiku-4-5",  "display_name": "Claude Haiku 4.5"}
  ],
  "has_more": false
}

驗證與錯誤語意和 /v1/messages 完全相同，因此在正式送出請求前，這是一個成本很低 的方式，用來確認 Agent 名稱與金鑰是否搭配正確。

若省略 model，解析順序為：automation 指定的模型（當你傳了 metadata.automation）→ Agent 的預設模型。

---

接下來

送出訊息

完整的請求內容、SSE 事件串流與 SDK 範例。

對話

接續、分支、列出、分享與刪除對話。

錯誤與限制

狀態碼、逾時與併發建議。