主導覽

運用 ChatGPT Apps SDK 推出產品所得的經驗

運用 ChatGPT Apps SDK 推出產品的實務心得，說明其架構適用的情況，以及何時需要更多控制權。

內容摘要

  • 如果你需要盡快在 ChatGPT 中推出工作流程，或想先在其中測試工具再投資建立自訂智能代理技術堆疊，Apps SDK 是務實的選擇。但如果你需要全面掌控智能代理每一步的行為，Apps SDK 通常並不適合。

  • 如果 ChatGPT 應是主要介面，而你希望提供工具及少量 UI，又不想建立完整的對話產品，請選用 Apps SDK。如果你需要嚴格控制流程、記憶、提示詞及寫入操作，請建立自己的智能代理技術堆疊。

  • Apps SDK 適合結合對話與少量簡短 UI 步驟的產品。你可以更快推出產品，但會犧牲部分控制權。

  • 對我們有效的方法，是清楚界定工具、介面元件行為及後續步驟。我們依靠這些元素來確定流程，而非依賴 LLM。系統作出決定後，由模型解釋結果最為實用。

  • 以下先說明如何選擇，再介紹哪些方法有效、哪些無效。

大多數團隊仍只在試行 AI，或把 AI 用於風險與回報均偏低的非核心用途。真正能推出讓用戶每週使用、同時對業務至關重要的產品的團隊寥寥可數。如果你的目標是進駐 ChatGPT，而非自行建立整套助理，ChatGPT Apps SDK 是收窄這項差距的方法之一。

我們為何使用 Apps SDK

這些心得來自一個客戶項目：需求以 ChatGPT 為主要介面，並要求快速推出，而毋須投資建立完整的度身訂造對話產品。

按照這項要求，Apps SDK 正好切合客戶的以下需要：

  • 毋須建立及託管專用對話產品—他們希望在 ChatGPT 中接觸用戶，而非另設獨立的助理介面。

  • 對話配合少量針對特定任務的 UI—只需幾個重點明確的介面元件步驟，而非在工作流程中再建一套完整產品。

  • 透過 MCP 工具提供後端功能—採用標準工具調用，而非自行端對端管理自訂智能代理執行環境。

  • 讓用戶在 ChatGPT 中發現這套工作流程—讓用戶可在慣常工作的地方接觸這套工作流程。

我們在開發期間與客戶共同驗證了這些選擇。取捨依然存在：由 ChatGPT 託管工作階段時，外層執行環境並不由你掌控。你可以引導它，卻無法完全控制它。

Apps SDK 提供甚麼

Apps SDK 應用程式連接三個部分：

  1. ChatGPT 的智能代理執行環境

  2. 你的 MCP 工具

  3. 你的介面元件

實際流程如下：

  1. 用戶向 ChatGPT 提出要求。

  2. ChatGPT 可能會調用你的其中一項 MCP 工具。

  3. 你的伺服器傳回結構化工具結果。

  4. ChatGPT 讀取結果並決定下一步：繼續調用工具、回覆用戶，或兩者並行。如果你為該工具附加了介面元件，它便可在這一輪顯示。

  5. 用戶在對話或介面元件中繼續操作（輸入跟進文字、作出選擇，或由介面元件觸發工具調用）。對話串隨之更新；ChatGPT 展開新一輪處理，並重複步驟 2 至 4，直至完成任務。

重點正是結合對話、後端操作及簡短的 UI 步驟。這也意味最容易出現問題的環節，是對話、工具與 UI 之間的交接。

你毋須從零建立對話 UI、工具連接、身分驗證模式或介面元件外殼。對許多產品而言，這可大幅縮短開發時間，讓你專注於領域邏輯和防護措施。

在 ChatGPT 內建立功能，並不等同自行運行智能代理。這個項目的難點並非提示詞技巧。真正的難點，是把工具、介面元件及後續步驟界定得足夠清楚，使模型與 UI 保持一致。

如何選擇

Apps SDK 所提供的產品形式有別於一般前端；了解它最適合哪些情境至關重要。

以下情況適宜使用 Apps SDK

  • 快速推出 ChatGPT 工作流程。

  • 讓 ChatGPT 託管對話。

  • 把自然語言與少量重點明確的 UI 步驟結合。

  • 避免自行建立對話介面、智能代理容器及讓用戶發現產品的機制。

如果用戶本來就在 ChatGPT 中工作，最後一點尤其重要。

以下情況應自行建立智能代理

  • 需要可透過程式碼強制執行的固定逐步流程。

  • 需要由你端對端掌控的自訂 UI 及確認路徑。

  • 需要自有的記憶及狀態模型。

  • 每次運行的行為都必須可以預測。

  • 需要智能代理的追蹤記錄、日誌及指標。

如果規劃器、系統提示詞及完整工作流程就是你的產品，自訂技術堆疊通常更為合適。

取捨一覽

問題

ChatGPT Apps SDK

自有智能代理

這項體驗在哪裏提供？

ChatGPT 內

你的產品內

由誰執行對話步驟？

ChatGPT，由你的工具及 UI 引導

你的智能代理式系統

需要建立多少 UI？

對話中針對特定功能的介面元件

按需要建立

對提示詞有多少控制權？

間接控制

完全控制

固定且可重複的流程是否容易實現？

需要審慎設計

較容易透過程式碼強制執行

首次推出所需時間

通常較快

初期通常較慢

由你負責的平台工作

較少

較多

日後改變方向的空間

較少

較多

在這個客戶項目中，反覆出現的關鍵詞是「控制權」：一邊是速度及熟悉的託管平台，另一邊則是只能局部掌控執行環境。客戶優先選擇在 ChatGPT 中接觸用戶，而非掌控整套技術堆疊時，便接受了這項取捨。

難點所在

理想流程看似簡單：用戶提出要求、工具運行、資料傳回，並在需要選擇時顯示介面元件。

實際上的痛點在於交接。介面元件並非裝飾。它一旦出現在畫面上，便會改變模型所看到的內容，以及模型下一步採取的行動。應把介面元件操作視為具名事件，而非鬆散的對話。

這個項目採用的技術堆疊相當簡單：FastMCP、Pydantic、React、TypeScript。整合這些技術並無問題。真正的工作，是讓模型、工具及 UI 對下一步達成一致。

有效的方法

讓每次交接都清楚明確

我們不再把工具結果視為原始後端資料，而是把每次傳回結果都視為一次交接。

穩健的工具結果會：

  • 提供介面元件呈現內容所需的資料。

  • 向 ChatGPT 提供結構化事實，作為回覆依據。

  • 在流程需要時說明下一步，以免模型自行猜測。

介面元件操作不應把含糊的文字送回對話串。它們應說明用戶做了甚麼，以及下一步應如何處理。

交接清楚後，可靠性便有所提升。

當工具輸出及介面元件操作包含簡短清晰的指示時，模型便能依循指示。

以下是我們使用的一個小型 Pydantic 結構。「output」欄位載有顯示介面元件時所需的結構化資料，以及 ChatGPT 在工作階段中應使用的事實。「agent_directions」欄位載有一行簡短指示，說明助理下一步應做甚麼。「reason」為選填項目。

Python

from typing import Generic, TypeVar
from pydantic import BaseModel
T = TypeVar("T")
class AgentDirections(BaseModel): assistant_instruction: str reason: str | None = None
class ToolResults(BaseModel, Generic[T]): agent_directions: AgentDirections output: T

保持介面元件精簡

有效的介面元件只讓用戶作出一項決定，然後便交還控制權。簡短清單、確認步驟或精簡的審閱畫面，效果都比把介面元件變成迷你應用程式好。如果希望流程更具確定性，在介面元件加入少量邏輯仍有幫助，例如簡單驗證或固定下一步。

介面元件訊息使用第三人稱

我們不再把介面元件的跟進訊息寫成用戶的對話，例如「我選擇了…」、「我確認了…」。我們改以簡短報告描述用戶的操作，例如「用戶選擇了…」、「用戶確認了…」。我們嘗試這種做法，是因為 ChatGPT 加入對話串時會標示為工具訊息，而非用戶訊息。

下一步明確時直接執行操作

如果按鈕已明確對應下一次工具調用，由介面元件直接觸發調用，效果會比強制多進行一輪對話好。這只適用於下一次工具調用毋須 ChatGPT 提供輸入的情況。

這令流程更具確定性，亦因省去另一輪對話而降低延遲。

錯誤處理

工具調用失敗時，我們會從工具傳回正確的 MCP 錯誤代碼及簡短易明的訊息。這樣，ChatGPT 在調用失敗時便有實際資訊可讀，從而向用戶解釋問題及／或選擇合理的下一步。

工具上下文管理

我們把工作階段狀態保留在自己的伺服器上。ChatGPT 會隨工具調用傳送工作階段層級的上下文；在 FastMCP 中，我們為每項工具加入 Context 參數，讓處理程式讀取及更新該狀態。

  • 固定 ID 和先前的結果都保留在工作階段內，毋須 ChatGPT 在每次調用時再次以工具引數傳送。

  • 出現工具調用循環時，我們可以偵測並攔截重複調用，再透過工具結果傳回明確的錯誤訊息。

  • 工作階段日誌則保留在我們的伺服器端，以便除錯及提供支援。

未奏效的方法

假設模型會推斷下一步

初期，我們顯示介面元件後，假設模型已經「明白」，然後等待它作出正確的跟進工具調用。有時會如預期調用，但很多時都不會。

若沒有清晰交接，ChatGPT 可能會在我們需要它執行操作時作出總結、要求用戶重複選擇，或在應該停止時繼續規劃。

解決方法是在結構化輸出內容和介面元件資料中明確說明下一步，而不是期望模型自行推斷。

把意思分散於不同層面

我們曾嘗試按照 Apps SDK 文件，把回應分拆到工具輸出、隱藏中繼資料和對話文字中。但我們無法在介面元件中讀取隱藏中繼資料，因此這個方法行不通。

對模型隱藏工具

Apps SDK 文件說明，可從智能代理的工具清單隱藏工具，使其不會選用這些工具，但介面元件仍可調用。但當我們把可見度設為「app-only」後，這些工具不但不再向智能代理顯示，也無法從介面元件調用。

含糊的錯誤回應

如果實際上沒有任何有效結果，保持沉默或傳回籠統的「成功」比直接報錯更差。因此，我們把工具及介面元件的失敗情況視為需要明確回報的結果：如果某個步驟無法繼續，我們便以淺白文字說明，並傳回明確錯誤，而不是讓用戶面對一個雖已顯示、卻無法推進流程的介面元件。

總結

如果你的目標是在 ChatGPT 中建立工作流程，同時減少自訂平台開發工作，Apps SDK 是一個實用選擇。你以部分控制權換取速度，並能在用戶慣常工作的地方接觸他們。

如果你需要掌控流程的每個分支、UI，以及每一步由誰決定，就應從一開始規劃自己的智能代理技術堆疊。你很可能最終會發現，只在 ChatGPT 內建立功能已無法滿足產品需要。

你亦可以先使用 Apps SDK 在 ChatGPT 內運行 MCP 伺服器，毋須自行建立對話介面、身份驗證和智能代理基礎設施；待產品有需要時，再遷移至自有技術堆疊。

處境相同的團隊下一步應選擇一項結對於有類似需要的團隊，下一步是選擇一項成果明確的工作流程，清楚記錄對話、工具和介面元件之間的交接方式，再對重試和錯誤情況進行壓力測試，然後才投入大量時間調整提示詞。

作者

Malan Evans