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.

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:

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.

Cara kerjanya

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.

# 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. Amazon Bedrock menggunakan konektor dan fungsionalitas server MCP jarak jauh 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. Periksa alat mana yang mendukung model Anda di sini. Saat menggunakan alat yang menggunakan API Responses, Anda hanya membayar token 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. toolsProperti 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. 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

notesAlat 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

tasksAlat 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 (sepertimethod,task.title, dantask.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 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:

AgentCore Integrasi Gateway:

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

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:

Manfaat Integrasi AgentCore Gateway

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