View a markdown version of this page

Gunakan alur kerja Step Functions Anda sebagai alat untuk agen AI - AWS Step Functions

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.

penting

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 dan Batu Dasar Amazon AgentCore harga. Untuk menghindari biaya yang sedang berlangsung, hapus sumber daya saat Anda selesai, seperti yang dijelaskan dalam Langkah 6: Bersihkan.

catatan

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:InvokeGateway izin 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)
  1. Buka AWS Step Functions konsol dan pilih Buat mesin negara.

  2. Pilih Kosong, dan kemudian memilih Pilih.

  3. 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 } } }
  4. Memilih Konfigurasi. Untuk Nama mesin negara, masukkan AgentHelloWorld. Simpan Mengetik sebagai Standar.

  5. Pilih Buat untuk membuat mesin negara.

  6. 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.

  7. 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)
  1. 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:region:123456789012:stateMachine:*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] }'
  2. 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" \ --region region

    Jawabannya 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
  1. Buka Konsol IAM dan pilih Peran, Buat peran.

  2. 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-*" } } } ] }
  3. Memilih Berikutnya, dan kemudian Berikutnya sekali lagi tanpa melampirkan kebijakan terkelola.

  4. Untuk Nama peran, masukkan AgentCoreGatewayToStepFunctions, dan kemudian memilih Buat peran.

  5. 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:region:123456789012:stateMachine:AgentHelloWorld" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "arn:aws:states:region:123456789012:execution:AgentHelloWorld:*" } ] }
  6. Beri nama kebijakan StepFunctionsConnectorAccess, dan kemudian memilih Buat kebijakan.

  7. Perhatikan peran ARN, seperti yang ditunjukkan pada contoh berikut.

    arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
catatan

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
  1. 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" \ --region region

    Jawabannya meliputi gatewayId dan gatewayUrl. Perhatikan keduanya.

  2. Tunggu hingga status gateway READY. Hal ini dapat menghabiskan waktu beberapa menit. Ganti GATEWAY_ID dengan gatewayId dari langkah sebelumnya.

    aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --region region
  3. Tambahkan target konektor. configurations daftar memilih operasi mana yang menjadi alat. StartExecution, ListExecutions, dan DescribeStateMachine disematkan ke mesin negara Anda. DescribeExecution, GetExecutionHistory, dan StopExecution mengambil ARN eksekusi dari agen. Ganti GATEWAY_ID dengan 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:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --region region
  4. Tunggu sampai status target READY. Hal ini dapat menghabiskan waktu beberapa menit. Ganti TARGET_ID dengan targetId dari create-gateway-target tanggapan.

    aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --region region

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
  1. Buat daftar alat yang dilihat agen.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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___StartExecution hanya mengiklankan input: yang disematkan stateMachineArn disembunyikan dari agen dan tidak dapat diganti.

  2. Mulai eksekusi.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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:region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",\"startDate\":1.7597E9}" } ] } }

    Perhatikan executionArn untuk langkah selanjutnya.

Langkah 5: Konfirmasikan hasilnya

Gunakan alat tingkat eksekusi untuk memeriksa apakah eksekusi berhasil dan membaca outputnya.

Untuk mengkonfirmasi hasil eksekusi
  1. Jelaskan eksekusi. Secara default, respons hanya berisi metadata. Untuk memasukkan input dan output, atur includedData kepada ALL_DATA. Ganti EXECUTION_ARN dengan executionArn dari langkah 4.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_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, status adalah SUCCEEDED dan output adalah "Hello from Step Functions". Jika eksekusi gagal, status adalah FAILED Dan jawabannya meliputi error dan cause bidang dari negara gagal.

  2. Baca riwayat acara untuk melihat setiap langkah yang dilakukan eksekusi.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }'
  3. Daftar eksekusi terbaru dari mesin status yang disematkan, secara opsional difilter berdasarkan status.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }'
  4. (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.

catatan

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
  1. Hapus target gateway, lalu gateway.

    aws bedrock-agentcore-control delete-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --region region aws bedrock-agentcore-control delete-gateway \ --gateway-identifier "GATEWAY_ID" --region region
  2. Di konsol Step Functions, hapus AgentHelloWorld mesin negara.

  3. Di konsol IAM, hapus AgentCoreGatewayToStepFunctions peran dan peran eksekusi mesin status (peran yang dibuat oleh Fungsi Langkah untuk Anda, atau AgentHelloWorldExecutionRole jika Anda menggunakan AWS CLI).