送出訊息

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

執行一個 Agent 回合，並以 Anthropic 風格的 server-sent events（SSE）串流回傳結果。

以下範例使用 DataGen Cloud（https://api.datagen.dev）。自架安裝請把主機換成自己的伺服器 — 例如 http://10.0.0.42:3001/api/agents/invoice-agent/v1/messages — 其餘完全相同。詳見 Base URL。

請求內容

{
  "model": "claude-haiku-4-5",
  "stream": true,
  "system": "這一回合的額外指示。",
  "messages": [
    { "role": "user", "content": "整理昨天失敗的執行紀錄。" }
  ],
  "metadata": {
    "conversation_id": "support-ticket-4821",
    "stream_tool_calls": true
  }
}

欄位	型別	必填	說明
`messages`	array	是	不可為空。只有最新的 `role: "user"` 文字會被使用。`content` 可以是字串，或 `{"type":"text","text":"…"}` 區塊陣列（以空行串接）。非文字區塊不會被讀取 — 檔案請改用 `metadata.attachments`。
`stream`	boolean	否	請填 `true`。原因見總覽的串流警告。
`model`	string	否	`/v1/models` 回傳的 id 之一。未指定時依序回退到 automation 的模型、Agent 的預設模型。
`system`	string	否	會附加在 Agent 自身的指示之後，不會取代它。
`metadata`	object	否	DataGen 的擴充欄位，見下方。

其他 Anthropic 欄位（max_tokens、temperature、tools 等）會被接受但忽略。

`metadata`

欄位	預設值	作用
`conversation_id`	自動產生	接續的目標對話。可以是任意字串 — 例如你自己的工單編號、討論串 id。詳見對話。
`stream_tool_calls`	`false`	在串流中顯示 `tool_use` 與 `tool_result` 區塊。若用戶端是一般 Anthropic 客戶端（只預期文字），請保持關閉。
`attachments`	`[]`	這一回合的附件檔案，base64 編碼。最多 10 個檔案 / 解碼後 10 MiB。會寫入 Agent 工作目錄下的 `.uploads/<name>`，並在提示中告知 Agent。
`read_only`	使用 API key 時為 `true`	以 repo 為來源的 Agent：可讀取 repo，但不會 commit 或 push。傳 `false` 才允許寫回，詳見寫入連結的 repository。
`isolated`	`false`	在一次性的沙箱中執行，不 clone repo、不掛載 workspace 檔案。
`automation`	—	這個 Agent 上某個啟用中的 automation 名稱。它儲存的提示與模型會成為這一回合的預設值；請求本文中的設定優先。名稱不存在則忽略。
`delivery`	`"sync"`	目前只支援 `"sync"`。`"async"` 會回傳 `501` — 背景執行請使用 webhook 或排程。

內部旗標

metadata.builder 會在 Agent builder 的工作樹中執行（僅限以儲存空間為來源的 Agent，需要 Admin 或 Builder 權限）；metadata.test 會把新對話標記為隱藏的測試執行。兩者是 DataGen 網頁介面在使用的，並非提供給外部整合。

寫入連結的 repository

使用 API key 呼叫時預設為唯讀。 以 repo 為來源的 Agent 會 clone 並讀取 repo，但除非你明確要求，否則不會寫回。若要讓某一回合可以提交它的成果：

"metadata": { "read_only": false }

當 read_only: false 時，只要該回合變更了任何檔案，結束前就會執行 git add -A、以 datagen-agent 身分 commit，並 push 到 repository 的預設分支 — 不是暫存分支。請只在整合的目的就是修改 repository 時才送出這個設定，並考慮讓 Agent 指向預設分支受保護的 repo。

以儲存空間為來源的 Agent 沒有 repository，也不會 push。它們的工作檔案在每一回合開始時重新還原、結束後不會寫回；一個回合的持久產出，是 Agent 寫入 outputs 目錄的內容，這些會發佈到 workspace 的儲存空間。

附件

"metadata": {
  "attachments": [
    { "name": "leads.csv", "mediaType": "text/csv", "dataBase64": "bmFtZSxkb21haW4K…" }
  ]
}

只接受 base64，不要加 data: 前綴。檔名會被正規化為安全的檔名並自動去重複。格式錯誤的項目、以及超出上限的部分會被靜默捨棄，因此若「缺少檔案」對你而言屬於重大問題，請在用戶端先行驗證。附件永遠不會被提交到連結的 repository。

回應

200 OK、Content-Type: text/event-stream，並帶有 X-Conversation-Id 回應 header — 若你沒有自訂 id，請記得把它保存下來。

event: message_start
data: {"type":"message_start","message":{"id":"msg_…","model":"claude-haiku-4-5","usage":{…}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"…"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"以下是摘要…"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{…}}

event: message_stop
data: {"type":"message_stop"}

區塊型別。 text、thinking（其後會跟著 signature_delta），以及在開啟 stream_tool_calls 時的 tool_use（伴隨 input_json_delta）與 tool_result （帶有 tool_use_id、content、is_error）。tool_result 區塊是 DataGen 的擴充，一般 Anthropic 客戶端會忽略它。 顆粒度。 區塊是整塊送達，而非逐 token：每個區塊是 content_block_start + 一次完整的 content_block_delta + content_block_stop。 index 是這一回合的遞增計數。 結束方式。 串流在 message_stop 結束 — 沒有 data: [DONE] 結尾標記。 用量。 message_delta.usage 包含 input_tokens、output_tokens、 cache_read_input_tokens、cache_creation_input_tokens，以及 DataGen 專屬的 total_cost_usd（該回合的美元成本）。

串流開始之後才發生的失敗，會以 SSE error 事件出現在一個已經回傳 200 的回應中： event: error data: {"error":{"type":"api_error","message":"…"}}。請檢查 error 事件，不要只看 HTTP 狀態碼。

範例

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 - \
  -d '{
    "model": "claude-haiku-4-5",
    "stream": true,
    "metadata": {"conversation_id": "support-ticket-4821"},
    "messages": [{"role": "user", "content": "整理昨天失敗的執行紀錄。"}]
  }'

from anthropic import Anthropic

client = Anthropic(
    api_key=DATAGEN_API_KEY,
    # 結尾不要加 /v1 — SDK 會自動補上
    base_url="https://api.datagen.dev/api/agents/data-agent",
)

with client.messages.stream(
    model="claude-haiku-4-5",
    max_tokens=1024,                      # SDK 必填，DataGen 會忽略
    messages=[{"role": "user", "content": "整理昨天失敗的執行紀錄。"}],
    extra_body={"metadata": {"conversation_id": "support-ticket-4821"}},
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print(stream.get_final_message().usage)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.DATAGEN_API_KEY!,
  baseURL: "https://api.datagen.dev/api/agents/data-agent",
});

const stream = client.messages.stream({
  model: "claude-haiku-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "整理昨天失敗的執行紀錄。" }],
  // @ts-expect-error DataGen 擴充欄位
  metadata: { conversation_id: "support-ticket-4821", stream_tool_calls: true },
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

之所以需要 extra_body（Python）與型別轉換（TypeScript），是因為 SDK 把 metadata 定義成 Anthropic 的 {user_id} 物件。這個欄位會原封不動傳給 DataGen。

不使用 SDK 讀取串流

curl -sN … | while IFS= read -r line; do
  case "$line" in
    'data: '*) printf '%s' "$(printf '%s' "${line#data: }" |
      jq -r 'select(.delta.type=="text_delta").delta.text // empty')" ;;
  esac
done

以模型字串指定 Agent

如果你偏好用模型字串而不是 URL 路徑來選擇 Agent：

POST https://api.datagen.dev/api/agents/v1/messages

並帶上 "model": "datagen-agent--data-agent"（或直接用 Agent 名稱）。當用戶端只能設定一個 base URL、而透過模型選單切換 Agent 時特別有用。其餘行為完全相同。

Agent API

中文

請求內容

`metadata`

寫入連結的 repository

附件

回應

範例

不使用 SDK 讀取串流

以模型字串指定 Agent

​請求內容

​metadata

​寫入連結的 repository

​附件

​回應

​範例

​不使用 SDK 讀取串流

​以模型字串指定 Agent

請求內容

`metadata`

寫入連結的 repository

附件

回應

範例

不使用 SDK 讀取串流

以模型字串指定 Agent