開發與整合
寫給你們公司的工程師。用 API 串接的金鑰呼叫 Dot Agents。可以開始工作流、收結果,把關卡放進你們的簽核流程。附一個十分鐘就能跑通的範例。
這一區寫給要把 Dot Agents 接進公司系統的工程師。你們的系統送 HTTP 請求就能用,不需要自己的 AI 能力。知識、技能、權限與稽核都留在 Dot Agents,由設定的人在主控台管理。
選哪一種接法
| 你想要 | 用什麼 | 說明 |
|---|---|---|
| 開始一個工作流、拿到結果 | API 串接 | 見跑工作流 |
| 你們的 App 或系統跟 agent 對話 | API 串接 | 見跟 agent 對話 |
| 規格書這類文件一改版就送進知識庫 | API 串接 | 見知識同步 |
| 內部網站上的對話窗,給同事用 | 網站小工具+對內的 API 串接 | 見給員工用的小工具 |
| 主管在你們的系統裡核准 | API 串接+關卡交給外部系統 | 見交給你們決定的事 |
| 不寫程式,只要開始一次 | 工作流的 Webhook 網址 | 拿不到結果。見工作流的開始方式 |
| agent 執行工具前,先問你們的系統 | 外部審查 | 3 秒內回覆允許或拒絕。見外部審查 |
| 官網上的對話窗,認得登入的會員 | 網站小工具+會員資料查詢 | 見會員資料查詢 |
開始之前
請設定的人在主控台建一個 API 串接,並給你三樣東西:
- 金鑰:
dak_開頭。 - 簽章金鑰:
whsec_開頭,用來驗證回呼。 - 工作流的編號:工作流網址最後那一段。串接的 能開始的工作流 要打開它。
十分鐘跑通
- 開始一次:
curl -X POST "https://<你的網址>/api/v1/workflows/<工作流編號>/runs" \
-H "Authorization: Bearer dak_…" \
-H "Idempotency-Key: PO-0042" \
-H "Content-Type: application/json" \
-d '{"inputs": {"po_no": "PO-0042", "amount": 82000}}'
- 回應是這一次的狀態。
run是第幾次,跟執行紀錄上的編號一樣:
{ "id": "3f2c…", "run": 12, "status": "running", "outputs": null, "waiting": [] }
- 做完時,我們把
workflow_run.finished送到串接的回呼網址。沒有回呼網址也可以查詢:
curl "https://<你的網址>/api/v1/workflow-runs/3f2c…" -H "Authorization: Bearer dak_…"
完整規格在 https://<你的網址>/api/v1/openapi.json。
用 SDK
我們提供 JavaScript 與 Python 各一個檔,不用裝其他套件。每一支 API 都有對應的方法,也包含驗證回呼簽章的函式。地端版一樣從你自己的網址下載:
curl -O "https://<你的網址>/sdk/dotagents.mjs" # Node.js 18 以上、Deno、Bun
curl -O "https://<你的網址>/sdk/dotagents.py" # Python 3.8 以上
JavaScript:
import { DotAgents } from './dotagents.mjs';
const dot = new DotAgents({ baseUrl: 'https://<你的網址>', apiKey: process.env.DOT_API_KEY });
const run = await dot.startRun('<工作流編號>', { inputs: { po_no: 'PO-0042' }, idempotencyKey: 'PO-0042' });
Python:
from dotagents import DotAgents
dot = DotAgents(base_url="https://<你的網址>", api_key=os.environ["DOT_API_KEY"])
run = dot.start_run("<工作流編號>", inputs={"po_no": "PO-0042"}, idempotency_key="PO-0042")
錯誤會丟出 DotAgentsError,帶 status 與 code,見錯誤與上限。
這一區的頁面
本區頁面
本頁對應 v0.168.0