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 Specification」を参照してください。
API スキーマを作成するときのベストプラクティスについては、Swagger ウェブサイトの「Best Practices in API Design」を参照してください。

アクショングループの 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 内のオペレーションを識別する一意の文字列。これは、Anthropic Claude 3.5 Sonnet や Meta Llama など、すべての新しい toolUse 対応モデルにおいて必須フィールドです。指定した識別子 (ID) がすべてのオペレーションで一意であり、ハイフンまたはアンダースコアのみを区切り文字として単純な英数字パターンに従っていることを確認します。
responses – API レスポンスでエージェントが返すプロパティが含まれます。エージェントは、レスポンスプロパティを使用してプロンプトを作成し、API コールの結果を正確に処理して、タスクを実行するための正しい一連のステップを決定します。エージェントは、1 つのオペレーションからのレスポンス値を、オーケストレーションでの後続のステップの入力として使用できます。

次の 2 つのオブジェクト内のフィールドは、エージェントがアクショングループを効果的に活用するためのより多くの情報を提供します。フィールドごとに、必須の場合は 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 ウェブサイトの「Media Types」を参照してください。
schema — (各メディアタイプに必須) レスポンス本体とそのフィールドのデータタイプを定義します。
properties — (スキーマに items が存在する場合は必須) エージェントは、スキーマで定義したプロパティを使用して、タスクを実行するためにエンドユーザーに返す必要のある情報を決定します。各プロパティには、次のフィールドが含まれます。
- type — (各プロパティに必須) レスポンスフィールドのデータタイプ。
- description — (オプション) プロパティについて説明します。エージェントはこの情報を使用して、エンドユーザーに返す必要のある情報を判断できます。

parameters


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

エージェントは次のフィールドを使用して、アクショングループの要件を実行するためにエンドユーザーから取得する必要のある情報を判断します。

name – (必須) パラメータの名前。
description – (必須) パラメータの説明。このフィールドを使用すると、エージェントがエージェントユーザーからこのパラメータを引き出す方法を理解したり、以前のアクションまたはユーザーのエージェントへのリクエストからそのパラメータ値がすでに設定されているかを判断できます。
required — (オプション) API リクエストでパラメータが必須かどうか。このフィールドを使用して、このパラメータが呼び出しのたびに必要かオプションかをエージェントに示します。
schema — (オプション) 入力データ型と出力データ型の定義。詳細については、Swagger ウェブサイトの「Data Models (Schemas)」を参照してください。

requestBody

以下は、requestBody フィールドの一般的な構造です。


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

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

required — (オプション) API リクエストにリクエスト本文が必要かどうか。
content — (必須) リクエスト本文のコンテンツ。
<media type> — (オプション) リクエスト本文の形式。詳細については、Swagger ウェブサイトの「Media Types」を参照してください。
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 つの API は次のように定義されます。

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

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

ドキュメントの表記規則

関数の詳細を定義する

アクションの履行を処理する