跳到內容

開發與整合

寫給你們公司的工程師。用 API 串接的金鑰呼叫 Dot Agents。可以開始工作流、收結果,把關卡放進你們的簽核流程。附一個十分鐘就能跑通的範例。

這一區寫給要把 Dot Agents 接進公司系統的工程師。你們的系統送 HTTP 請求就能用,不需要自己的 AI 能力。知識、技能、權限與稽核都留在 Dot Agents,由設定的人在主控台管理。

你們的系統開始一次工作流、收到結果示意圖
你們的系統開始一次工作流。做完時,結果送回你們的系統,也可以用查詢拿到。

選哪一種接法

你想要 用什麼 說明
開始一個工作流、拿到結果 API 串接 見跑工作流
你們的 App 或系統跟 agent 對話 API 串接 見跟 agent 對話
規格書這類文件一改版就送進知識庫 API 串接 見知識同步
內部網站上的對話窗,給同事用 網站小工具+對內的 API 串接 見給員工用的小工具
主管在你們的系統裡核准 API 串接+關卡交給外部系統 見交給你們決定的事
不寫程式,只要開始一次 工作流的 Webhook 網址 拿不到結果。見工作流的開始方式
agent 執行工具前,先問你們的系統 外部審查 3 秒內回覆允許或拒絕。見外部審查
官網上的對話窗,認得登入的會員 網站小工具+會員資料查詢 見會員資料查詢

開始之前

請設定的人在主控台建一個 API 串接,並給你三樣東西:

  • 金鑰:dak_ 開頭。
  • 簽章金鑰:whsec_ 開頭,用來驗證回呼。
  • 工作流的編號:工作流網址最後那一段。串接的 能開始的工作流 要打開它。

十分鐘跑通

  1. 開始一次:
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}}'
  1. 回應是這一次的狀態。run 是第幾次,跟執行紀錄上的編號一樣:
{ "id": "3f2c…", "run": 12, "status": "running", "outputs": null, "waiting": [] }
  1. 做完時,我們把 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