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

當您在 Amazon Bedrock 中建立動作群組時，您必須定義代理程式需要從使用者叫用的參數。您也可以定義代理程式可以使用這些參數叫用的 API 操作。若要定義 API OpenAPI 操作，請以 JSON 或 YAML 格式建立結構描述。您可以建立結構描述檔案，並將其上傳至 Amazon Simple Storage Service OpenAPI (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 Meta Llama、 Claude 3.5 Sonnet等。請確定您提供的識別符 (Id) 在所有操作中都是唯一的，並遵循簡單的英數字元模式，只有連字號或底線做為分隔符號。
responses – 包含代理程式在 API 回應中傳回的屬性。代理程式使用回應屬性來建構提示、準確處理 API 呼叫的結果，以及判斷執行任務的一組正確步驟。代理程式可以使用來自一個操作的回應值作為協調中後續步驟的輸入。

下列兩個物件中的欄位為您的代理提供更多資訊，使他們能有效利用您的動作群組。對於每個欄位，true如果需要，請將required欄位的值設定為，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 操作，以協助處理保險索賠。三個 APIs定義如下：

getAllOpenClaims – 如果需要開啟的宣告清單，您的客服人員可以使用 description 欄位來判斷是否應呼叫此 API 操作。properties 在 responses 中指定傳回 ID 和保單持有人和理賠的狀態。代理會將此資訊傳回給代理使用者，或使用部分或全部回應，以當做後續 API 呼叫的輸入。
identifyMissingDocuments – 如果必須為保險索賠識別缺少的文件，您的代理可以使用 description 欄位來判斷是否應呼叫此 API 操作。name、description 和 required 欄位會告訴代理，必須向客戶取得未結索賠的唯一識別碼。properties 在 responses 中指定傳回未結保險理賠的 ID。代理程式會傳回此資訊給最終使用者，或使用部分或全部回應做為後續 API 呼叫的輸入。
sendReminders – 您的客服人員可以使用 description 欄位，判斷如果需要向客戶傳送提醒，應該呼叫此 API 操作。例如，有關待處理文件的提醒，這些文件具有開放的宣告。properties 中的會requestBody告知客服人員，其必須找到宣告 IDs和待定文件。properties 中的會responses指定傳回提醒的 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 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

定義函數詳細資訊

處理動作的履行