Mendefinisikan 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 dipanggil agen menggunakan parameter ini. Untuk menentukan operasi API, buat OpenAPI skema dalam format JSON atau YAML. 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 Memodifikasi agen.

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

catatan

Agen Amazon Bedrock mendukung subset dari spesifikasi OpenAPI 3.0. Fitur skema berikut tidak didukung:

Bid enum ang untuk membatasi nilai parameter ke set tetap.

Jika Anda perlu membatasi nilai parameter, jelaskan nilai yang diizinkan di description bidang parameter sebagai gantinya.

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

Untuk detail lebih lanjut tentang OpenAPI skema, lihat OpenAPI spesifikasi 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 tindakan.


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

Daftar berikut menjelaskan bidang dalam OpenAPI skema

openapi— (Diperlukan) Versi OpenAPI yang sedang digunakan. Nilai ini harus "3.0.0" agar kelompok tindakan dapat bekerja.
paths— (Diperlukan) Berisi jalur relatif ke titik akhir individu. Setiap jalur harus dimulai dengan garis miring maju (/).
method— (Wajib) Mendefinisikan metode yang akan digunakan.
x-requireConfirmation— (Opsional) Menentukan apakah konfirmasi pengguna diperlukan sebelum melakukan tindakan. Aktifkan bidang ini untuk meminta konfirmasi dari pengguna sebelum tindakan dipanggil. Meminta konfirmasi pengguna sebelum melakukan 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 memerlukan bidang berikut:

description— Deskripsi operasi API. Gunakan bidang ini untuk memberi tahu agen kapan harus memanggil operasi API ini dan apa yang dilakukan operasi tersebut.
operationId— String unik yang mengidentifikasi operasi dalam API, seperti nama fungsi. Ini adalah bidang wajib untuk semua model yang diaktifkan toolUse baru seperti AnthropicClaude 3.5 Sonnet,Meta Llama, dll. Pastikan pengidentifikasi (Id) yang Anda berikan unik di semua operasi dan mengikuti pola alfanumerik sederhana dengan hanya tanda hubung atau garis bawah sebagai pemisah.
responses— Berisi properti yang dikembalikan agen dalam respons API. Agen menggunakan properti respons untuk membuat prompt, secara akurat memproses hasil panggilan API, dan menentukan serangkaian langkah yang benar untuk melakukan tugas. Agen dapat menggunakan nilai respons dari satu operasi sebagai input untuk langkah-langkah berikutnya dalam orkestrasi.

Bidang dalam dua objek berikut memberikan informasi lebih lanjut bagi agen Anda untuk secara efektif memanfaatkan grup tindakan Anda. Untuk setiap bidang, atur 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 tanggapan.
<media type>— Format badan tanggapan. Untuk informasi selengkapnya, lihat Jenis media di Swagger situs web.
schema— (Diperlukan untuk setiap jenis media) Mendefinisikan tipe data badan respons dan bidangnya.
properties— (Diperlukan jika ada items dalam skema) Agen Anda menggunakan properti yang Anda tentukan dalam skema untuk menentukan informasi yang diperlukan untuk dikembalikan ke pengguna akhir untuk memenuhi tugas. Setiap properti berisi bidang berikut:
- type— (Diperlukan untuk setiap properti) Jenis data bidang respons.
- description— (Opsional) Menjelaskan properti. Agen dapat menggunakan informasi ini untuk menentukan informasi yang diperlukan untuk dikembalikan ke pengguna akhir.

parameters


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

Agen Anda menggunakan bidang berikut untuk menentukan informasi yang harus didapat 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 apakah 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— (Diperlukan) 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 didapat dari pengguna akhir untuk membuat permintaan API. Setiap properti berisi bidang berikut:
- type— (Opsional) Jenis data dari bidang permintaan.
- description— (Opsional) Menjelaskan properti. Agen dapat menggunakan informasi ini untuk menentukan informasi yang dibutuhkan untuk dikembalikan ke pengguna akhir.

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

Contoh skema API

Contoh berikut menyediakan OpenAPI skema sederhana dalam format YAML yang mendapatkan cuaca untuk lokasi tertentu dalam 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 ia harus memanggil operasi API ini jika daftar klaim terbuka diperlukan. Di properties dalam responses menentukan untuk mengembalikan ID dan pemegang polis dan status klaim. Agen mengembalikan informasi ini ke pengguna agen atau menggunakan beberapa atau semua respons sebagai masukan untuk panggilan API berikutnya.
identifyMissingDocuments— Agen Anda dapat menggunakan description bidang untuk menentukan bahwa ia harus memanggil operasi API ini jika dokumen yang hilang harus diidentifikasi untuk klaim asuransi. Bid name angdescription,, dan required memberi tahu agen bahwa ia harus mendapatkan pengenal unik klaim terbuka dari pelanggan. Di properties dalam responses menentukan untuk mengembalikan ID klaim asuransi terbuka. Agen mengembalikan informasi ini ke pengguna akhir atau menggunakan beberapa atau semua respons sebagai input untuk panggilan API berikutnya.
sendReminders— Agen Anda dapat menggunakan description bidang untuk menentukan bahwa ia harus memanggil operasi API ini jika ada kebutuhan untuk mengirim pengingat kepada pelanggan. Misalnya, pengingat tentang dokumen tertunda yang mereka miliki untuk klaim terbuka. Di properties dalam requestBody memberi tahu agen bahwa ia harus menemukan ID klaim dan dokumen yang tertunda. Di properties dalam responses menentukan untuk mengembalikan ID pengingat dan statusnya. Agen mengembalikan informasi ini ke pengguna akhir atau menggunakan beberapa atau semua respons sebagai input 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 Contoh Deskripsi API di OpenAPI situs web.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Tentukan detail fungsi

Menangani pemenuhan tindakan