Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
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 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 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 OpenAPI spesifikasi
pada Swagger situs web. -
Untuk praktik terbaik dalam menulis skema API, lihat Praktik terbaik dalam desain API
di Swagger situs web.
Berikut ini adalah format umum dari 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 ke depan (/). -
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 adalahDISABLEDjika bidang ini tidak ditentukan.
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. -
operationId— String unik yang mengidentifikasi operasi di API, seperti nama fungsi. Ini adalah bidang wajib untuk semua model baru yang diaktifkan ToolUse 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 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 untukGETdanDELETEmetode.
Untuk mempelajari lebih lanjut tentang struktur, pilih dari tab berikut.
"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 mediadi Swagger situs web. -
schema— (Diperlukan untuk setiap jenis media) Mendefinisikan tipe data dari badan respons dan bidangnya. -
properties— (Diperlukan jika adaitemsdalam 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.
-
Untuk mempelajari cara menambahkan OpenAPI skema yang Anda buat saat membuat grup aksi, lihatTambahkan grup tindakan ke agen Anda di Amazon Bedrock.
Contoh skema API
Contoh berikut memberikan sederhana OpenAPI skema 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: stringContoh skema API berikut mendefinisikan sekelompok operasi API yang membantu menangani klaim asuransi. Tiga APIs didefinisikan sebagai berikut:
-
getAllOpenClaims— Agen Anda dapat menggunakandescriptionbidang untuk menentukan bahwa itu harus memanggil operasi API ini jika daftar klaim terbuka diperlukan.propertiesDalamresponsesmenentukan 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 menggunakandescriptionbidang ini untuk menentukan bahwa itu harus memanggil operasi API ini jika dokumen yang hilang harus diidentifikasi untuk klaim asuransi.requiredBidangnamedescription,, dan memberi tahu agen bahwa ia harus mendapatkan pengenal unik dari klaim terbuka dari pelanggan.propertiesDalamresponsesmenentukan untuk mengembalikan IDs 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 menggunakandescriptionbidang 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.propertiesDalamrequestBodymemberitahu agen bahwa ia harus menemukan klaim IDs dan dokumen yang tertunda.propertiesDalamresponsesmenentukan 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 lebih banyak contoh OpenAPI skema, lihat Contoh Deskripsi API
