在 Amazon Bedrock 中為代理程式的動作群組定義 OpenAPI 結構描述

在 Amazon Bedrock 中建立動作群組時，您必須定義代理程式需要從使用者調用的參數。您也可以定義代理程式可以使用這些參數來調用的 API 操作。若要定義 API 操作，請以 JSON 或 YAML 格式建立 OpenAPI 結構描述。您可以建立 OpenAPI 結構描述檔案，並將其上傳至 Amazon Simple Storage Service (Amazon S3)。或者，您也可以使用主控台中的 OpenAPI 文字編輯器，它會驗證您的結構描述。建立代理程式後，您可以在將動作群組新增至代理程式或編輯現有的動作群組時，使用文字編輯器。如需詳細資訊，請參閱修改代理程式。

代理程式會使用結構描述來判斷其需要調用的 API 操作，以及提出 API 請求所需的參數。然後，這些詳細資訊會透過您定義的 Lambda 函數傳送，以執行動作或在代理程式調用的回應中傳回。

如需 API 結構描述的詳細資訊，請參閱下列資源：

如需 OpenAPI 結構描述的詳細資訊，請參閱 Swagger 網站上的 OpenAPI 規格。
如需撰寫 API 結構描述的最佳做法，請參閱 Swagger 網站上的 API 設計中的最佳做法。

以下是動作群組的 OpenAPI 結構描述的一般格式。


{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... },
                "x-requireConfirmation": ENABLED | DISABLED
           }
       }
    }
}

下列清單說明 OpenAPI 結構描述中的欄位。

openapi – (必要) 要使用的 OpenAPI 版本。此值必須等於 "3.0.0"，如此動作群組才能運作。
paths— (必要) 包含個別端點的相對路徑。每個路徑都必須以正斜線 (/) 開頭。
method— (必要) 定義要使用的方法。
x-requireConfirmation – (選用) 指定在調用動作之前是否需要使用者確認。啟用此欄位可在調用動作之前向使用者請求確認。在調用動作之前請求使用者確認，可以保護您的應用程式免於因惡意提示注入而執行動作。根據預設，如果未指定此欄位，則使用者確認為 DISABLED。

每個方法至少都需要下列欄位：

description – API 的描述。使用此欄位告知代理程式何時呼叫此 API 操作，以及此操作的執行內容。
operationId – 可識別 API 中操作的唯一字串，例如函數名稱。這是所有啟用 toolUse 新模型的必要欄位，例如 Anthropic Claude 3.5 Sonnet、Meta Llama 等。確保您提供的識別符 (Id) 在所有操作中都是唯一的，並遵循簡單的英數字元模式，只使用連字號或底線做為分隔符號。
responses – 包含代理程式在 API 回應中傳回的屬性。代理程式會使用回應屬性來建構提示、準確處理 API 呼叫的結果，以及判斷執行任務的一組正確步驟。代理程式可以使用來自一個操作的回應值，作為協同運作中後續步驟的輸入。

下列兩個物件中的欄位為您的代理提供更多資訊，使他們能有效利用您的動作群組。對於每個欄位，若是必要欄位，請將 required 欄位的值設定為 true；若是選用欄位，則設定為 false。

parameters – 包含可納入請求中之參數的相關資訊。
requestBody— 包含操作請求內文中的欄位。請勿在 GET 和 DELETE 方法中包含此欄位。

若要進一步了解結構，請從下列索引標籤中選取。

responses


"responses": {
    "200": {
        "content": {
            "<media type>": {
                "schema": {
                    "properties": {
                        "<property>": {
                            "type": "string",
                            "description": "string"
                        },
                        ...
                    }
                }
            }
        },
    },
    ...
}

responses 物件中的每個索引鍵都是回應代碼，描述回應的狀態。回應程式碼映射至一個物件，其中包含回應的下列資訊：

content- (每個回應都需要)回應的內容。
<media type>— 回應內文的格式。如需詳細資訊，請參閱 Swagger 網站上的媒體類型。
schema— (每種媒體類型都需要) 定義回應內文及其欄位的資料類型。
properties— (如果結構描述中存在 items 則為必要) 您的代理會使用您在結構描述中定義的內容來決定傳回給使用者以完成任務所需的資訊。每個屬性包含下列欄位：
- type— (每個屬性都需要) 回應欄位的資料類型。
- description— (選用) 描述屬性。代理程式可以使用此資訊來判斷需傳回給最終使用者的資訊。

parameters


"parameters": [
    {
        "name": "string",
        "description": "string",
        "required": boolean,
        "schema": {
            ...
        }
    },
    ...
]

您的代理程式會使用下列欄位來確定需要從最終使用者取得的資訊，以便執行動作群組的要求。

name – (必要) 參數的名稱。
description – (必要) 參數的描述。使用此欄位可協助代理了解如何從代理使用者取得此參數，或判斷其已具有先前動作或使用者向代理要求所產生的該參數值。
required – (選用) API 請求是否需要參數。使用此欄位可向代理程式指示此參數是否每次調用都需要，或是選用參數。
schema— (選用) 輸入和輸出資料類型的定義。如需詳細資訊，請參閱 Swagger 網站上的資料模型 (結構描述)。

requestBody

以下是 requestBody 欄位的一般結構：


"requestBody": {
    "required": boolean,
    "content": {
        "<media type>": {
            "schema": {
                "properties": {
                    "<property>": {
                        "type": "string",
                        "description": "string"
                    },
                    ...
                }
            }
        }
    }
}

以下清單說明每個欄位：

required – (選用) API 請求是否需要請求內文。
content— (必要) 請求內文的內容。
<media type>— (選用) 請求內文的格式。如需詳細資訊，請參閱 Swagger 網站上的媒體類型。
schema— (選用) 定義請求內文及其欄位的資料類型。
properties – (選用) 您的代理會使用您在結構描述中定義的屬性，來決定需要從最終使用者取得哪些資訊，以便發出 API 請求。每個屬性包含下列欄位：
- type— (選用) 請求欄位的資料類型。
- description— (選用) 描述屬性。代理可以使用此資訊來判斷需傳回給終端使用者的資訊。

若要了解如何新增您在建立動作群組時建立的 OpenAPI 結構描述，請參閱在 Amazon Bedrock 中將動作群組新增至您的代理程式。

範例 API 結構描述

下列範例提供 YAML 格式的簡單 OpenAPI 結構描述，用於取得給定位置的攝氏溫度天氣。


openapi: 3.0.0
info:
  title: GetWeather API
  version: 1.0.0
  description: gets weather
paths:
  /getWeather/{location}/:
    get:
      summary: gets weather in Celsius
      description: gets weather in Celsius
      operationId: getWeather
      parameters:
        - name: location
          in: path
          description: location name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: weather in Celsius
          content:
            application/json:
              schema:
                type: string

以下範例 API 結構描述定義了一組協助處理保險理賠的 API 操作。三個 API 定義如下：

getAllOpenClaims – 您的代理程式可以使用 description 欄位來確定在需要未結理賠清單時，應呼叫此 API 操作。properties 在 responses 中指定傳回 ID 和保單持有人和理賠的狀態。代理會將此資訊傳回給代理使用者，或使用部分或全部回應，以當做後續 API 呼叫的輸入。
identifyMissingDocuments – 您的代理程式可以使用 description 欄位來確定，如果需要識別保險理賠中缺少的文件，則應呼叫此 API 操作。name、description 和 required 欄位會告訴代理，必須向客戶取得未結索賠的唯一識別碼。properties 在 responses 中指定傳回未結保險理賠的 ID。代理程式會將此資訊傳回給最終使用者，或使用部分或全部回應，以當做後續 API 呼叫的輸入。
sendReminders – 您的代理程式可以使用 description 欄位來確定如果需要向客戶傳送提醒時，應該呼叫此 API 操作。例如，提醒他們注意未結理賠中待處理的文件。requestBody 中的 properties 告知代理程式必須找到理賠 ID 和待處理文件。responses 中的 properties 指定傳回提醒的 ID 及其狀態。代理程式會將此資訊傳回給最終使用者，或使用部分或全部回應，以當做後續 API 呼叫的輸入。


{
    "openapi": "3.0.0",
    "info": {
        "title": "Insurance Claims Automation API",
        "version": "1.0.0",
        "description": "APIs for managing insurance claims by pulling a list of open claims, identifying outstanding paperwork for each claim, and sending reminders to policy holders."
    },
    "paths": {
        "/claims": {
            "get": {
                "summary": "Get a list of all open claims",
                "description": "Get the list of all open insurance claims. Return all the open claimIds.",
                "operationId": "getAllOpenClaims",
                "responses": {
                    "200": {
                        "description": "Gets the list of all open insurance claims for policy holders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "claimId": {
                                                "type": "string",
                                                "description": "Unique ID of the claim."
                                            },
                                            "policyHolderId": {
                                                "type": "string",
                                                "description": "Unique ID of the policy holder who has filed the claim."
                                            },
                                            "claimStatus": {
                                                "type": "string",
                                                "description": "The status of the claim. Claim can be in Open or Closed state"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/claims/{claimId}/identify-missing-documents": {
            "get": {
                "summary": "Identify missing documents for a specific claim",
                "description": "Get the list of pending documents that need to be uploaded by policy holder before the claim can be processed. The API takes in only one claim id and returns the list of documents that are pending to be uploaded by policy holder for that claim. This API should be called for each claim id",
                "operationId": "identifyMissingDocuments",
                "parameters": [{
                    "name": "claimId",
                    "in": "path",
                    "description": "Unique ID of the open insurance claim",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }],
                "responses": {
                    "200": {
                        "description": "List of documents that are pending to be uploaded by policy holder for insurance claim",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pendingDocuments": {
                                            "type": "string",
                                            "description": "The list of pending documents for the claim."
                                        }
                                    }
                                }
                            }
                        }

                    }
                }
            }
        },
        "/send-reminders": {
            "post": {
                "summary": "API to send reminder to the customer about pending documents for open claim",
                "description": "Send reminder to the customer about pending documents for open claim. The API takes in only one claim id and its pending documents at a time, sends the reminder and returns the tracking details for the reminder. This API should be called for each claim id you want to send reminders for.",
                "operationId": "sendReminders",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "claimId": {
                                        "type": "string",
                                        "description": "Unique ID of open claims to send reminders for."
                                    },
                                    "pendingDocuments": {
                                        "type": "string",
                                        "description": "The list of pending documents for the claim."
                                    }
                                },
                                "required": [
                                    "claimId",
                                    "pendingDocuments"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reminders sent successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sendReminderTrackingId": {
                                            "type": "string",
                                            "description": "Unique Id to track the status of the send reminder Call"
                                        },
                                        "sendReminderStatus": {
                                            "type": "string",
                                            "description": "Status of send reminder notifications"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request. One or more required fields are missing or invalid."
                    }
                }
            }
        }
    }
}

如需 OpenAPI 結構描述的更多範例，請參閱 OpenAPI 網站上的 API 描述範例。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

定義函數詳細資訊

處理動作的履行