Tentukan OpenAPI skema untuk grup tindakan agen Anda di Amazon Bedrock

Saat membuat grup tindakan di Amazon Bedrock, Anda harus menentukan parameter yang perlu dipanggil agen dari pengguna. Anda juga dapat menentukan operasi API yang dapat dijalankan agen menggunakan parameter ini. Untuk menentukan operasi API, buat OpenAPI skema dalam format JSON atau YAMAL. Anda dapat membuat file OpenAPI skema dan mengunggahnya ke Amazon Simple Storage Service (Amazon S3). Atau, Anda dapat menggunakan editor OpenAPI teks di konsol, yang akan memvalidasi skema Anda. Setelah membuat agen, Anda dapat menggunakan editor teks saat menambahkan grup tindakan ke agen atau mengedit grup tindakan yang ada. Untuk informasi selengkapnya, lihat Edit agen.

Agen menggunakan skema untuk menentukan operasi API yang perlu dipanggil dan parameter yang diperlukan untuk membuat permintaan API. Detail ini kemudian dikirim melalui fungsi Lambda yang Anda tentukan untuk melakukan tindakan atau dikembalikan sebagai respons pemanggilan agen.

Untuk informasi selengkapnya tentang skema API, lihat sumber daya berikut:

• Untuk detail lebih lanjut tentang OpenAPI skema, lihat OpenAPIspesifikasi di situs Swagger web.

• Untuk praktik terbaik dalam menulis skema API, lihat Praktik terbaik dalam desain API di Swagger situs web.

Berikut ini adalah format umum OpenAPI skema untuk grup aksi.

{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... }
           }
       }
    }
}

Daftar berikut menjelaskan bidang dalam OpenAPI skema

• openapi— (Wajib) Versi OpenAPI yang sedang digunakan. Nilai ini harus "3.0.0" agar kelompok aksi dapat bekerja.

• paths— (Diperlukan) Berisi jalur relatif ke titik akhir individu. Setiap jalur harus dimulai dengan garis miring ke depan (/).

• method— (Wajib) Mendefinisikan metode yang akan digunakan.

Minimal, setiap metode membutuhkan bidang-bidang berikut:

• description— Deskripsi operasi API. Gunakan bidang ini untuk memberi tahu agen kapan harus memanggil operasi API ini dan apa yang dilakukan operasi.

• responses— Berisi properti yang dikembalikan agen dalam respons API. Agen menggunakan properti respons untuk membuat prompt, memproses hasil panggilan API secara akurat, dan menentukan serangkaian langkah yang benar untuk melakukan tugas. Agen dapat menggunakan nilai respons dari satu operasi sebagai input untuk langkah selanjutnya dalam orkestrasi.

Bidang dalam dua objek berikut memberikan informasi lebih lanjut bagi agen Anda untuk secara efektif memanfaatkan kelompok tindakan Anda. Untuk setiap bidang, tetapkan nilai required bidang ke true jika diperlukan dan false jika opsional.

• parameters— Berisi informasi tentang parameter yang dapat dimasukkan dalam permintaan.

• requestBody— Berisi bidang di badan permintaan untuk operasi. Jangan sertakan bidang ini untuk GET dan DELETE metode.

Untuk mempelajari lebih lanjut tentang struktur, pilih dari tab berikut.

responses

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

Setiap kunci dalam responses objek adalah kode respons, yang menggambarkan status respons. Kode respons memetakan ke objek yang berisi informasi berikut untuk respons:

• content— (Diperlukan untuk setiap respons) Isi respons.

• <media type>— Format badan respons. Untuk informasi selengkapnya, lihat Jenis media di Swagger situs web.

• schema— (Diperlukan untuk setiap jenis media) Mendefinisikan tipe data dari badan respons dan bidangnya.

• properties— (Diperlukan jika ada items dalam skema) Agen Anda menggunakan properti yang Anda tentukan dalam skema untuk menentukan informasi yang dibutuhkan untuk kembali ke pengguna akhir untuk memenuhi tugas. Setiap properti berisi bidang-bidang berikut:

  • type— (Diperlukan untuk setiap properti) Tipe data dari bidang respons.

  • description— (Opsional) Menjelaskan properti. Agen dapat menggunakan informasi ini untuk menentukan informasi yang diperlukan untuk kembali ke pengguna akhir.

parameters

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

Agen Anda menggunakan bidang berikut untuk menentukan informasi yang harus diperoleh dari pengguna akhir untuk melakukan persyaratan grup tindakan.

• name— (Wajib) Nama parameter.

• description— (Diperlukan) Deskripsi parameter. Gunakan bidang ini untuk membantu agen memahami cara mendapatkan parameter ini dari pengguna agen atau menentukan bahwa parameter tersebut sudah memiliki nilai parameter tersebut dari tindakan sebelumnya atau dari permintaan pengguna ke agen.

• required— (Opsional) Apakah parameter diperlukan untuk permintaan API. Gunakan bidang ini untuk menunjukkan kepada agen apakah parameter ini diperlukan untuk setiap pemanggilan atau jika itu opsional.

• schema— (Opsional) Definisi tipe data input dan output. Untuk informasi lebih lanjut, lihat Model Data (Skema) di Swagger situs web.

requestBody

Berikut ini adalah struktur umum suatu requestBody bidang:

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

Daftar berikut menjelaskan setiap bidang:

• required— (Opsional) Apakah badan permintaan diperlukan untuk permintaan API.

• content— (Wajib) Isi dari badan permintaan.

• <media type>— (Opsional) Format badan permintaan. Untuk informasi selengkapnya, lihat Jenis media di Swagger situs web.

• schema— (Opsional) Mendefinisikan tipe data dari badan permintaan dan bidangnya.

• properties— (Opsional) Agen Anda menggunakan properti yang Anda tentukan dalam skema untuk menentukan informasi yang harus diperoleh dari pengguna akhir untuk membuat permintaan API. Setiap properti berisi bidang-bidang berikut:

  • type— (Opsional) Tipe data dari bidang permintaan.

  • description— (Opsional) Menjelaskan properti. Agen dapat menggunakan informasi ini untuk menentukan informasi yang dibutuhkan untuk kembali ke pengguna akhir.

Untuk mempelajari cara menambahkan OpenAPI skema yang Anda buat saat membuat grup tindakan, lihatMenambahkan grup tindakan ke agen Anda di Amazon Bedrock.

Contoh skema API

Contoh berikut menyediakan OpenAPI skema sederhana dalam format YAMAL yang mendapatkan cuaca untuk lokasi tertentu di Celcius.

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

Contoh skema API berikut mendefinisikan sekelompok operasi API yang membantu menangani klaim asuransi. Tiga API didefinisikan sebagai berikut:

• getAllOpenClaims— Agen Anda dapat menggunakan description bidang untuk menentukan bahwa itu harus memanggil operasi API ini jika daftar klaim terbuka diperlukan. propertiesDalam responses menentukan untuk mengembalikan ID dan pemegang polis dan status klaim. Agen mengembalikan informasi ini ke pengguna agen atau menggunakan sebagian atau semua respons sebagai masukan untuk panggilan API berikutnya.

• identifyMissingDocuments— Agen Anda dapat menggunakan description bidang ini untuk menentukan bahwa itu harus memanggil operasi API ini jika dokumen yang hilang harus diidentifikasi untuk klaim asuransi. requiredBidang namedescription,, dan memberi tahu agen bahwa ia harus mendapatkan pengenal unik dari klaim terbuka dari pelanggan. propertiesDalam responses menentukan untuk mengembalikan ID klaim asuransi terbuka. Agen mengembalikan informasi ini ke pengguna akhir atau menggunakan sebagian atau semua respons sebagai masukan untuk panggilan API berikutnya.

• sendReminders— Agen Anda dapat menggunakan description bidang untuk menentukan bahwa itu harus memanggil operasi API ini jika ada kebutuhan untuk mengirim pengingat ke pelanggan. Misalnya, pengingat tentang dokumen yang tertunda yang mereka miliki untuk klaim terbuka. propertiesDalam requestBody memberitahu agen bahwa ia harus menemukan ID klaim dan dokumen yang tertunda. propertiesDalam responses menentukan untuk mengembalikan ID pengingat dan statusnya. Agen mengembalikan informasi ini ke pengguna akhir atau menggunakan sebagian atau semua respons sebagai masukan untuk panggilan API berikutnya.

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

Untuk contoh OpenAPI skema lainnya, lihat https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v3.0 di situs GitHub web.