Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Server-side penggunaan alat
Jika Anda menggunakan Responses API untuk memanggil model, maka itu dapat menggunakan pemanggilan alat sisi server, selain pemanggilan alat sisi klien yang telah kita bahas sebelumnya. Server-side pemanggilan alat adalah mekanisme di mana alat (API, fungsi, alur kerja) dijalankan di lingkungan backend tepercaya, bukan pada klien. Ini meningkatkan keamanan, keandalan, dan postur tata kelola aplikasi. Sebelum Amazon Bedrock menjalankan fungsi Lambda yang mengimplementasikan penggunaan alat, ini memastikan bahwa fungsi Lambda memiliki kebijakan IAM yang sama dengan aplikasi yang memanggilnya. Karena Amazon Bedrock mendorong eksekusi alat, klien dapat fokus pada penerapan logika bisnis mereka, daripada menambahkan fungsionalitas alat. Amazon Bedrock juga mendukung standar tata kelola tertinggi seperti ISO, SOC, dan HIPAA yang memenuhi syarat. Pelanggan dapat mengirimkan fungsi Lambda kustom mereka sendiri untuk menjalankan alat atau menggunakan alat yang telah ditentukan sebelumnya, seperti catatan dan tugas. Server-side alat yang menggunakan Responses API tersedia dimulai dengan model OSS GPT OSS OpenAI, dengan dukungan untuk 20B/120B model lain segera hadir. Anda dapat menggunakan Models API untuk menemukan model yang tersedia yang dapat Anda gunakan dengan API Responses. Untuk detail selengkapnya tentang API Responses, lihat [Menghasilkan respons menggunakan API OpenAI](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html).
Ada dua jenis alat yang dapat Anda gunakan dengan Amazon Bedrock: Alat khusus menggunakan Lambda, atau alat yang telah ditentukan sebelumnya yang didukung oleh Bedrock. Pada bagian ini kita akan meninjau cara membuat alat Lambda khusus dengan API Responses. Mari kita bahas keduanya secara detail.
**Alat kustom menggunakan Lambda di Responses API**
Dengan menggunakan fungsi Lambda sebagai alat khusus di Bedrock, Anda dapat memperluas kemampuan agen dengan mengintegrasikan fungsi AWS Lambda khusus sebagai alat. Ini memungkinkan Anda membuat alat tanpa server dan dapat diskalakan yang dapat dipanggil oleh asisten AI dan aplikasi lain melalui Model Context Protocol (MCP). Berikut adalah kelebihan dari fitur ini:
+ Perluas Fungsionalitas: Tambahkan logika bisnis khusus, integrasi API, atau kemampuan pemrosesan data.
+ Jalankan alat dengan aman: Lambda memungkinkan alat untuk mengakses sumber daya di dalam VPC tanpa harus memberikan akses VPC penuh.
+ Arsitektur Tanpa Server: Tidak ada manajemen infrastruktur, Lambda menangani penskalaan secara otomatis.
+ Hemat Biaya: Bayar hanya untuk waktu eksekusi, bukan sumber daya yang menganggur.
+ Integrasi Mudah: Fungsi Lambda muncul bersama alat bawaan dengan mulus.
Agar model di Amazon Bedrock menggunakan alat untuk menyelesaikan respons pesan, Anda mengirim pesan dan definisi untuk satu atau beberapa alat ke model. Berdasarkan prompt aplikasi Anda, jika model menentukan bahwa salah satu alat dapat membantu menghasilkan respons, ia mengembalikan permintaan untuk Bedrock untuk menggunakan alat dan mengirim hasil alat kembali ke model. Model kemudian menggunakan hasil untuk menghasilkan respons terhadap pesan asli.
Langkah-langkah berikut menunjukkan cara menggunakan alat dengan [Responses API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html).
**Cara kerjanya**
1. Fungsi **Lambda: Buat fungsi** Lambda Anda yang mengimplementasikan protokol MCP
1. **Penemuan Alat**: Bedrock memanggil fungsi Lambda Anda untuk menemukan alat yang tersedia
1. **Pendaftaran Alat**: Alat Anda terdaftar di Bedrock
1. **Eksekusi Alat**: Saat agen meminta alat Anda, Bedrock memanggil fungsi Lambda Anda
1. **Response Handling**: Hasil dikembalikan ke agen melalui antarmuka standar
**Langkah 1: Tentukan fungsi Lambda untuk mendapatkan lagu paling populer**
Buat fungsi Lambda yang mengimplementasikan protokol MCP. Berikut adalah contoh Python sederhana:
```
import json
def lambda_handler(event, context):
# Parse JSON-RPC request
method = event.get('method')
params = event.get('params', {})
request_id = event.get('id')
if method == 'tools/list':
return {
"jsonrpc": "2.0",
"id": request_id,
"result": {
"tools": [
{
"name": "my_custom_tool",
"description": "My custom business logic tool",
"inputSchema": {
"type": "object",
"properties": {
"input": {
"type": "string",
"description": "Input text to process"
}
},
"required": ["input"]
}
}
]
}
}
elif method == 'tools/call':
tool_name = params.get('name')
arguments = params.get('arguments', {})
if tool_name == 'my_custom_tool':
# Your custom logic here
result = f"Processed: {arguments.get('input', '')}"
return {
"jsonrpc": "2.0",
"id": request_id,
"result": {
"content": [
{
"type": "text",
"text": result
}
]
}
}
# Error response for unsupported methods
return {
"jsonrpc": "2.0",
"id": request_id,
"error": {
"code": -32601,
"message": "Method not found"
}
}
```
**Langkah 2: Menyebarkan fungsi Lambda**
Selanjutnya, gunakan peran IAM Anda untuk menerapkan fungsi Lambda ini untuk mendapatkan ARN. [Anda dapat membaca lebih lanjut tentang penerapan fungsi Lambda di sini.](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)
```
# Example using AWS CLI
aws lambda create-function \
--function-name my-custom-tool \
--runtime python3.14 \
--role arn:aws:iam::YOUR-ACCOUNT:role/lambda-execution-role \
--handler lambda_function.lambda_handler \
--zip-file fileb://function.zip
```
Katakanlah ARN Anda adalah: `arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool`
**Langkah 3: Tentukan definisi pesan dan alat dalam permintaan inferensi Anda**
Untuk mengirim pesan dan definisi alat, Anda menggunakan operasi [Responses API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Amazon Bedrock menggunakan [konektor dan fungsionalitas server MCP jarak jauh](https://platform.openai.com/docs/guides/tools-connectors-mcp) dari Responses API untuk menyediakan kemampuan penggunaan alat. Definisi alat ini adalah skema JSON yang Anda teruskan dalam parameter permintaan mcp ke operasi Create. Di `connector_id` bidang di API konektor Responses, Anda dapat meneruskan ARN Lambda yang telah Anda buat di langkah sebelumnya. Anda tidak perlu memberikan kredensi otorisasi karena Bedrock menggunakan peran dan kebijakan IAM yang sama yang digunakan untuk aplikasi Anda yang memanggil model. Berikut ini adalah contoh skema untuk alat yang mendapatkan lagu paling populer diputar di stasiun radio.
```
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="oss-gpt-120b",
tools=[
{
"type": "mcp",
"server_label": "xamzn_arn",
"connector_id": "arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool",
"require_approval": "never",
},
],
input="My custom prompt.",
)
print(resp.output_text)
```
**Langkah 4: Bedrock memanggil alat dan meneruskan respons kembali ke model**
Kemampuan untuk menggunakan alat konektor tersedia dalam model yang mendukung [Responses API](https://platform.openai.com/docs/api-reference/responses/create). Periksa alat mana yang mendukung model Anda [di sini](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Saat menggunakan alat yang menggunakan API Responses, Anda hanya membayar [token](https://platform.openai.com/docs/pricing) yang digunakan saat mengimpor definisi alat atau melakukan panggilan alat. Tidak ada biaya tambahan yang terlibat per panggilan alat.
Ketika Anda menentukan fungsi Lambda dalam `tools` parameter, API akan mencoba untuk mendapatkan daftar alat dari server. Jika berhasil mengambil daftar alat, item `mcp_list_tools` keluaran baru akan muncul di output respons model. `tools`Properti objek ini akan menunjukkan alat yang berhasil diimpor. Setelah model memiliki akses ke definisi alat ini, ia dapat memilih untuk memanggilnya tergantung pada apa yang ada dalam konteks model. Ketika model memutuskan untuk memanggil alat Lambda, API akan membuat permintaan ke fungsi Lambda untuk memanggil alat dan memasukkan outputnya ke dalam konteks model. Anda dapat membaca lebih lanjut tentang alat daftar dan alat panggilan di dokumentasi [OpenAI](https://platform.openai.com/docs/guides/tools-connectors-mcp?quickstart-panels=connector). Perhatikan bahwa fungsi Lambda Anda harus memiliki peran dan kebijakan IAM yang sama dengan fungsi aplikasi yang memanggil model di Bedrock, jika tidak, fungsi Lambda akan gagal. Berikut ini adalah definisi kesalahan.
```
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32000,
"message": "Tool execution failed",
"data": "Additional error details"
}
}
```
**Menggunakan alat yang disediakan AWS di Responses API**
Ada dua alat yang disediakan AWS yang dibangun ke dalam `openai.gpt-oss-20b` dan `openai.gpt-oss-120b` model: Note-taking fungsionalitas (alat catatan) dan Manajemen tugas (alat tugas). Alat-alat ini tersedia secara otomatis — Anda tidak perlu mendefinisikannya dalam `tools` parameter.
**Ikhtisar Alat Catatan**
`notes`Alat ini memungkinkan model untuk menyimpan catatan dalam sesi percakapan yang sama. Ini menyediakan mekanisme memori sederhana untuk mempertahankan konteks di berbagai interaksi. Memori hanya tercakup pada percakapan saat ini.
Ketika model menggunakan alat catatan, ia memancarkan `mcp_call` output dengan `name` set ke`"notes"`. Model menentukan argumen yang sesuai berdasarkan permintaan Anda.
Anda dapat menggunakan salah satu bahasa alami (misalnya “Ingat bahwa warna favorit saya adalah biru”, “Apa yang saya ceritakan tentang warna favorit saya?” , “Simpan fakta bahwa saya lebih suka rapat pagi”, “Ingat apa yang saya katakan tentang preferensi rapat”) atau Anda dapat menggunakan panggilan alat langsung di prompt Anda (“Gunakan alat catatan untuk menyimpan email saya sebagai john@example.com “, “Periksa catatan untuk alamat email saya”).
**Ikhtisar Alat Tugas**
`tasks`Alat ini menyediakan tumpukan untuk mengelola tugas dalam sesi percakapan. Anda dapat mendorong tugas ke tumpukan dan memunculkannya, sehingga berguna untuk mengelola alur kerja, pengingat, atau manajemen tugas hierarkis. Tugas tetap ada di seluruh sesi percakapan. Memori hanya tercakup pada percakapan saat ini.
Ketika model menggunakan alat tugas, ia memancarkan `mcp_call` output dengan `name` set ke`"tasks"`. Model menentukan argumen yang sesuai (seperti`method`,`task.title`, dan`task.description`) berdasarkan permintaan Anda.
Anda dapat memanggil alat Tugas dengan menggunakan bahasa alami (misalnya “Tambahkan tugas untuk meninjau anggaran”, “Dorong pengingat untuk memanggil klien”, “Apa tugas selanjutnya yang perlu saya lakukan?” , “Pop tugas terbaru”, “Dapatkan tugas terbaru dari tumpukan saya”) atau Anda dapat memanggil alat langsung di prompt Anda (“Gunakan alat tugas untuk mendorong 'menyelesaikan presentasi'”, “Pop tugas dari tumpukan”, “Tambahkan 'jadwalkan pertemuan' ke daftar tugas saya”).
**Contoh kode: Menggunakan catatan dan alat tugas**
Catatan dan alat tugas dibangun ke dalam `openai.gpt-oss-20b` dan `openai.gpt-oss-120b` model. Anda tidak perlu mendefinisikannya secara eksplisit dalam `tools` parameter — cukup referensikan mereka di prompt Anda:
```
from openai import OpenAI
client = OpenAI(
base_url="https://bedrock-mantle.us-east-1.api.aws/v1"
)
# The notes tool is built-in — just ask the model to use it
resp = client.responses.create(
model="openai.gpt-oss-120b",
input="Use the notes tool to store that my preferred language is Python.",
)
print(resp.output)
# The model automatically calls the notes tool via mcp_call
# Use the tasks tool to push a task
resp = client.responses.create(
model="openai.gpt-oss-120b",
input="Use the tasks tool to push a task: review the API documentation",
)
print(resp.output)
```
## Server-side integrasi penggunaan alat dengan Gateway AgentCore
Amazon Bedrock sekarang mendukung [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) sebagai alat server-side memanggil tipe integrasi. Fitur ini memungkinkan Anda untuk menghubungkan model Anda secara langsung ke titik akhir AgentCore Gateway, memungkinkan akses tanpa batas ke alat yang dikelola melalui infrastruktur gateway.
Integrasi AgentCore Gateway mengikuti pola yang sama dengan integrasi fungsi Lambda, dengan satu perbedaan utama.
**Integrasi Lambda:**
+ Menggunakan ARN fungsi Lambda
+ Langsung memanggil fungsi AWS Lambda
**AgentCore Integrasi Gateway:**
+ Menggunakan AgentCore ARN Gateway
+ Rutekan panggilan alat melalui infrastruktur AgentCore Gateway
+ Menyediakan manajemen dan penemuan alat terpusat
### Konfigurasi
**Struktur Permintaan**
Saat mengonfigurasi AgentCore Gateway sebagai sumber alat, gunakan struktur berikut dalam `tools` array Anda dalam permintaan API Responses Anda.
```
{
"type":"mcp",
"server_label":"agentcore_tools",
"connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp",
"server_description":"AgentCore Gateway providing custom tools",
"require_approval":"never"
}
```
**Parameter**
| Parameter | Tipe | Diperlukan | Deskripsi |
| --- | --- | --- | --- |
| type | string | Ya | Harus diatur ke mcp |
| server\_label | string | Ya | Pengenal unik untuk konektor alat ini dalam permintaan Anda |
| connector\_id | string | Ya | ARN dari Gateway Anda AgentCore |
| server\_description | string | Tidak | Human-readable deskripsi alat yang disediakan oleh gateway ini |
| require\_approval | string | Ya | Bidang harus "never" |
**Contoh Permintaan Lengkap**
```
{
"model":"openai.gpt-oss-120b",
"stream":true,
"background":false,
"store":false,
"tools": [
{
"type":"mcp",
"server_label":"agentcore_tools",
"connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp",
"server_description":"AgentCore Gateway providing custom tools",
"require_approval":"never"
}
],
"input": [
{
"type":"message",
"role":"user",
"content": [
{
"type":"input_text",
"text":"What is the weather in Seattle?"
}
]
}
]
}
```
### Prasyarat
Sebelum menggunakan integrasi AgentCore Gateway, pastikan Anda memiliki:
1. **Membuat AgentCore Gateway dengan target yang** dikonfigurasi (fungsi Lambda, tahapan API Gateway, skema OpenAPI, atau server MCP)
1. **Izin IAM yang dikonfigurasi** memungkinkan peran layanan Bedrock Anda untuk memanggil gateway. Perhatikan bahwa Bedrock hanya mendukung gateway dengan autentikasi IAM.
1. **Gateway ARN dalam format** yang benar
### Manfaat Integrasi AgentCore Gateway
+ **Manajemen Alat Terpusat**: Kelola semua alat Anda melalui titik akhir gateway tunggal
+ **Penemuan Alat**: Agen dapat secara dinamis menemukan alat yang tersedia melalui gateway
+ **Keamanan**: Built-in otentikasi dan otorisasi melalui IAM dan kebijakan gateway
+ **Observabilitas**: Pemantauan komprehensif dan pencatatan pemanggilan alat
+ **Fleksibilitas**: Dukungan untuk beberapa jenis target (Lambda, API Gateway, OpenAPI, server MCP)
### Izin IAM
Peran eksekusi Bedrock Anda memerlukan izin untuk memanggil Gateway: AgentCore
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeGateway"
],
"Resource": "arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp"
}
]
}
```
### Langkah Berikutnya
+ Pelajari selengkapnya tentang [membuat AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create.html)
+ Jelajahi [jenis target gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-targets.html)
+ Tinjau [praktik terbaik keamanan gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-security.html)