從頭開始建立動作 create-action-from-scratch
decorate函式和EDS專案結構),然後再連線Widget。新增平台未建立的功能。 在LLM Apps中定義動作、在連結的存放庫中寫入其處理常式,並視需要新增Widget。
在本指南中:瞭解如何定義動作、實作其處理常式,以及連線選用的Widget。 在本機測試動作、部署應用程式,然後在支援的LLM平台中嘗試該動作。
針對您的第一個應用程式,從基礎結構設定開始,然後建立動作。 「建立動作」指南說明從網站自動產生和手動建立。
開始之前
您需要:
- 現有的LLM應用程式。
- 連結的處理常式存放庫。
- 存放庫的本機複製及其相依性已安裝。
- EDS專案(如果動作顯示Widget)。
- 生產結果的清除API或資料來源。
計畫動作
圍繞一個清除的使用者任務設計每個動作。 在開啟UI之前,請定義:
- 意圖 — 使用者嘗試達到的目的。
- 描述 — 何時選取動作。
- 輸入 — 使用者需要的最少資訊。
- 結果 — 處理常式傳回的文字和結構化資料。
- 行為 — 動作會讀取資料、變更資料或呼叫外部系統。
- Widget — 結果是否需要視覺介面。
例如,將此計畫用於 搜尋產品 動作:
Intent: Find products matching a category or search phrase
Inputs:
category: optional string
query: optional string
Result:
content: text summary
structuredContent: products and total count
Behavior: read-only, idempotent, open-world
Widget: product cards
將相關但不同的工作分開。 針對產品搜尋和產品購買使用個別動作,因為這些工作具有不同的輸入、風險和確認需求。
建立動作中繼資料
開啟應用程式並選取動作,然後選取建立動作。
建立新動作對話方塊有四個標籤: 動作詳細資料、LLM Widget詳細資料、應用程式深入分析以及ChatGPT擴充功能。 對話方塊會在 動作詳細資料 開啟。 儲存的動作編輯器會使用相同的標籤。
選用的 ChatGPT擴充功能 設定可讓使用者直接開啟應用程式、使用自訂檔案檢視器,或在支援使用者端的撰寫器中尋找資源。 在對應動作和Widget行為準備就緒後設定這些專案。 請參閱設定ChatGPT擴充功能。
輸入動作資訊和輸入引數
在 動作資訊 下,輸入:
- 動作名稱 — 簡短的工作名稱,例如搜尋產品。
- 描述 — 說明何時使用動作及其傳回的內容。
對話方塊會從名稱(例如search-products)衍生代碼識別碼。 識別碼會在建立後修正,且必須在應用程式內是唯一的。 使用處理常式資料夾的確切識別碼。
有用的說明很具體:
Search the product catalog by category or keyword. Returns matching
products with their names, prices, categories, and image URLs.
避免模糊的描述,例如取得產品資訊。 LLM平台會使用說明來選擇動作。
在 輸入引數 下,為處理常式接受的每個值選取 新增引數 一次。 針對每個引數,輸入:
- 引數名稱 — 處理常式收到的金鑰。
- 型別 — 字串、數字、整數、布林值、物件或檔案。
- 必要 — 動作是否需要值。
- 描述 — 如何擷取值。
針對搜尋產品:
category
Type: String
Required: No
Description: Product category used to narrow the catalog.
query
Type: String
Required: No
Description: Product name or search phrase.
使用穩定的引數名稱。 變更名稱也需要變更處理常式及其測試。
設定LLM設定
展開LLM設定。 依預設,該區段會摺疊。
在 註解 下,只選取動作為True的提示:
- 破壞性提示 — 動作可以刪除或永久變更資料。
- 等冪(相同的引數=沒有額外的效果) — 重複相同的要求會有相同的效果。
- 開放世界提示 — 動作與外部系統通訊。
- 唯讀提示 — 動作不會變更資料。
例如,產品搜尋通常是唯讀、等冪和開放世界。
在 OpenAI中繼資料 底下,輸入動作執行時和完成時顯示的簡短訊息,每個訊息最多64個字元:
Invoking status text: Searching products...
Invoked status text: Products found
在 可見度 下:
- 公開給AI模型可讓模型選取動作。
- 在應用程式表面顯示為Widget會顯示設定的Widget。
可見度不會選擇Widget型別。 若是純文字動作,請選取LLM Widget詳細資料 > Widget型別下的無互動式UI。
設定應用程式分析 configure-analytics
開啟Application Insights。 依預設會選取「收集使用者意圖」:LLM平台會建立簡短、匿名化的摘要,說明使用者在執行動作時嘗試完成的內容。
如果您設定自己的Adobe Analytics或Customer Journey Analytics,使用者意向也會傳送至該處。 請參閱設定Adobe Analytics和Customer Journey Analytics。
請檢閱核取方塊下方的指示,該指示可指導摘要。 將其限製為非敏感、匿名的目的,並在您的隱私權政策中說明您的資料收集。 指示最多可接受2,000個字元。 清除 收集使用者意圖 以不收集摘要。
如需完整的欄位定義,請參閱動作和Widget欄位。
設定Widget
開啟LLM Widget詳細資料。 若是純文字動作,請選取 Widget型別 下的無互動式UI,並略過其餘的Widget設定。
在 Widget資訊 下,設定:
- Widget型別 — 為互動式Widget選取Edge Delivery Services區塊。
- Widget網域 — Widget的沙箱來源。 UI會根據應用程式提交和每個應用程式的唯一性來識別它;它與EDS頁面URL不同。
- Widget說明 — 在Widget呈現後,模型所顯示的內容,最多512個字元。
Widget說明與動作說明不同:
- 動作描述可協助模型決定何時叫用動作。
- Widget描述對應至
_meta["openai/widgetDescription"]並摘要呈現的元件所顯示的內容,減少重複的旁白。
LLM Apps將Widget說明套用為元件中繼資料。 請勿從處理常式傳回說明。
展開 範本URL 並輸入:
- 指令碼URL — EDS Widget進入點。
- Widget URL — 此動作的已發佈EDS頁面。
典型的URL為:
Script URL:
https://main--<repo>--<owner>.aem.live/scripts/aem-embed.js
Widget URL:
https://main--<repo>--<owner>.aem.live/<widget-page>
在 CSP設定 底下,僅新增資產和網路要求Widget需要的來源。 如果CSP不完整,載入外部資源的Widget可能不會呈現。
如果EDS專案或Widget頁面尚不存在,請完成自攜EDS專案,然後返回動作。
儲存動作
選取建立新動作。 此動作會顯示在具有 未部署 徽章的「動作」頁面上。
儲存會建立中繼資料,但動作仍需要處理常式。
當您重新開啟儲存的動作時,編輯器會顯示相同的標籤。 若要儲存稍後的編輯,請選取儲存變更。
實作處理常式
複製連結的處理常式存放庫並安裝其相依性:
npm install
建立:
actions/
└── search-products/
└── index.js
資料夾名稱必須符合動作編輯器中顯示的動作代碼識別碼。
如需完整的結果合約與處理常式 — Widget關係,請參閱自訂產生的處理常式。
處理常式合約
匯出非同步函式:
module.exports = async (args) => {
return {
content: [
{ type: 'text', text: 'Response for the LLM platform.' }
],
structuredContent: {
// Data for the widget.
}
};
};
處理常式會接收UI中定義的引數。
傳回content
LLM平台讀取content做為文字遞補:
content: [
{ type: 'text', text: 'Found 3 matching products.' }
]
一律傳回有用的content,即使動作具有Widget亦然。
傳回structuredContent
Widget會將structuredContent視為純物件:
structuredContent: {
products: [
{ id: 'P-100', name: 'Product A', price: '$20' }
],
total: 1
}
形狀必須符合EDS區塊從bridge.toolResult讀取的內容。
連線API
將API呼叫保留在伺服器端處理常式。 此範例會呼叫公用產品API。 在名為PRODUCT_API_ORIGIN的應用程式變數中設定API的HTTPS來源。 此範例接受以上定義的query和category引數、至少需要一個引數,而且不需要認證。
const { getVariable } = require('@adobe/llm-apps-runtime');
module.exports = async ({ query = '', category = '' } = {}, extra) => {
const normalizedQuery = typeof query === 'string' ? query.trim() : '';
const normalizedCategory = typeof category === 'string' ? category.trim() : '';
if (typeof query !== 'string' || typeof category !== 'string'
|| (!normalizedQuery && !normalizedCategory)
|| normalizedQuery.length > 200 || normalizedCategory.length > 100) {
return {
isError: true,
content: [{ type: 'text', text: 'Enter a valid product search.' }],
structuredContent: { products: [], total: 0 }
};
}
const apiOrigin = getVariable(extra, 'PRODUCT_API_ORIGIN');
if (!apiOrigin) {
throw new Error('Product API configuration is unavailable.');
}
const origin = new URL(apiOrigin);
if (origin.protocol !== 'https:') {
throw new Error('Product API configuration must use HTTPS.');
}
const url = new URL('/v1/products', origin);
if (normalizedQuery) {
url.searchParams.set('query', normalizedQuery);
}
if (normalizedCategory) {
url.searchParams.set('category', normalizedCategory);
}
const response = await fetch(url, {
signal: AbortSignal.timeout(8000)
});
if (!response.ok) {
throw new Error('Product service request failed.');
}
const payload = await response.json();
if (!payload || !Array.isArray(payload.products)
|| !payload.products.every((product) =>
product
&& typeof product.id === 'string'
&& typeof product.name === 'string'
&& typeof product.price === 'string')) {
throw new Error('Product service returned an unexpected response.');
}
const products = payload.products.map((product) => ({
id: product.id,
name: product.name,
price: product.price
}));
return {
content: [
{ type: 'text', text: `Found ${products.length} matching products.` }
],
structuredContent: {
products,
total: products.length
}
};
};
請勿將API認證放入原始程式碼、動作中繼資料、Widget JavaScript、記錄檔或面對使用者的錯誤中。 變數和密碼 UI目前僅支援不敏感的變數,不支援密碼。 請勿將API權杖儲存在變數中。 如果您的上游API需要認證,請先安排核准的伺服器端認證機制,然後再進行連線。
對於生產程式碼,在將核准的欄位對應到structuredContent之前,請先驗證完整的上游回應。
新增處理常式測試
建立比對測試:
test/
└── actions/
└── search-products.test.js
至少測試:
- 有效的輸入。
- 輸入遺失或無效。
- 空白的結果。
- API逾時或失敗。
- API資料格式錯誤。
- Widget預期的
structuredContent形狀。
執行:
npm test
如需專案配置與本機MCP測試,請參閱本機處理常式開發與測試。
在本機測試動作
執行:
npm run dev:local
如果沒有本機actions.json,伺服器會以最少的中繼資料發現處理常式,而且沒有輸入結構描述驗證。
使用MCP檢查工具或curl來:
- 列出已註冊的動作。
- 使用代表性引數呼叫新動作。
- 驗證
content和structuredContent。 - 測試無效和空白的請求。
連線和測試Widget
如果動作有Widget:
- 讓Widget讀取處理常式的
structuredContent。 - 使用安全DOM API (例如
textContent)轉譯外部值。 - 新增載入、空白和錯誤狀態。
- 在本機預覽EDS頁面。
- 驗證CSP、CORS和Widget URL。
參閱自備EDS專案。
部署和測試
如果中繼資料不存在相符的處理常式,部署會使用預設的Stub註冊動作。 在讓使用者能夠使用動作之前,請新增處理常式。