API yang didukung Definisi status tugas Penanganan kesalahan Kebijakan IAM

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 InvokeHarnessuntuk 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 InvokeHarnessdi Referensi Amazon Bedrock AgentCore API. Untuk informasi selengkapnya tentang peran eksekusi harness, lihat Izin waktu proses di Panduan Pengembang 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 di CloudWatch Panduan Pengguna Amazon.

Untuk mempelajari tentang mengintegrasikan dengan AWS layanan di Step Functions, lihat Integrasi layanan danMeneruskan parameter ke API layanan di Step Functions.

Fitur utama integrasi AgentCore harness yang dioptimalkan

Hanya pola Minta Tanggapan integrasi yang didukung. Tunggu Callback dengan Task TokenPola Jalankan Tugas (.sync) dan tidak didukung.
Respons diubah menjadi struktur JSON berbentuk Converse. 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, lihatKuota yang berkaitan dengan eksekusi tugas.
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

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 InvokeHarnessdi 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.
StopReasonMengapa agen berhenti. Nilai:end_turn,max_tokens,stop_sequence,tool_use.
Usage— Metrik konsumsi token digabungkan di semua belokan. BerisiInputTokens,OutputTokens, danTotalTokens.
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 .

RuntimeSessionIdBidang 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).

contoh 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
}

contoh 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 TestStateAPI sebelum menjalankan eksekusi penuh.

Penanganan kesalahan

InvokeHarnessAPI dapat gagal dengan berbagai kesalahan, termasuk pembatasan, validasi, dan kesalahan akses ditolak. Untuk daftar lengkapnya, lihat InvokeHarnesserror 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 dan Temukan pola integrasi layanan di Step Functions.

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
Kebijakan IAM untuk memanggil semua harness di akun

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 di Panduan Pengguna Amazon Bedrock AgentCore .

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Amazon Bedrock

AWS CodeBuild