Python SDK 參考

DataGen Python SDK 的完整 API 參考

​

安裝

pip install datagen-python-sdk

需要 Python 3.10 以上版本。

​

用戶端設定

from datagen_sdk import DatagenClient

client = DatagenClient(
    api_key=None,           # 預設：從 DATAGEN_API_KEY 環境變數讀取
    base_url="https://api.datagen.dev",
    timeout=30,             # 請求逾時秒數
    retries=0,              # 請求失敗時的重試次數
    backoff_seconds=0.5     # 初始退避時間（以 2^attempt 倍數指數成長）
)

參數	型別	預設值	說明
api_key	Optional[str]	None	API key。未提供時改用 DATAGEN_API_KEY 環境變數
base_url	str	"https://api.datagen.dev"	DataGen API base URL
timeout	int	30	請求逾時秒數
retries	int	0	重試次數
backoff_seconds	float	0.5	重試的初始退避時間

---

​

工具執行

​

execute_tool

以別名執行 MCP 工具。

result = client.execute_tool(
    tool_alias_name: str,
    parameters: Optional[Dict[str, Any]] = None
) -> Any

參數	型別	必填	說明
tool_alias_name	str	是	工具別名（例如 "mcp_Gmail_gmail_send_email"）
parameters	Dict[str, Any]	否	工具專屬參數

回傳： 工具執行結果（型別依工具而定）。

例外： DatagenAuthError、DatagenToolError、DatagenHttpError

---

​

自訂工具部署

​

deploy_custom_tool

將 Python 工作流程部署為 API 端點。

result = client.deploy_custom_tool(
    name: str,
    code: str,
    description: Optional[str] = None,
    input_schema: Optional[Dict[str, Any]] = None,
    output_vars: Optional[List[str]] = None,
    expected_tools: Optional[List[str]] = None,
    additional_imports: Optional[List[str]] = None,
    deployment_type: str = "private",
    default_input_vars: Optional[Dict[str, Any]] = None,
    mcp_server_names: Optional[List[str]] = None,
    required_secrets: Optional[List[str]] = None,
) -> Dict[str, Any]

參數	型別	必填	預設值	說明
name	str	是	—	工具的 API 名稱
code	str	是	—	要部署的 Python 程式碼
description	str	否	None	工具說明
input_schema	Dict	否	None	輸入的 OpenAPI/JSON Schema
output_vars	List[str]	否	None	輸出變數名稱
expected_tools	List[str]	否	None	需要的 MCP 工具
additional_imports	List[str]	否	None	Python 套件
deployment_type	str	否	"private"	"private" 或 "public"
default_input_vars	Dict	否	None	預設輸入值
mcp_server_names	List[str]	否	None	MCP server 名稱
required_secrets	List[str]	否	None	需要的 secret 名稱

回傳： 含 deployment_uuid 與部署細節的 Dict。

例外： DatagenDeploymentError

​

update_custom_tool

更新既有的自訂工具。只會更新有提供的欄位。

result = client.update_custom_tool(
    deployment_uuid: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    code: Optional[str] = None,
    input_schema: Optional[Dict[str, Any]] = None,
    output_vars: Optional[List[str]] = None,
    default_input_vars: Optional[Dict[str, Any]] = None,
    additional_imports: Optional[List[str]] = None,
    expected_tools: Optional[List[str]] = None,
    required_secrets: Optional[List[str]] = None,
) -> Dict[str, Any]

參數	型別	必填	說明
deployment_uuid	str	是	要更新之工具的 UUID
name	str	否	更新後的名稱
description	str	否	更新後的說明
code	str	否	更新後的 Python 程式碼
input_schema	Dict	否	更新後的輸入 schema
output_vars	List[str]	否	更新後的輸出變數
default_input_vars	Dict	否	更新後的預設輸入
additional_imports	List[str]	否	更新後的匯入套件
expected_tools	List[str]	否	更新後需要的工具
required_secrets	List[str]	否	更新後需要的 secret

回傳： 含更新後部署細節的 Dict。

例外： DatagenDeploymentError

​

get_custom_tool

取得自訂工具的細節。

result = client.get_custom_tool(deployment_uuid: str) -> Dict[str, Any]

​

list_custom_tools

列出所有自訂工具。

result = client.list_custom_tools(
    sort_by: str = "created_at",
    order_by: str = "desc",
    skip: int = 0,
    limit: int = 100,
) -> List[Dict[str, Any]]

參數	型別	預設值	說明
sort_by	str	"created_at"	排序欄位
order_by	str	"desc"	"asc" 或 "desc"
skip	int	0	分頁位移
limit	int	100	最多回傳筆數

---

​

自訂工具執行

​

run_custom_tool

以同步方式執行自訂工具（會等待執行完成）。

result = client.run_custom_tool(
    deployment_uuid: str,
    input_vars: Optional[Dict[str, Any]] = None,
    execution_timeout: int = 120,
) -> Dict[str, Any]

參數	型別	必填	預設值	說明
deployment_uuid	str	是	—	工具 UUID
input_vars	Dict	否	None	輸入變數
execution_timeout	int	否	120	最長執行秒數

回傳： 含 run_uuid、status 與 output_vars 的 Dict。

例外： DatagenDeploymentError

​

run_custom_tool_async

以非同步方式執行自訂工具（立即回傳）。

result = client.run_custom_tool_async(
    deployment_uuid: str,
    input_vars: Optional[Dict[str, Any]] = None,
    execution_timeout: int = 120,
) -> Dict[str, Any]

參數與 run_custom_tool 相同。

回傳： 含 run_uuid 與 status: "pending" 的 Dict。

例外： DatagenDeploymentError

​

check_run_status

檢查自訂工具執行的狀態。

result = client.check_run_status(run_uuid: str) -> Dict[str, Any]

回傳： 含 run_uuid 與 status（"pending"、"running"、"completed" 或 "failed"）的 Dict。

​

get_run

取得自訂工具執行的完整細節，包含輸出。

result = client.get_run(run_uuid: str) -> Dict[str, Any]

回傳： 含完整執行細節（包括 output_vars）的 Dict。

​

wait_for_run

持續輪詢，直到非同步執行完成或失敗。

result = client.wait_for_run(
    run_uuid: str,
    timeout: int = 300,
    poll_interval: float = 2.0,
) -> Dict[str, Any]

參數	型別	預設值	說明
run_uuid	str	—	Run UUID
timeout	int	300	最長等待秒數
poll_interval	float	2.0	每次檢查狀態的間隔秒數

回傳： 含 output_vars 的最終執行結果。

例外： 執行失敗或逾時時拋出 DatagenDeploymentError。

---

​

Secret 管理

​

list_secrets

列出所有 secret（不會回傳值）。

result = client.list_secrets() -> List[Dict[str, Any]]

回傳： secret 中繼資料清單（name、masked_value、provider 等）。

​

set_secret

建立或更新 secret。

result = client.set_secret(
    name: str,
    value: str,
    display_name: Optional[str] = None,
    description: Optional[str] = None,
    category: str = "api_key",
    force: bool = False,
) -> Dict[str, Any]

參數	型別	必填	預設值	說明
name	str	是	—	Secret 名稱（英數字、底線、連字號）
value	str	是	—	Secret 值
display_name	str	否	None	易讀的顯示名稱
description	str	否	None	說明
category	str	否	"api_key"	Secret 類別
force	bool	否	False	設為 True 時更新既有的 secret

例外： secret 已存在且 force=False 時拋出 DatagenSecretError。

---

​

錯誤類型

所有例外都繼承自 DatagenError。

例外	說明
DatagenError	基礎例外類別
DatagenAuthError	身分驗證失敗（401/403）或缺少 API key
DatagenToolError	工具執行失敗
DatagenHttpError	HTTP 層級錯誤（4xx/5xx）
DatagenDeploymentError	自訂工具部署或執行失敗
DatagenSecretError	Secret 管理錯誤

from datagen_sdk import (
    DatagenClient,
    DatagenError,
    DatagenAuthError,
    DatagenToolError,
    DatagenHttpError,
    DatagenDeploymentError,
    DatagenSecretError,
)