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

# AI 語音代理

> 選取可供 REST API 執行 AI 通話的儀表板管理代理。

<Note>
  **私人測試版。** 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。
</Note>

AI 語音代理定義單次通話與批次使用的對話行為。代理是在 Brightalk 儀表板中設定及管理。

## 符合資格的條件

`GET /agents` 只傳回組織擁有、且目前符合對外 AI 撥號資格的代理。符合資格表示代理為有效、已設定供對外撥號使用、已可提供通話服務，並與組織內已驗證且可用的對外撥號路由關聯。

此端點接受 `calls:read` 或 `batches:read` 任一權限，權限模式為 `anyOf`。單次通話整合通常使用 `calls:read`；只執行批次的整合則可用 `batches:read` 讀取同一份符合資格的代理目錄。

若清單中沒有某個代理，就不可使用該代理建立通話或批次。請重新列出目錄，不要無限期快取可用性。

## 唯讀目錄

REST API 僅提供精簡的選取資料：`id`、`name`、`description`、`language` 與 `availability`。傳回項目的 `availability` 為 `available`。本 API 無法建立或修改代理定義。

## 選取代理

將傳回的 `id` 作為 `POST /calls` 或 `POST /batches` 的 `agent_id`。請依收話人流程選擇具適合語言及儀表板管理行為的代理。Automation 會使用自身設定的代理，因此 `POST /automation-runs` 不接受 `agent_id`。