自訂產生的處理常式 customize-generated-handler
平台會為每個產生的動作建立工作處理常式。 處理常式一開始會傳回範例資料,以測試完整的體驗。
在本指南中:瞭解如何尋找產生的處理常式、以呼叫您的系統取代其範例資料,以及保持其回應與Widget相容。 然後測試和部署您的變更。
尋找產生的處理常式
開啟在基礎結構設定期間連線的處理常式存放庫。 如果您使用LLM Apps受管理基礎結構,請先要求程式碼存取權,然後再繼續。
actions/
└── <action-slug>/
├── index.js
└── data.json
相符的測試位於不同的目錄中:
test/
└── actions/
└── <action-slug>.test.js
使用產生的提取請求或分支來找出確切的檔案。 資料夾概要(Slug)使用連字型大小:平台會在actions/search-products/下產生代碼識別碼為search_products的動作。 執行階段會辨識斷字表單以及完全符合識別碼的資料夾。
編輯產生的index.js和任何關聯的範例資料。 請勿變更執行階段檔案,例如entry.js。
處理常式合約
每個處理常式會匯出一個非同步函式:
module.exports = async (args, extra) => {
return {
content: [
{ type: 'text', text: 'Response for the LLM platform.' }
],
structuredContent: {
// Data for the widget.
}
};
};
針對具有輸入結構描述的動作,函式會接收args物件與選擇性執行階段內容extra,並傳回結果物件。 針對執行階段協助程式(例如getVariable(extra, 'PRODUCT_API_ORIGIN'))使用extra;應用程式變數不會透過process.env自動公開。 請參閱設定應用程式變數和密碼。
輸入: args
args包含為LLM Apps中的動作定義的引數。
針對具有category和query引數的動作:
module.exports = async ({ category = '', query = '' } = {}, extra) => {
// Validate business rules before using the arguments.
};
透過動作中繼資料,執行階段會將宣告的輸入結構描述轉換為支援規則的驗證,包括必要欄位、基本型別、列舉和陣列專案。 執行階段未執行完整的JSON結構描述驗證。 檢查處理常式中的限制,例如字串長度、數值範圍和巢狀物件屬性。
沒有結構描述中繼資料的本機探索不等於部署:執行階段不會以一般(args, extra)形式傳遞動作引數。 使用直接處理常式測試或代表性本機actions.json中繼資料來測試引數。 請參閱本機處理常式開發與測試。
輸出: content
一律傳回content。 這是由LLM平台及不顯示Widget的主機所讀取的內容部分陣列。
content: [
{
type: 'text',
text: 'Found 3 products matching your search.'
}
]
保持簡明的文字回應。 不要包含認證、內部錯誤或使用者無權檢視的資料。
輸出: structuredContent
動作有Widget時傳回structuredContent。 它必須是純物件,而非裸陣列。
structuredContent: {
arguments: { query: 'coffee' },
records: [
{
id: 'P-100',
name: 'Frescopa House Blend',
price: '$14.99'
}
]
}
structuredContent是傳遞給主機的MCP動作結果的一部分。 請勿假設模型或使用者看不到它。 僅傳回體驗、永不認證或私人伺服器設定所需的授權資料。
對於純文字動作,傳回structuredContent為選用。
處理常式 — Widget合約
處理常式和Widget共用一個合約: structuredContent的形狀。
contentstructuredContentbridge.toolResult讀取Widget會從LLM應用程式SDK Bridge讀取處理常式結果:
export default async function decorate(block, bridge) {
if (!bridge?.isConnected || bridge.hostContext?.preview === true) {
// Render the block's local preview data instead.
return;
}
const result = await bridge.toolResult;
const records = result?.structuredContent?.records ?? [];
// Render records.
}
目前產生的處理常式使用包含arguments和records的物件。 現有的應用程式可以使用不同的形狀,因此請在編輯之前檢查您產生的檔案。 變更欄位名稱或型別可能會中斷Widget。 一起更新處理常式、Widget和測試。
取代範例資料
產生的處理常式會從data.json載入代表性記錄。 以伺服器端呼叫您的系統來取代範例資料查詢。 以下範例使用公用HTTPS目錄API,並從應用程式變數中讀取其非敏感來源。 將回應驗證調整至您的API。
const { getVariable } = require('@adobe/llm-apps-runtime');
module.exports = async ({ query = '' } = {}, extra) => {
const normalizedQuery = typeof query === 'string' ? query.trim() : '';
if (!normalizedQuery || normalizedQuery.length > 200) {
return {
content: [{ type: 'text', text: 'Enter a valid product search.' }],
structuredContent: { arguments: {}, records: [] },
isError: true
};
}
const knownArguments = { query };
try {
const apiOrigin = getVariable(extra, 'PRODUCT_API_ORIGIN');
if (!apiOrigin) {
throw new Error('Missing configuration');
}
const origin = new URL(apiOrigin);
if (origin.protocol !== 'https:' || origin.username || origin.password) {
throw new Error('Invalid API origin');
}
const url = new URL('/v1/products', origin);
url.searchParams.set('query', normalizedQuery);
const response = await fetch(url, {
signal: AbortSignal.timeout(8000)
});
if (!response.ok) {
throw new Error('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('Unexpected response');
}
const records = payload.products.map(({ id, name, price }) => ({
id,
name,
price
}));
return {
content: [
{ type: 'text', text: `Found ${records.length} matching products.` }
],
structuredContent: { arguments: knownArguments, records }
};
} catch {
return {
content: [{ type: 'text', text: 'Product search is unavailable. Try again later.' }],
structuredContent: { arguments: knownArguments, records: [] },
isError: true
};
}
};
在處理常式中保留受保護的網路存取。 切勿將API憑證放入Widget JavaScript或原始檔控制中。 若是代表登入使用者提出的要求,請參閱驗證一般使用者。
如需您的處理常式所需的非敏感設定(例如服務URL),請參閱設定應用程式變數和密碼。 分別為每個環境設定變數。 變數變更會在下次部署時生效。 目前的UI僅支援新增變數;請勿使用變數來儲存API認證。
處理預期狀態
保留每個結果的可預測輸出圖形。
找到個結果
{
content: [{ type: 'text', text: 'Found 3 products.' }],
structuredContent: { arguments: { query: 'coffee' }, records: [...] }
}
沒有結果
{
content: [{ type: 'text', text: 'No matching products were found.' }],
structuredContent: { arguments: { query: 'coffee' }, records: [] }
}
可預測的結果圖形可讓Widget呈現空白狀態,而不需猜測records是否存在。
對於服務失敗,傳回包含isError: true的安全錯誤結果,如範例所示。 檢查Widget中的result.isError,以便將失敗的要求顯示為成功的空白搜尋。 請勿公開棧疊追蹤、認證、內部主機或上游回應主體。
測試合約
每當處理常式變更時,請更新產生的測試。 封面:
- 有效且無效的引數。
- 「結果」和「無結果」狀態。
- API失敗和逾時。
- API回應的格式錯誤。
- 每個結果中都有
content存在。 structuredContent的純物件。- Widget預期的形狀。
執行存放庫已設定的測試套件:
npm test
如果產生的測試匯入node:test而非Jest,請使用node --test test/actions/<action-slug>.test.js執行它,並驗證其匯入路徑是否從test/actions/解析。 使用適合檔案的測試執行器;樣版的npm test命令會執行Jest。
如需本機MCP測試,請參閱本機處理常式開發與測試。
部署變更
接下來,請參閱自訂產生的Widget。