Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Gunakan alur kerja Step Functions Anda sebagai alat untuk agen AI
Anda dapat membiarkan agen AI menjalankan alur kerja Step Functions Anda dengan mengekspos mesin status sebagai alat Model Context Protocol (MCP) melalui Amazon Bedrock AgentCore Gerbang. Agen yang terhubung ke gateway dapat memulai eksekusi, memeriksa status dan output mereka, membaca riwayat peristiwa, dan menghentikan eksekusi. Anda tidak perlu menulis fungsi Lambda atau mendefinisikan alat sendiri. Gateway membuat skema alat dan memanggil Fungsi Langkah untuk agen.
Pola ini berguna ketika tugas harus menjalankan langkah yang sama dalam urutan yang sama setiap saat. Agen memutuskan kapan menjalankan alur kerja dan masukan apa yang harus diteruskan. Mesin status memutuskan langkah mana yang dijalankan, sehingga agen tidak dapat melewati atau menyusunnya ulang, dan riwayat eksekusi mencatat setiap langkah alur kerja.
Anda mengontrol apa yang dapat dilakukan agen dengan dua cara. Alat yang memulai atau mencantumkan eksekusi disematkan ke mesin status yang Anda pilih, dan agen tidak dapat mengubahnya. Alat yang bertindak pada eksekusi tertentu mengambil eksekusi Nama Sumber Daya Amazon (ARN) dari agen. The AWS Identity and Access Management kebijakan pada peran layanan gateway membatasi eksekusi mana yang dapat diakses alat tersebut. Tutorial ini mencakup kebijakan itu ke mesin status tunggal.
Dalam tutorial ini, Anda membuat mesin status Standar sederhana dan gateway dengan target konektor Fungsi Langkah yang menunjuk ke sana. Anda kemudian membuat panggilan MCP yang sama dengan yang dilakukan agen, menggunakan awscurl, sehingga Anda dapat melihat setiap permintaan dan tanggapan. Jika Anda sudah memiliki mesin status Standar, Anda dapat melompat ke Langkah 2: Buat peran layanan untuk gateway dan menggunakan ARN-nya sebagai pengganti AgentHelloWorld. Tutorial ini menggunakan alur kerja Standar karena ListExecutions, DescribeExecution, dan GetExecutionHistory jangan bekerja dengan eksekusi Ekspres. Sumber daya yang Anda buat dapat dikenakan biaya hingga Anda menghapusnya di Langkah 6: Bersihkan.
Sumber daya dalam tutorial ini dapat dikenakan biaya untuk transisi status Fungsi Langkah dan Amazon Bedrock AgentCore Panggilan alat gateway. Untuk tarif, lihat Penetapan harga Step Functions
Konektor Step Functions memperlihatkan sepuluh operasi. Tutorial ini mengonfigurasi enam di antaranya: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, dan StopExecution. Untuk daftar lengkapnya, termasuk operasi token tugas dan perbedaan antara alur kerja Standar dan Ekspres, lihat AWS Langkah Berfungsi sebagai Target Konektor di Batu Dasar Amazon AgentCore Panduan Pengembang.
Prasyarat
Sebelum Anda mulai, pastikan Anda memiliki yang berikut:
-
AWS CLI versi 2, dikonfigurasi dengan kredenSIAL untuk akun Anda. Langkah 3 hingga 6 menggunakan AWS CLI.
-
Klien yang dapat mengirim permintaan HTTP bertanda tangan Versi 4 yang ditandatangani ke gateway. Tutorial ini menggunakan awscurl
, yang dapat Anda instal dengan pip install awscurl. Setiap klien MCP yang mendukung Signature Version 4 bekerja dengan cara yang sama. -
Izin untuk membuat peran IAM, mesin status Fungsi Langkah, dan AgentCore gateway di akun Anda, dan
bedrock-agentcore:InvokeGatewayizin pada gateway yang Anda buat di Langkah 3 untuk identitas yang memanggilnya di Langkah 4 dan 5.
Buat setiap sumber daya dalam tutorial ini dengan cara yang sama Wilayah AWS. Gateway memanggil Fungsi Langkah di Wilayahnya sendiri, sehingga mesin status di Wilayah yang berbeda tidak dapat dijangkau melalui konektor.
Langkah 1: Buat mesin status
Buat mesin status standar untuk dijalankan oleh agen. Definisi berikut memiliki satu Pass keadaan yang mengembalikan hasil tetap. Pastikan konsol diatur ke Wilayah tempat Anda akan membuat gateway di Langkah 3.
Untuk membuat mesin status (konsol)
-
Buka AWS Step Functions konsol
dan pilih Buat mesin negara. -
Pilih Kosong, dan kemudian memilih Pilih.
-
Pilih Kode dan ganti definisi dengan yang berikut ini.
{ "Comment": "A workflow that an AI agent starts through AgentCore Gateway", "StartAt": "Hello", "States": { "Hello": { "Type": "Pass", "Result": "Hello from Step Functions", "End": true } } } -
Memilih Konfigurasi. Untuk Nama mesin negara, masukkan
AgentHelloWorld. Simpan Mengetik sebagai Standar. -
Pilih Buat untuk membuat mesin negara.
-
Izinkan Fungsi Langkah untuk membuat peran eksekusi saat diminta. Jika Anda menggunakan AWS CLI sebagai gantinya, buat peran sendiri, seperti yang ditunjukkan dalam prosedur berikut.
-
Pada halaman detail mesin status, perhatikan ARN, seperti yang ditunjukkan pada contoh berikut.
arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld
Untuk membuat mesin status yang sama dengan AWS CLI sebagai gantinya, gunakan prosedur berikut. Berbeda dengan konsol, AWS CLI tidak membuat peran eksekusi untuk Anda, jadi buat satu terlebih dahulu. Ini Pass-only alur kerja tidak memanggil layanan lain, jadi peran tidak memerlukan kebijakan izin.
Untuk membuat mesin negara (AWS CLI)
-
Buat peran eksekusi yang dapat diasumsikan oleh Fungsi Langkah. Ganti Wilayah dan ID akun dengan milik Anda sendiri.
aws iam create-role \ --role-name AgentHelloWorldExecutionRole \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:states:" }, "StringEquals": { "aws:SourceAccount": "region:123456789012:stateMachine:*123456789012" } } } ] }' -
Simpan definisi yang ditampilkan dalam prosedur konsol ke file bernama
definition.json, dan kemudian membuat mesin negara.aws stepfunctions create-state-machine \ --name AgentHelloWorld \ --type STANDARD \ --definition file://definition.json \ --role-arn "arn:aws:iam::123456789012:role/AgentHelloWorldExecutionRole" \ --regionregionJawabannya berisi
stateMachineArn. Catat untuk Langkah 2 dan 3.
Langkah 2: Buat peran layanan untuk gateway
Gateway memanggil Fungsi Langkah dengan peran layanan. Lingkup peran ke mesin status yang Anda buat sehingga agen tidak dapat bertindak pada alur kerja lain di akun Anda.
Untuk membuat peran layanan gateway
-
Buka Konsol IAM
dan pilih Peran, Buat peran. -
Untuk Jenis entitas tepercaya, pilih Kebijakan kepercayaan kustom, dan masukkan yang berikut ini. Ganti Wilayah dan ID akun dengan milik Anda sendiri.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:" } } } ] }region:123456789012:gateway/step-functions-gateway-* -
Memilih Berikutnya, dan kemudian Berikutnya sekali lagi tanpa melampirkan kebijakan terkelola.
-
Untuk Nama peran, masukkan
AgentCoreGatewayToStepFunctions, dan kemudian memilih Buat peran. -
Buka peran, pilih Tambahkan izin, Buat kebijakan sebaris, pilih JSON, dan masukkan kebijakan berikut. Ganti Wilayah dan ID akun dengan milik Anda sendiri.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "StateMachineOperations", "Effect": "Allow", "Action": [ "states:StartExecution", "states:ListExecutions", "states:DescribeStateMachine" ], "Resource": "arn:aws:states:" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } ] }region:123456789012:execution:AgentHelloWorld:* -
Beri nama kebijakan
StepFunctionsConnectorAccess, dan kemudian memilih Buat kebijakan. -
Perhatikan peran ARN, seperti yang ditunjukkan pada contoh berikut.
arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
ARN eksekusi adalah jenis sumber daya yang berbeda dari ARN mesin status, itulah sebabnya kebijakan memiliki dua pernyataan.
Jika nanti Anda mengekspos operasi token tugas (SendTaskSuccess, SendTaskFailure, dan SendTaskHeartbeat), Anda harus memberikannya "*", karena IAM tidak mendukung izin tingkat sumber daya untuk tindakan ini. Token tugas kemudian menjadi satu-satunya kontrol tugas yang dapat diselesaikan agen, jadi perlakukan token tugas sebagai rahasia dan kirim masing-masing hanya ke agen yang harus menindaklanjutinya.
Semua target pada gateway berbagi peran layanannya. Jika alur kerja yang berbeda memerlukan batas IAM yang berbeda, gunakan gateway terpisah untuk masing-masing.
Langkah 3: Buat gateway dan tambahkan target konektor Fungsi Langkah
Buat gateway yang menerima permintaan yang ditandatangani AWS kredenSIAL, lalu tambahkan target yang menggunakan states konektor dan menyematkannya ke mesin negara Anda.
Untuk membuat gateway dan target
-
Buat gateway dengan AWS CLI. Ganti peran ARN dengan yang dari Langkah 2.
aws bedrock-agentcore-control create-gateway \ --name "step-functions-gateway" \ --protocol-type MCP \ --authorizer-type AWS_IAM \ --role-arn "arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions" \ --regionregionJawabannya meliputi
gatewayIddangatewayUrl. Perhatikan keduanya. -
Tunggu hingga status gateway
READY. Hal ini dapat menghabiskan waktu beberapa menit. GantiGATEWAY_IDdengangatewayIddari langkah sebelumnya.aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --regionregion -
Tambahkan target konektor.
configurationsdaftar memilih operasi mana yang menjadi alat.StartExecution,ListExecutions, danDescribeStateMachinedisematkan ke mesin negara Anda.DescribeExecution,GetExecutionHistory, danStopExecutionmengambil ARN eksekusi dari agen. GantiGATEWAY_IDdengan ID gateway Anda.aws bedrock-agentcore-control create-gateway-target \ --gateway-identifier "GATEWAY_ID" \ --name "hello" \ --target-configuration '{ "mcp": { "connector": { "source": { "connectorId": "states" }, "configurations": [ { "name": "StartExecution", "parameterValues": { "stateMachineArn": "arn:aws:states:" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --regionregion:123456789012:stateMachine:AgentHelloWorldregion -
Tunggu sampai status target
READY. Hal ini dapat menghabiskan waktu beberapa menit. GantiTARGET_IDdengantargetIddaricreate-gateway-targettanggapan.aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --regionregion
Gateway sekarang mengekspos enam alat MCP: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, dan hello___StopExecution. Gateway mengawali setiap nama alat dengan nama target.
Langkah 4: Mulai eksekusi melalui gateway
Klien MCP memanggil gateway dengan JSON-RPC permintaan. Karena gateway menggunakan AWS_IAM otorisasi, permintaan harus ditandatangani dengan Tanda Tangan Versi 4. Contoh-contoh berikut menggunakan awscurl, yang menandatangani permintaan dengan Anda AWS CLI kredenSIAL. Lihat Prasyarat. Dalam setiap perintah, ganti GATEWAY_URL dengan gatewayUrl dari langkah 3.
Untuk memulai eksekusi
-
Buat daftar alat yang dilihat agen.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Tanggapan mencantumkan enam alat dengan skema input mereka. Perhatikan bahwa
hello___StartExecutionhanya mengiklankaninput: yang disematkanstateMachineArndisembunyikan dari agen dan tidak dapat diganti. -
Mulai eksekusi.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "hello___StartExecution", "arguments": { "input": "{\"who\": \"agent\"}" } } }'Hasil alat berisi respons Fungsi Langkah dengan ARN eksekusi baru.
{ "jsonrpc": "2.0", "id": 2, "result": { "isError": false, "content": [ { "type": "text", "text": "{\"executionArn\":\"arn:aws:states:\",\"startDate\":1.7597E9}" } ] } }region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111Perhatikan
executionArnuntuk langkah selanjutnya.
Langkah 5: Konfirmasikan hasilnya
Gunakan alat tingkat eksekusi untuk memeriksa apakah eksekusi berhasil dan membaca outputnya.
Untuk mengkonfirmasi hasil eksekusi
-
Jelaskan eksekusi. Secara default, respons hanya berisi metadata. Untuk memasukkan input dan output, atur
includedDatakepadaALL_DATA. GantiEXECUTION_ARNdenganexecutionArndari langkah 4.awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "hello___DescribeExecution", "arguments": { "executionArn": "EXECUTION_ARN", "includedData": "ALL_DATA" } } }'Untuk mesin negara ini,
statusadalahSUCCEEDEDdanoutputadalah"Hello from Step Functions". Jika eksekusi gagal,statusadalahFAILEDDan jawabannya meliputierrordancausebidang dari negara gagal. -
Baca riwayat acara untuk melihat setiap langkah yang dilakukan eksekusi.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }' -
Daftar eksekusi terbaru dari mesin status yang disematkan, secara opsional difilter berdasarkan status.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }' -
(Opsional) Konfirmasikan eksekusi di AWS Step Functions konsol
. Pilih AgentHelloWorld, dan kemudian pilih eksekusi. Eksekusi yang dimulai oleh gateway muncul seperti eksekusi lainnya, dengan peran layanan gateway sebagai pemanggil AWS CloudTrail.
Untuk menghentikan eksekusi yang sedang berjalan, panggil hello___StopExecution dengan eksekusi ARN. Memanggilnya pada eksekusi yang telah selesai berhasil tetapi tidak berpengaruh. Respons mengembalikan waktu berhenti eksekusi asli. Untuk alur kerja yang berjalan lama, agen biasanya menelepon StartExecution, dan kemudian jajak pendapat DescribeExecution sampai status tidak lagi RUNNING.
Langkah 6: Bersihkan
Untuk menghindari biaya yang sedang berlangsung, hapus sumber daya yang Anda buat.
Untuk membersihkan
-
Hapus target gateway, lalu gateway.
aws bedrock-agentcore-control delete-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --regionaws bedrock-agentcore-control delete-gateway \ --gateway-identifier "regionGATEWAY_ID" --regionregion -
Di konsol Step Functions, hapus
AgentHelloWorldmesin negara. -
Di konsol IAM, hapus
AgentCoreGatewayToStepFunctionsperan dan peran eksekusi mesin status (peran yang dibuat oleh Fungsi Langkah untuk Anda, atauAgentHelloWorldExecutionRolejika Anda menggunakan AWS CLI).
Sumber daya terkait
-
AWS Langkah Berfungsi sebagai Target Konektor di Batu Dasar Amazon AgentCore Panduan Pengembang — semua sepuluh operasi, parameter mana yang dapat disematkan, batasan alur kerja Standar dan Ekspres, dan skema alat.
-
Tambahkan target Konektor dengan AWS Fungsi Langkah — pengaturan dengan Boto3, AWS CLI, dan AgentCore CLI, dan kebijakan peran layanan penuh termasuk operasi token tugas.
-
Buat agen yang menggunakan AgentCore gerbang — menghubungkan kerangka kerja agen seperti Strands Agents atau LangGraph ke pintu gerbang.
-
Gunakan AgentCore harness Amazon Bedrock dengan Step Functions — arah sebaliknya: panggil agen dari status Tugas Fungsi Langkah.