翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
定義 OpenAPI Amazon Bedrock でのエージェントのアクショングループのスキーマ
Amazon Bedrock でアクショングループを作成するときは、エージェントがユーザーから呼び出す必要があるパラメータを定義する必要があります。これらのパラメータを使用して、エージェントが呼び出すことができるAPIオペレーションを定義することもできます。API オペレーションを定義するには、 を作成します。OpenAPI JSON または YAML形式のスキーマ。作成できます。OpenAPI スキーマファイルを作成し、Amazon Simple Storage Service (Amazon S3) にアップロードします。または、OpenAPI コンソールのテキストエディタ。スキーマを検証します。エージェントを作成したら、エージェントにアクショングループを追加したり、既存のアクショングループを編集したりするときに、テキストエディタを使用できます。詳細については、「エージェントを変更する」を参照してください。
エージェントはスキーマを使用して、呼び出す必要があるAPIオペレーションと、APIリクエストの実行に必要なパラメータを決定します。その後、これらの詳細は、アクションを実行するために定義した Lambda 関数を通じて送信されるか、エージェントの呼び出しの応答で返されます。
API スキーマの詳細については、次のリソースを参照してください。
-
の詳細については、「」を参照してください。OpenAPI スキーマ、「」を参照してください。 OpenAPI の 仕様
Swagger ウェブサイト。 -
API スキーマ作成のベストプラクティスについては、「」のAPI「設計におけるベストプラクティス
」を参照してください。Swagger ウェブサイト。
以下は、 の一般的な形式です。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オペレーションを呼び出すタイミングと、オペレーションの動作をエージェントに通知します。 -
responses– エージェントがAPIレスポンスで返すプロパティが含まれます。エージェントは、レスポンスプロパティを使用してプロンプトを作成し、API通話の結果を正確に処理し、タスクを実行するための正しい一連のステップを決定します。エージェントは、オーケストレーションの後続のステップの入力として 1 つのオペレーションからのレスポンス値を使用できます。
次の 2 つのオブジェクト内のフィールドは、エージェントがアクショングループを効果的に活用するためのより多くの情報を提供します。フィールドごとに、true必要に応じて required フィールドの値を に設定し、オプションfalseの場合は に設定します。
-
parameters— リクエストに含めることができるパラメータに関する情報が含まれます。 -
requestBody— オペレーションのリクエスト本文内のフィールドが含まれます。GETおよびDELETEメソッドにはこのフィールドを含めないでください。
構造の詳細については、次のタブから選択します。
を追加する方法を学ぶには OpenAPI アクショングループの作成時に作成したスキーマについては、「」を参照してくださいAmazon Bedrock でアクショングループをエージェントに追加する。
API スキーマの例
次の例では、シンプルな OpenAPI 特定の場所の天気を摂氏で取得するYAML形式のスキーマ。
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オペレーションのグループを定義します。3 つの APIs は次のように定義されます。
-
getAllOpenClaims– エージェントはdescriptionフィールドを使用して、未解決のクレームのリストが必要な場合にこのAPIオペレーションを呼び出す必要があるかどうかを判断できます。responsesのpropertiesには、ID、保険契約者、請求のステータスを返すよう指定されています。エージェントはこの情報をエージェントユーザーに返すか、レスポンスの一部またはすべてを後続のAPI呼び出しの入力として使用します。 -
identifyMissingDocuments– エージェントはdescriptionフィールドを使用して、保険金請求で不足しているドキュメントを特定する必要がある場合に、このAPIオペレーションを呼び出す必要があるかどうかを判断できます。name、description、およびrequiredフィールドは、未解決請求の固有識別子をカスタマーから引き出す必要があることをエージェントに伝えます。propertiesの は、未解決の保険金請求IDsの を返すようにresponses指定します。エージェントはこの情報をエンドユーザーに返すか、レスポンスの一部またはすべてを後続のAPI呼び出しの入力として使用します。 -
sendReminders– エージェントはdescriptionフィールドを使用して、顧客にリマインダーを送信する必要がある場合にこのAPIオペレーションを呼び出す必要があるかどうかを判断できます。例えば、未解決のクレームについて保留中のドキュメントに関するリマインダーなどです。propertiesの はrequestBody、クレームIDsと保留中のドキュメントを見つける必要があることをエージェントに伝えます。propertiesの は、リマインダーの ID とそのステータスを返すようにresponses指定します。エージェントはこの情報をエンドユーザーに返すか、レスポンスの一部またはすべてを後続の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 スキーマについては、 GitHub ウェブサイトのhttps://github.com/OAI/「OpenAPI-Specification/tree/main/examples/v3.0
