Mendefinisikan OpenAPI skema untuk grup aksi agen Anda di Amazon Bedrock - Amazon Bedrock
Contoh API skema

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mendefinisikan OpenAPI skema untuk grup aksi 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 API operasi yang dapat dijalankan agen menggunakan parameter ini. Untuk menentukan API operasi, buat OpenAPI skema dalam JSON atau YAML format. Anda dapat membuat OpenAPI skema file dan unggah ke Amazon Simple Storage Service (Amazon S3). Atau, Anda dapat menggunakan OpenAPI editor 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 Memodifikasi agen.

Agen menggunakan skema untuk menentukan API operasi 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 API skema, lihat sumber daya berikut:

Berikut ini adalah format umum dari sebuah OpenAPI skema untuk kelompok aksi.

{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... },
                "x-requireConfirmation": ENABLED | DISABLED
           }
       }
    }
}

Daftar berikut menjelaskan bidang di OpenAPI skema

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

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

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

  • x-requireConfirmation— (Opsional) Menentukan apakah konfirmasi pengguna diperlukan sebelum menjalankan tindakan. Aktifkan bidang ini untuk meminta konfirmasi dari pengguna sebelum tindakan dipanggil. Meminta konfirmasi pengguna sebelum menjalankan tindakan dapat melindungi aplikasi Anda dari mengambil tindakan karena suntikan cepat yang berbahaya. Secara default, konfirmasi pengguna adalah DISABLED jika bidang ini tidak ditentukan.

Minimal, setiap metode membutuhkan bidang-bidang berikut:

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

  • operationId— String unik yang mengidentifikasi operasi dalamAPI, seperti nama fungsi. Ini adalah bidang wajib untuk semua model baru yang toolUse diaktifkan seperti Anthropic Claude 3.5 Sonnet, Meta Llama, dll. Pastikan bahwa identifier (Id) yang Anda berikan unik di semua operasi dan ikuti pola alfanumerik sederhana dengan hanya tanda hubung atau garis bawah sebagai pemisah.

  • responses— Berisi properti yang dikembalikan agen dalam API respons. Agen menggunakan properti respons untuk membuat prompt, memproses hasil API panggilan 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 API permintaan. 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 selengkapnya, 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 API permintaan tersebut.

  • content— (Wajib) Isi 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 API permintaan. 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 aksi, lihatMenambahkan grup tindakan ke agen Anda di Amazon Bedrock.

Contoh API skema

Contoh berikut memberikan sederhana OpenAPI skema dalam YAML format 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 API skema berikut mendefinisikan sekelompok API operasi yang membantu menangani klaim asuransi. Tiga APIs didefinisikan sebagai berikut:

  • getAllOpenClaims— Agen Anda dapat menggunakan description bidang ini untuk menentukan bahwa itu harus memanggil API operasi 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 API panggilan berikutnya.

  • identifyMissingDocuments— Agen Anda dapat menggunakan description lapangan untuk menentukan bahwa itu harus memanggil API operasi 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 IDs klaim asuransi terbuka. Agen mengembalikan informasi ini ke pengguna akhir atau menggunakan sebagian atau semua respons sebagai masukan untuk API panggilan berikutnya.

  • sendReminders— Agen Anda dapat menggunakan description lapangan untuk menentukan bahwa itu harus memanggil API operasi ini jika ada kebutuhan untuk mengirim pengingat kepada pelanggan. Misalnya, pengingat tentang dokumen yang tertunda yang mereka miliki untuk klaim terbuka. propertiesDalam requestBody memberitahu agen bahwa ia harus menemukan klaim IDs 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 API panggilan 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 lebih banyak contoh OpenAPI skema, lihat Contoh API Deskripsi pada OpenAPI situs web.