> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK 參考

> DataGen Python SDK 的完整 API 參考

## 安裝

```bash theme={null}
pip install datagen-python-sdk
```

需要 Python 3.10 以上版本。

## 用戶端設定

```python theme={null}
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 工具。

```python theme={null}
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 端點。

```python theme={null}
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`

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

```python theme={null}
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`

取得自訂工具的細節。

```python theme={null}
result = client.get_custom_tool(deployment_uuid: str) -> Dict[str, Any]
```

### `list_custom_tools`

列出所有自訂工具。

```python theme={null}
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`

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

```python theme={null}
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`

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

```python theme={null}
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`

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

```python theme={null}
result = client.check_run_status(run_uuid: str) -> Dict[str, Any]
```

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

### `get_run`

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

```python theme={null}
result = client.get_run(run_uuid: str) -> Dict[str, Any]
```

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

### `wait_for_run`

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

```python theme={null}
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（不會回傳值）。

```python theme={null}
result = client.list_secrets() -> List[Dict[str, Any]]
```

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

### `set_secret`

建立或更新 secret。

```python theme={null}
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 管理錯誤 |

```python theme={null}
from datagen_sdk import (
    DatagenClient,
    DatagenError,
    DatagenAuthError,
    DatagenToolError,
    DatagenHttpError,
    DatagenDeploymentError,
    DatagenSecretError,
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.