Agent 工具呼叫粵語語音：畀 AI agent 自己攞聲，由功能開關到 MCP 接入

一句答你： 畀 AI agent 開聲講粵語，重點唔係再寫一個 TTS 模組，而係將語音生成包成一個語義清晰嘅工具：傳入文稿同聲線，傳回音頻連結同狀態；agent 行工具、系統守預算同限流，MCP 接入令呢套工具一接即用。

Key Takeaways

• Agent 嘅語音能力唔係「佢識唱歌」，係一個個明確工具：生成、查進度、取連結——參數要窄，語義要清。
• 工具設計鐵律：窄介面（text、voice）、少數必要參數；擴充用第二個工具，唔好一件工具百個掣。
• 回傳要自帶語義：pending、ready、failed 三種狀態講清楚；agent 先至知道下一步點行。
• 成本閘同用量封頂由系統守：agent 可以重試，但字符預算、每分鐘請求上限係硬規距，唔跟 agent 心情。
• 錯誤要可重試、可告知：限流要延遲再試，文稿超長要分段，唔可以將技術錯誤原樣讀畀用戶聽。
• 每月 5,000 字符（約 21 分鐘音頻）夠試晒「行工具—攞音頻—修正再行」全流程；上生產先至揀付費方案。

Agent 開聲之前：先整清楚要咩

「識講嘢」唔係能力，「識用工具」先係

AI agent 本身識輸出文字；要佢開聲，正確理解係「畀佢一個語音工具，令佢喺適當時機行」。呢個理解決定成套設計：你要設計嘅唔係模型，係工具介面——工具名、參數、回傳、錯誤語義。設計得好，agent 自然用得順；設計得差，agent 就會亂傳參數、重複調用、或者將技術錯誤當答案讀出嚟。

一條簡單判準：要 agent 全靠撞先至用得嘅工具，就係設計得差嘅工具。好嘅語音工具，agent 睇一次工具說明就識行——文稿入、狀態出，冇暗位、冇要估嘅野。

語音係動作，唔係輸出格式

另一個常見誤解係「語音=輸出的一種格式」。喺 agent 架構，語音係動作（action），唔係格式：佢有副作用——用字符、生成檔案、有延遲。所以語音工具要以「動作」規格設計：明確開始、有進度、有完成狀態、有可攞嘅結果。想知 agent 同粵語語音整合嘅另一條路（唔行工具呼叫、用文檔指引方式），可以參考廣東話 TTS MCP agent 整合指南；本篇焦點係行工具呼叫嘅設計路。

語音喺 agent 任務鏈嘅三個典型位

第一個位：任務完成的通知聲。Agent 跑長任務（報表、巡檢、整理），完成時播一段粵語摘要——人唔使望屏都知「做完了」，這係 agent 化報告最自然嘅出口。第二個位：流程中的口播引導。喺需要人手接力嘅流程（審批、確認）上，voice 提示令接力位清晰。第三個位：定時播報。每日固定時間播一段整理好嘅摘要，令 agent 服務由「被查詢先反應」變成「主動開聲」。三個位嘅共同點：文稿由 agent 撰寫，語音工具只負責開聲——分工清楚，鏈路就簡單。

呢三個位都係「一個工具調用」就完成嘅動作；正因為輕，先至值得由 agent 一手包辦——要人手介入嘅話，成本結構就完全唔同。呢個係 agent 語音嘅經濟賬：工具輕到一個調用就開聲，「人手配音」呢個工序先至可以由流程入面徹底拆走。

語音工具嘅介面設計

最小可用工具：一個生成、一個查詢

第一版工具要窄：

兩個工具、四個參數，已經係一個完整可用面。窄介面唔係功能缺陷，係 agent 可用性嘅核心：agent 嘅選擇空間越細，行錯嘅機率越低。生成工具只要文稿同聲線兩個必要參數，其餘（風格、情緒）可以由預設值兜底、後期先加。

參數同聲線代稱

聲線參數要設計成「代稱」：一個短代碼對應一條聲線，由一張固定表映射，唔好要 agent 記長規格。呢個層仲有個品牌位：想 agent 用「品牌把聲」，可以由一段品牌錄音做參考樣本先行「複製聲線」生成，再將條聲線綁入代稱表——細節可以睇聲音複製攻略。聲線代稱表一經定稿，就唔好頻頻改——agent 對工具參數嘅「記憶」嚟自說明位，改一次，全部 agent 都要重新認知。

批量同分段生成嘅介面位

長文本唔可以一次生成，所以要設計一個「分段生成」指引：agent 先攞文稿分段計劃，再逐段行生成工具。批量生成（一次提交多段）係另一層效率工具，適合已穩定嘅大量內容，細節可以參考批量生成工作流程。留意單段文稿有長度上限，超長要「rejected、唔會截斷」——呢個語義要在工具回傳講清晰，令 agent 明知要分段而唔係以為成功。

參數校驗同回傳範例

窄介面要有配套嘅校驗語義：文稿空白、文稿超長、聲線代稱唔存在、批量項目數超額——每一種錯誤都回一個明確原因，唔好得個「失敗」字。校驗係「全有或全無」：批次入面有一項無效，就整批唔會提交，令 agent 唔會以為部分成功而漏做。回傳範例可以寫入工具說明位，令 agent 一望即明白成功與失敗各長咩樣：

• 成功：任務編號、狀態、再查建議。
• 失敗：錯誤原因、可以行嘅下一步。

呢兩個範例放喺工具說明，等 agent 嘅規劃行為由「估」變成「跟說明」，介面就會順。

回傳語義：狀態先行

三種狀態，講清楚

回傳是 agent 嘅世界。最少要回三種狀態：

• pending：任務已接、生成中——agent 應該晚啲再查，唔好即時重複行。
• ready：完成——隨附音頻取回連結。
• failed：失敗——隨附原因同可以行嘅動作（重試、分段、轉聲線）。

狀態語義冇灰位：唔好回「processing」又唔解釋幾時算完，agent 唔知要等幾耐就會狂查。查詢工具回 pending 時附「再查建議」，佢就等返。呢啲係 agent 工程嘅基本禮儀，亦直接決定 agent 嘅行為品質。

音頻連結嘅時效語義

取回連結有時效——過期就失效，要重查攞新連結。呢個語義要在回傳入面寫明（「連結有效期一小時；過期請重新查詢」）。agent 見到過期，重行查詢工具就攞返新連結，唔會攞個死連結傻傻播。呢個位好似小，但係 agent 長時間運行（例如過夜跑任務）最容易撞到嘅坑。

成本閘：硬規距交由系統守

預算、限流同並行上限

Agent 可以自作主張重試，所以預算控制一定唔可以交畀 agent 自己。三道閘：

• 字符預算：每日或每月字符用量上限，到頂就拒。
• 每分鐘請求上限：限流閘，令 agent 唔會狂轟。
• 並行上限：同時在途任務數有上限，令 agent 唔會一次開幾十個生成。

呢三道閘由你在系統配置，唔受 agent 支配；行到上限，工具回清楚語義——「本輪已達字符上限」或「請稍後再試」。Agent 得到正確語義，行為先不會亂。限流細節同 429 語義的通用處理，可以參考API 錯誤碼指南。

適用方案同啟動預算

免費與入門方案冇全速 API；但可以由開戶額度試原型：每月 5,000 字符（月月重置）（約 21 分鐘音頻），夠行「生成—查詢—取連結」幾次循環，驗證工具語義。真係要長期行 agent，上專業或工作室方案先有全速 API；字符包（HK$50 起、每千字符 HK$0.80）係加量嘅靈活補位。成本計法同方案匹配的詳細算法，可以睇粵語 TTS API 成本計算。10 分鐘旁白約 2,400 字符，方案按月繳折算：入門約 HK$1.54、專業約 HK$1.35、工作室約 HK$1.18——以呢個粒度預算，agent 每日用量好容易落到位。

錯誤處理：令 agent 行為可預測

三類錯誤、三種語義

• 可重試錯誤（限流、服務繁忙）——回傳講明「延遲再試」，語義要附建議等待。
• 要修正嘅錯誤（文稿太長、文稿空白、聲線代稱不存在）——回傳講明原因，agent 應該修正參數再行。
• 唔可重試錯誤（預算用盡）——回傳講到明，唔好令 agent 空轉。

三類分清楚，agent 就唔會限流嗰陣即刻重試（越試越糟）、文稿太長嗰陣傻傻重試同一份稿（永遠失敗）。呢啲行為分野，完全由回傳語義決定。

播出嘅最後一關

不論 agent 幾聰明，播出前要有一層「播出審查」：確認內容適合播出、身份同聲線正確、無技術錯誤被當成內容。呢層由系統守，唔由 agent 守——agent 係生產者，系統係把關者。技術報錯原樣讀出嚟係服務事故；記住：用戶聽到嘅每一句，都是你嘅服務。

聽感驗收：上線前最後一環

工具層之外，聽感係最後一道人工關。上線前攞一份代表性測試文稿（含術語、含數字、含英文混句），由頭到尾播一次，聽四樣：咬字、節奏、中英夾雜位、聲線一致性。有問題，改稿唔改閘——稿寫法係聽感嘅第一因，閘只係安全網。將呢個驗收做成常規（每次改聲線或風格配置都行一次），服務聽感先至一路有底。

MCP 接入：令工具一接即用

MCP 係咩，點幫到

MCP（Model Context Protocol）係一個開放協定，令工具成為標準化嘅「上下文服務」：一旦包成 MCP 伺服器，支援 MCP 嘅 agent 環境可以直接發現同調用你嘅工具，唔使每個 agent 環境重寫接入。港嘢已提供 MCP 接入，將粵語語音成為 agent 可以直接調用的工具；接入流程同參數可睇粵語 TTS MCP agent 整合指南。

做法上的兩粒提醒：一，MCP 工具說明寫得清（參數、回傳狀態、錯誤語義），agent 行為就穩；二，工具說明一旦定稿就唔好頻頻改，改一次，全部已接嘅 agent 都要重新行過「理解—試行」。

由試到行：三步路線

第一步（原型）：用開戶額度，在平台介面手動行幾條粵語文稿，確定聲線同聽感。第二步（接入）：接 MCP，喺測試環境行「生成—查詢—取連結」嘅完整循環，觀察 agent 會唔會行錯（重複行、亂傳參數）。第三步（收緊）：上預算閘、限流、並行上限，再上生產——呢步先至真正「可上線」。三步行完，你就有個唔使看長的 agent 語音能力。

同既有渠道嘅分工

Agent 開聲唔取代既有渠道，係補位。通知性、簡短、即時嘅內容——語音最啱；要留底、要轉發、要引用嘅內容——文字最啱。兩者由 agent 按內容性質分工：摘要播聲、全文留字；指示播聲、規格留字。呢個分工令語音唔會變成「全部嘢都讀一次」嘅噪音源，而係喺啱嘅位出現。渠道分工嘅思路，同所有內容系統一樣：聲音有聲音嘅強項位，用啱位先至係體驗加分。

一個可以即刻行的示例

• 行 1：agent 行 generate_voice，傳入「各位乘客，下一班車將於兩分鐘後到站。」＋聲線代稱 pa_announcer，攞返任務編號＋狀態 pending。
• 行 2：agent 晚 10 秒行 check_voice，攞返狀態 ready＋音頻連結。
• 行 3：系統下載音頻、播出；播出前由系統級「播出審查」確認無技術錯誤。

三步行完，一段站內廣播已經由 agent 全程自主完成——由文稿到聲音，中間無人落手。

常見問題 FAQ

agent 會唔會自己亂行語音工具、狂用字符？

有機會，所以三道閘（字符預算、限流、並行上限）一定由系統守。閘嘅拒絕回傳要有清楚語義，令 agent 知道係「行到上限」，唔係「工具壞」。呢個設計令亂行的代價有上限，行為可以預測。

文稿太長被拒，點分段先最啱聽？

分段位要揀句子或者段落邊界，唔好喺一句中間切開；每段以一句收尾，令拼接後節奏自然。逐段生成、逐段核聽，最後再串埋播一次——拼接位有冇突兀，聽返先知。

agent 行工具應該行幾多次查詢？

由回傳語義決定：查不到完成，就按「再查建議」延遲；限流或者預算訊息一出，即時停。好嘅回傳說明，令 agent 唔會無限重試——呢個係工具設計者嘅責任，唔可以賴 agent。

聲線用品牌特有嘅得唔得？

得。以一段品牌錄音做參考樣本，先行「複製聲線」，然後綁入代稱表俾 agent 用。記住要取得錄音嘅使用授權；複製聲線嘅規距同流程，可以參考聲音複製攻略。

MCP 接入要幾多工程？

如果 agent 環境已支援 MCP，接入接近零：工具成為標準服務，環境自己發現。要先試嘅話，由開戶額度先行手動生成驗聽感，再接 MCP 測試——工程量集中在語義同閘設計，唔在協定本身。

10 分鐘旁白要幾多字符同錢？

約 2,400 字符。按月繳方案折算：入門約 HK$1.54、專業約 HK$1.35、工作室約 HK$1.18。agent 全日行落嘅總量可以用呢個粒度推算，再定預算閘嘅數。

免費開戶額度夠唔夠試 agent 流程？

夠驗證。每月 5,000 字符約 21 分鐘音頻，夠行幾次「生成—查詢—取連結」循環，驗工具語義同聽感。要長期行就要上專業／工作室（全速 API）；字符包（HK$50 起）係靈活補位。

[!CTA]

開戶試第一個 agent 語音循環

每月 5,000 字符額度，行完「生成—查詢—取連結」全循環，驗啱聽感先至接 MCP 同上生產。