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": { ... }
           }
       }
    }
}

次のリストでは、OpenAPIスキーマのフィールドについて説明します。

openapi – (必須) OpenAPI使用されているのバージョン。アクショングループが動作するには、この値が "3.0.0" 以上である必要があります。
paths — (必須) 個々のエンドポイントへの相対パスが含まれます。各パスはスラッシュ () で始まる必要があります/。
method — (必須) 使用する方法を定義します。

少なくとも、各メソッドには次のフィールドが必要です。

description — API オペレーションの説明。このフィールドを使用して、この API オペレーションを呼び出すタイミングと、オペレーションの動作をエージェントに通知します。
responses – エージェントが API レスポンスで返すプロパティが含まれます。エージェントはレスポンスプロパティを使用してプロンプトを作成し、API コールの結果を正確に処理し、タスクを実行するための正しいステップのセットを決定します。エージェントは、オーケストレーションの後続のステップの入力として 1 つのオペレーションからのレスポンス値を使用できます。

次の 2 つのオブジェクト内のフィールドは、エージェントがアクショングループを効果的に活用するためのより多くの情報を提供します。フィールドごとに、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 オペレーションのグループを定義します。3 つの APIsは次のように定義されます。

getAllOpenClaims – エージェントは descriptionフィールドを使用して、未解決のクレームのリストが必要な場合にこの API オペレーションを呼び出す必要があるかどうかを判断できます。responses の properties には、ID、保険契約者、請求のステータスを返すよう指定されています。エージェントはこの情報をエージェントユーザーに返すか、レスポンスの一部または全部を後続の API コールの入力として使用します。
identifyMissingDocuments – エージェントは descriptionフィールドを使用して、保険金請求で不足しているドキュメントを特定する必要がある場合に、この API オペレーションを呼び出す必要があるかどうかを判断できます。name、description、および required フィールドは、未解決請求の固有識別子をカスタマーから引き出す必要があることをエージェントに伝えます。responses の properties には、未解決の保険金請求の ID を返すよう指定します。エージェントはこの情報をエンドユーザーに返すか、レスポンスの一部またはすべてを後続の 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。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

関数の詳細を定義する

アクションのフルフィルメントの処理