View a markdown version of this page

Target AgentCore Runtime Amazon Bedrock - Batuan Dasar Amazon AgentCore
Pertimbangan dan keterbatasan utamaKonfigurasi targetMemanggil target AgentCore RuntimeOtorisasi keluarMenegakkan lalu lintas melalui gatewayPerbandingan kemampuan dengan target MCP

Target AgentCore Runtime Amazon Bedrock

Anda dapat menambahkan agen Amazon Bedrock AgentCore Runtime sebagai target gateway. Gateway mengirimkan lalu lintas langsung ke agen runtime tanpa agregasi atau terjemahan protokol. Tidak seperti target MCP yang menggabungkan kemampuan alat menjadi server MCP virtual terpadu, target AgentCore Runtime meneruskan permintaan dan tanggapan antara klien dan agen runtime tanpa modifikasi.

Menambahkan target AgentCore Runtime ke gateway Anda berguna saat Anda ingin:

  • Menyediakan manajemen akses terpusat untuk agen runtime Anda melalui titik akhir gateway tunggal.

  • Gunakan autentikasi dan observabilitas bawaan gateway untuk agen runtime Anda.

  • Rutekan permintaan ke agen runtime tertentu menggunakan perutean berbasis jalur saat beberapa target dilampirkan ke gateway.

  • Optimalkan kinerja agen Anda dengan menggunakan AgentCore optimasi Amazon Bedrock untuk menghasilkan rekomendasi dari jejak agen, A/B menguji perubahan dengan lalu lintas langsung melalui gateway, dan menerapkan konfigurasi pemenang. Untuk informasi selengkapnya, lihat AgentCore pengoptimalan.

Pertimbangan dan keterbatasan utama

Saat bekerja dengan target AgentCore Runtime, perhatikan pertimbangan berikut:

  • Gateway mengirimkan lalu lintas langsung ke target AgentCore Runtime tanpa menggabungkan kemampuan.

  • AgentCore Target runtime dapat ditambahkan ke gateway yang tidak memiliki jenis protokol yang ditetapkan. Mereka tidak dapat ditambahkan ke gateway tipe protokol MCP.

  • Tidak ada sinkronisasi kemampuan atau pencarian alat semantik yang tersedia untuk AgentCore target Runtime. Klien harus menangani setiap target secara individual melalui routing berbasis jalur.

  • Server-Sent Streaming Acara (SSE) didukung untuk target AgentCore Runtime.

  • Fungsi Lambda pencegat permintaan dan respons didukung dalam mode buffer. Pencegat belum didukung dalam mode streaming.

Konfigurasi target

Saat membuat target AgentCore Runtime, Anda menyediakan ARN runtime dan qualifier opsional. Gateway menyelesaikan titik akhir runtime secara internal, jadi Anda tidak perlu membuat URL runtime sendiri.

Konfigurasi target untuk target AgentCore Runtime menggunakan struktur berikut:

{
    "http": {
        "agentcoreRuntime": {
            "arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "qualifier": "DEFAULT",
            "schema": {
                "source": {
                    "s3": {
                        "uri": "s3://DOC-EXAMPLE-BUCKET/agent-schema.yaml"
                    }
                }
            }
        }
    }
}

  • arn (wajib) - ARN dari agen Amazon AgentCore Bedrock Runtime.

  • qualifier (opsional) - Kualifikasi runtime. Default ke DEFAULT.

  • skema (opsional) - Skema API yang menjelaskan permintaan dan struktur respons target runtime. Gateway menggunakan skema ini untuk mengaktifkan fitur mesin kebijakan seperti pagar pembatas. Format skema dideteksi secara otomatis sebagai OpenAPI atau Smithy.

    Untuk agen runtime yang menggunakan protokol MCP atau A2A, skema default diterapkan secara otomatis dan Anda tidak perlu menyediakannya. Untuk agen runtime yang menggunakan protokol HTTP, Anda harus menyediakan skema untuk menggunakan pagar pembatas.

    schemaObjek berisi a source yang menentukan di mana konten skema berada:

    • s3 — URI S3 yang menunjuk ke file skema (misalnya,). s3://DOC-EXAMPLE-BUCKET/agent-schema.yaml

    • InlinePayLoad - Konten skema yang disediakan langsung sebagai string.

catatan

Jika agen runtime Anda menggunakan protokol HTTP dan Anda ingin menerapkan pagar pembatas melalui mesin kebijakan gateway, Anda harus menyediakan skema. Untuk agen runtime yang menggunakan protokol MCP atau A2A, skema default diterapkan secara otomatis.

Memanggil target AgentCore Runtime

Untuk memanggil target AgentCore Runtime melalui gateway, kirim permintaan POST ke URL pemanggilan target. Format URL-nya adalah:

https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/{targetName}/invocations

Ganti {gatewayId} dengan ID gateway Anda, {targetName} dengan AWS Wilayah, dan dengan nama target. {region}

Contoh berikut menggunakan curl untuk memanggil target AgentCore Runtime:

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/my-target/invocations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"input": {"prompt": "Hello"}}'

Anda juga dapat menggunakan Amazon Bedrock AgentCore SDK dengan penggantian URL endpoint:

aws bedrock-agentcore invoke-agent-runtime \
    --endpoint-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/my-target \
    --runtimeArn arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID

Otorisasi keluar

AgentCore Target runtime mendukung jenis otorisasi keluar berikut:

  • IAM (SiGv4) — Gateway mengasumsikan peran layanan gateway untuk mendapatkan kredensil untuk menandatangani permintaan ke target runtime. Saat mengonfigurasi otorisasi IAM, Anda dapat menggunakan kebijakan IAM untuk membatasi akses secara eksklusif ke peran gateway, memastikan semua permintaan runtime mengalir melalui gateway.

  • Kredensial IAM pemanggil — Gateway menggunakan kredensil IAM pemanggil untuk menandatangani permintaan ke target runtime. Gateway mengasumsikan peran atas nama penelepon dan menandatangani permintaan keluar dengan identitas pemanggil.

  • OAuth (JWT) — Gateway mengambil token OAuth dari penyedia kredensi yang dikonfigurasi dalam target melalui layanan identitas Amazon Bedrock. AgentCore

  • Token passthrough — Gateway memvalidasi token masuk dan meneruskannya ke target runtime tanpa modifikasi. Ini berguna ketika runtime menangani otorisasi sendiri.

Menegakkan lalu lintas melalui gateway

Anda dapat mengedepankan AgentCore Runtime dengan AgentCore Gateway sehingga gateway menjadi titik masuk tunggal yang diatur ke runtime — memberi Anda otorisasi berbasis kebijakan, Amazon Bedrock Guardrails, pencegat permintaan dan respons, dan observabilitas terpadu, semuanya diterapkan di luar lingkungan agen sendiri. Untuk alasan lengkapnya, lihat Front runtime Anda dengan Gateway. AgentCore Tetapi ini hanya berguna jika Anda tidak dapat melewati gateway dan mengakses runtime secara langsung. Anda sekarang dapat mencapai ini terlepas dari apakah runtime menggunakan otorisasi masuk IAM (SigV4) atau OAuth (JWT).

Anda mengonfigurasi batasan ini pada runtime. Gateway mencap sumber dari setiap permintaan yang diteruskannya, dan runtime memvalidasi sumber tersebut saat masuk. Mekanisme spesifik tergantung pada jenis otorisasi masuk runtime:

  • Runtime IAM (SiGv4) — Lampirkan kebijakan berbasis sumber daya yang membatasi pemanggilan ke peran eksekusi gateway Anda. Untuk kebijakan dan pengerasan kebijakan kepercayaan yang diperlukan, lihat Membatasi permintaan masuk IAM (SigV4) ke gateway Anda.

  • Runtime OAuth (JWT) — Konfigurasikan allowedWorkloadConfiguration pada runtime customJWTAuthorizer untuk mengizinkan hanya beban kerja gateway Anda. Untuk konfigurasi dan referensi bidang, lihat Membatasi pemanggilan ke gateway Anda.

Perbandingan kemampuan dengan target MCP

Anda dapat mengintegrasikan server MCP dengan AgentCore gateway Amazon Bedrock menggunakan dua pendekatan: menggunakan tipe target MCP dalam mode agregasi, atau menggunakan tipe target AgentCore Runtime. Tabel berikut membandingkan kemampuan setiap pendekatan.

Kemampuan Gerbang MCP dengan target MCP AgentCore Target runtime

Tool/capability agregasi

Mengagregat kemampuan dari semua target MCP ke dalam satu server MCP virtual terpadu. Klien melihat satu tools/list respons terkonsolidasi.

Beroperasi dalam isolasi. Gateway mengirimkan lalu lintas langsung ke target tanpa menggabungkan kemampuan. Klien harus menangani setiap target secara individual melalui routing berbasis jalur.

Pencarian alat semantik

Mengindeks deskripsi alat dan memungkinkan penemuan melalui kueri bahasa alami.

Tidak tersedia. Gateway tidak menelan atau mengindeks kemampuan. Klien harus tahu nama alat yang tepat atau menggunakan server itu sendiritools/list.

Pencegat respons Lambda

Mendukung pencegat permintaan dan respons untuk operasi MCP non-streaming.

Mendukung fungsi Lambda pencegat permintaan dan respons dalam mode buffer. Pencegat belum didukung dalam mode streaming.