Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Gunakan AgentCore harness Amazon Bedrock dengan Step Functions
Anda dapat mengintegrasikan Step Functions dengan Amazon Bedrock AgentCore untuk memanggil harness dari mesin status Anda. Harness adalah runtime terkelola yang mengatur inferensi model, penggunaan alat, dan percakapan multi-putaran. Di Workflow Studio, cari **AgentCore InvokeHarness**untuk menemukan status ini dan seret ke alur kerja Anda.
Dari panel konfigurasi, Anda dapat membuat peran harness dan eksekusi baru menggunakan **Quick Create Harness**, atau memilih ARN harness yang ada. Saat Anda menggunakan harness yang ada, Anda dapat mengganti konfigurasi berdasarkan per-pemanggilan — nilai dalam definisi status Tugas Anda akan mengganti default harness. Untuk parameter yang tersedia, lihat [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)di *Referensi Amazon Bedrock AgentCore API*. Untuk informasi selengkapnya tentang peran eksekusi harness, lihat [Izin waktu proses di Panduan Pengembang](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) *Amazon Bedrock AgentCore *.
**Tip**
Untuk menambahkan observabilitas ke sumber daya agen Anda, aktifkan Penelusuran CloudWatch Transaksi. Untuk informasi selengkapnya, lihat [Menambahkan observabilitas ke sumber daya agen Anda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AgentCore-GettingStarted.html#add-observability-agentic-resources) di * CloudWatch Panduan Pengguna Amazon*.
Untuk mempelajari tentang mengintegrasikan dengan AWS layanan di Step Functions, lihat [Integrasi layanan ](integrate-services.md) dan[Meneruskan parameter ke API layanan di Step Functions](connect-parameters.md).
**Fitur utama integrasi AgentCore harness yang dioptimalkan**
Hanya pola [Minta Tanggapan](connect-to-resource.md#connect-default) integrasi yang didukung. [Tunggu Callback dengan Task Token](connect-to-resource.md#connect-wait-token)Pola [Jalankan Tugas (.sync)](connect-to-resource.md#connect-sync) dan tidak didukung.
Respons diubah menjadi struktur JSON berbentuk [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html#API_runtime_Converse_ResponseSyntax). Hanya pesan asisten terakhir yang dikembalikan; giliran sebelumnya dalam percakapan multi-putaran dibuang.
Metrik penggunaan token (`InputTokens`,`OutputTokens`,`TotalTokens`) digabungkan di semua pesan dalam percakapan.
Hanya konten teks yang disertakan dalam respons. Penggunaan alat dan blok penalaran dihilangkan dari. `Output.Message.Content`
Ukuran output tunduk pada batas output status Tugas. Untuk nilai saat ini, lihat[Kuota yang berkaitan dengan eksekusi tugas](service-quotas.md#service-limits-task-executions).
Status `InvokeHarness` Tugas memiliki waktu eksekusi maksimum 15 menit (900 detik), bahkan jika `TimeoutSeconds` nilainya melebihi batas itu. Setelah status Tugas habis, harness terus mengeksekusi hingga mencapai batas waktu yang dikonfigurasi sendiri. Untuk menghindari biaya tak terduga, pastikan batas waktu harness Anda tidak melebihi 15 menit.
Tampilan detail eksekusi konsol Step Functions menampilkan CloudWatch tautan di samping langkah agen, memberikan tampilan belokan demi belokan dari alasan agen termasuk penggunaan alat.
## API AgentCore harness Amazon Bedrock yang dioptimalkan
API berikut didukung:
### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)
Memanggil harness untuk menjalankan agen AI yang dapat menggunakan alat, mengakses memori, dan menjalankan percakapan multi-putaran.
**Pola yang didukung:** Minta Respons saja.
Untuk sintaks permintaan lengkap, lihat [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)di Referensi *Amazon Bedrock AgentCore API*.
**Parameter dalam Step Functions dinyatakan dalam PascalCase**
Bahkan jika API layanan asli ada di camelCase, misalnya `startSyncExecution` tindakan API, Anda menentukan parameter PascalCase, seperti:. `StateMachineArn`
**Bidang respons**
+ `Output.Message`— Pesan asisten terakhir agen. Berisi `Role` (selalu`"assistant"`) dan `Content` (array blok teks). Hanya giliran asisten terakhir yang dikembalikan; giliran sebelumnya dalam percakapan multi-putaran dibuang.
+ `Output.Message.Content`— Array blok konten. Setiap blok berisi `Text` bidang dengan teks respons agen. Hanya konten teks yang disertakan; penggunaan alat dan blok penalaran dihilangkan.
+ `StopReason`Mengapa agen berhenti. Nilai:`end_turn`,`max_tokens`,`stop_sequence`,`tool_use`.
+ `Usage`— Metrik konsumsi token digabungkan di semua belokan. Berisi`InputTokens`,`OutputTokens`, dan`TotalTokens`.
+ `Metrics.LatencyMs`— Total latensi pemanggilan dalam milidetik, digabungkan di semua belokan.
**Sintaks respons**
```
{
"Output": {
"Message": {
"Role": "{{string}}",
"Content": [
{
"Text": "{{string}}"
}
]
}
},
"StopReason": "{{string}}",
"Usage": {
"InputTokens": {{long}},
"OutputTokens": {{long}},
"TotalTokens": {{long}}
},
"Metrics": {
"LatencyMs": {{long}}
}
}
```
**catatan**
Menghentikan eksekusi atau status Tugas tidak menghentikan harness untuk terus berjalan.
## Definisi status tugas untuk integrasi Amazon Bedrock AgentCore
Contoh berikut menunjukkan cara menentukan status Tugas yang memanggil harness Amazon Bedrock AgentCore .
`RuntimeSessionId`Bidang mengidentifikasi sesi percakapan. Gunakan ID sesi yang sama di seluruh pemanggilan untuk melanjutkan percakapan.
**catatan**
URI resource Step Functions menggunakan `bedrockagentcore` (tanpa tanda hubung), sedangkan ARN AgentCore resource Amazon Bedrock menggunakan `bedrock-agentcore` (dengan tanda hubung).
**Example pemanggilan dasar dengan penggantian model dan prompt sistem**
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-agent-harness}}",
"RuntimeSessionId": "{% $uuid() %}",
"Messages": [
{
"Content": [{ "Text": "{% $states.input.userMessage %}" }],
"Role": "user"
}
],
"SystemPrompt": [{ "Text": "You are a helpful customer service agent." }],
"Model": {
"BedrockModelConfig": {
"Temperature": 0.7,
"ModelId": "global.anthropic.claude-sonnet-4-6"
}
},
"MaxIterations": 75,
"TimeoutSeconds": 600
},
"End": true
}
```
**Example pemanggilan dengan alat (browser)**
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{order-agent}}",
"RuntimeSessionId": "{% $uuid() %}",
"Messages": [
{
"Content": [{ "Text": "What is the status of order #12345?" }],
"Role": "user"
}
],
"Tools": [
{
"Type": "agentcore_browser",
"Name": "aws_browser_v1",
"Config": {
"AgentCoreBrowser": {
"BrowserArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:aws:browser/aws.browser.v1"
}
}
}
],
"MaxIterations": 10,
"TimeoutSeconds": 300
},
"End": true
}
```
**Tip**
Anda dapat menguji status ini satu per satu menggunakan [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API sebelum menjalankan eksekusi penuh.
## Penanganan kesalahan
`InvokeHarness`API dapat gagal dengan berbagai kesalahan, termasuk pembatasan, validasi, dan kesalahan akses ditolak. Untuk daftar lengkapnya, lihat [InvokeHarnesserror](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html#API_InvokeHarness_Errors) di *Referensi Amazon Bedrock AgentCore API*.
Contoh berikut menunjukkan status Tugas dengan `Retry` dan `Catch` bidang untuk penanganan kesalahan:
```
{
"Type": "Task",
"Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
"Arguments": {
"HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-harness}}",
"Messages": [
{
"Content": [{ "Text": "{% $states.input.userMessage %}" }],
"Role": "user"
}
]
},
"Retry": [
{
"ErrorEquals": ["BedrockAgentCore.ThrottlingException"],
"IntervalSeconds": 2,
"MaxAttempts": 3,
"BackoffRate": 2.0
}
],
"Catch": [
{
"ErrorEquals": ["BedrockAgentCore.ResourceNotFoundException"],
"Next": "HandleNotFound"
},
{
"ErrorEquals": ["States.ALL"],
"Next": "HandleError"
}
],
"End": true
}
```
## Kebijakan IAM untuk memanggil Amazon Bedrock AgentCore
Contoh templat berikut menunjukkan cara AWS Step Functions menghasilkan kebijakan IAM berdasarkan sumber daya dalam definisi mesin status Anda. Untuk informasi selengkapnya, lihat [Bagaimana Step Functions menghasilkan kebijakan IAM untuk layanan terintegrasi](service-integration-iam-templates.md) dan [Temukan pola integrasi layanan di Step Functions](connect-to-resource.md).
### Contoh kebijakan IAM untuk integrasi Amazon Bedrock AgentCore
Contoh berikut menunjukkan cara membuat kebijakan IAM untuk peran eksekusi Step Functions agar berinteraksi dengan resource Amazon Bedrock AgentCore.
Dalam contoh kebijakan berikut, ganti nilai placeholder dengan nilai Anda sendiri.
+ [Kebijakan IAM untuk menggunakan harness tertentu](#bedrockagentcore-policy-invoke-specific-harness)
+ [Kebijakan IAM untuk memanggil semua harness di akun](#bedrockagentcore-policy-invoke-all-harnesses)
#### Kebijakan IAM untuk menggunakan harness tertentu
Kebijakan contoh berikut memungkinkan penggunaan AgentCore harness Amazon Bedrock tertentu oleh ARN.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeSpecificHarness",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:InvokeAgentRuntime"
],
"Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/{{harnessName}}"
}
]
}
```
#### Kebijakan IAM untuk memanggil semua harness di akun
Kebijakan contoh berikut memungkinkan penggunaan AgentCore harness Amazon Bedrock apa pun di akun Anda. Kami merekomendasikan pelingkupan ke ARN harness tertentu jika memungkinkan.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeAllHarnesses",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:InvokeAgentRuntime"
],
"Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/*"
}
]
}
```
**catatan**
Jika harness Anda menggunakan alat seperti gateway, browser, atau interpreter kode, izin tersebut dikonfigurasi pada peran eksekusi *harness, bukan peran eksekusi* Step Functions. Untuk informasi selengkapnya, lihat [Memanfaatkan izin peran eksekusi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html) di Panduan Pengguna *Amazon Bedrock AgentCore *.