Pengait siklus hidup

Hook siklus hidup mengirim peristiwa ke fungsi AWS Lambda, topik Amazon SNS, atau bus EventBridge acara Amazon pada titik yang ditentukan dalam loop agen harness. Gunakan kait untuk memvalidasi pemanggilan atau panggilan alat, merekam aktivitas di sistem lain, atau memulai alur kerja asinkron.

Anda mengkonfigurasi kait pada harness dengan CreateHarness atau. UpdateHarness Konfigurasi hook tidak tersedia sebagai InvokeHarness override. Harness mendukung hingga 20 kait, dan setiap nama kait harus unik di dalam harness.

Pilih acara siklus hidup

Jenis peristiwa menentukan kapan hook berjalan, konteks yang dikirim ke target, dan efek dari keputusan Lambdadeny.

Gunakan kait panggilan alat dengan fungsi inline

Tool-call kait juga dijalankan untuk inline_function alat. Harness dipanggil before_tool_call setelah model menghasilkan permintaan alat dan sebelum harness menyerahkan pemanggilan tertunda untuk eksekusi sisi klien. Gunakan aliran respons lengkap, lalu proses panggilan sebaris hanya jika messageStop acara terakhir telah stopReason disetel ketool_use. Permintaan yang dihasilkan model dapat muncul di peristiwa streaming sebelumnya sebelum keputusan hook; before_tool_call mengontrol eksekusi, bukan visibilitas di aliran.

Kembalikan pencocokan toolResult dalam InvokeHarness permintaan selanjutnya yang menggunakan yang samaruntimeSessionId. Harness melanjutkan panggilan tertunda, memanggil after_tool_call dengan hasil yang disediakan klien, dan melanjutkan loop agen jika hook memungkinkan hasilnya. Untuk alur callback lengkap, lihat Pemanggilan fungsi sebaris.

Alat dalam satu respons model mempertahankan urutan eksekusi berurutan. Untuk alat yang dieksekusi harness A, fungsi inline B, dan alat yang dieksekusi harness C, harness mengeksekusi A sebelum menyerahkan B dan menunggu hasil B sebelum mengeksekusi C. Permintaan tindak lanjut adalah pemanggilan baru, jadi kait pemanggilan berjalan lagi; untuk fungsi inline yang tertunda tidak diulang, dan berjalan sekali dengan hasil yang dikirimkan. before_tool_call after_tool_call

Anda dapat mengirimkan hasil yang tertunda dan hasil inline yang segera mengikuti dalam satu permintaan tindak lanjut. Harness memproses dan after_tool_call mengaitnya before_tool_call secara berurutan. Jika klien Anda memerlukan allow keputusan sebelum setiap tindakan eksternal, kembalikan satu hasil inline per handoff. Permintaan selanjutnya dapat muncul di aliran sebelum kaitnya berjalan.

Jika before_tool_call menyangkal B, harness melompati B dan berlanjut dengan C tanpa menyerahkan B kepada klien. Jika after_tool_call menolak B setelah klien mengembalikan hasilnya, harness mempertahankan hasil B dan berhenti sebelum C.

Pilih target

Hooks mendukung jenis target berikut.

Harness menjadwalkan SNS dan EventBridge pengiriman tanpa menunggu tanggapan. Kesalahan pengiriman tidak menghentikan pemanggilan. Untuk topik SNS FIFO, harness memperoleh ID grup pesan dari ARN harness dan ID sesi. Ini mempertahankan urutan publikasi dalam sesi itu. Topik SNS standar dan EventBridge tidak menjamin urutan acara siklus hidup.

Berikan izin peran eksekusi harness untuk memanggil setiap target. Untuk kebijakan contoh, lihat Target hook siklus hidup.

Konfigurasikan kait

Contoh berikut mengonfigurasi hook keputusan Lambda sebelum setiap pemanggilan, pemberitahuan SNS setelah setiap panggilan alat, dan EventBridge pemberitahuan setelah setiap pemanggilan. Tentukan kait dihooks.json:

[
  {
    "beforeInvocation": {
      "name": "validate_request",
      "target": {
        "lambda": {
          "arn": "arn:aws:lambda:us-west-2:123456789012:function:validate-harness-request",
          "timeoutSeconds": 5,
          "failureMode": "deny"
        }
      }
    }
  },
  {
    "afterToolCall": {
      "name": "record_tool_result",
      "target": {
        "sns": {
          "arn": "arn:aws:sns:us-west-2:123456789012:harness-tool-events"
        }
      }
    }
  },
  {
    "afterInvocation": {
      "name": "record_invocation",
      "target": {
        "eventBridge": {
          "arn": "arn:aws:events:us-west-2:123456789012:event-bus/harness-events"
        }
      }
    }
  }
]

Saat Anda hooks UpdateHarness meneruskannya, daftar yang disediakan menggantikan konfigurasi hook yang ada. Lewati daftar kosong untuk menghapus semua kait. Abaikan hooks untuk mempertahankan konfigurasi yang ada.

Kembalikan keputusan Lambda

Target Lambda menerima muatan kait secara langsung. Ini harus mengembalikan objek JSON dengan decision nilai allow ataudeny. Itu juga dapat mengembalikan areason. Harness menyertakan alasan ini dalam acara aliran hookEvent respons dan membatasi hingga 1.024 karakter.

Handler berikut menyangkal before_invocation peristiwa ketika target tidak dapat mengevaluasi konteks hook lengkap. Ganti logika ini dengan aturan untuk aplikasi Anda.

def lambda_handler(event, _context):
    hook_context = event["context"]

    if event["event"] == "before_invocation" and hook_context.get("truncated"):
        return {
            "decision": "deny",
            "reason": "The request context exceeded the evaluation limit.",
        }

    return {"decision": "allow"}

Untuk target Lambda, timeoutSeconds defaultnya 60 detik dan menerima nilai dari 1 hingga 900 detik. failureModemenentukan keputusan saat fungsi habis, mengembalikan kesalahan, atau mengembalikan respons yang tidak valid:

import boto3
from botocore.config import Config

client = boto3.client(
    "bedrock-agentcore",
    config=Config(
        read_timeout=1000,
        tcp_keepalive=True,
    ),
)

Pemotongan konteks tidak diaktifkan. failureMode Fungsi Lambda menerima konteks terpotong dan harus mengembalikan keputusan.

Ketika beberapa kait Lambda menggunakan jenis peristiwa yang sama, harness memanggilnya secara bersamaan. denyKeputusan apa pun menerapkan perilaku penolakan acara. Jika lebih dari satu hook menyangkal peristiwa tersebut, hook penyangkalan pertama dalam daftar yang dikonfigurasi memberikan alasannya.

Memproses muatan kait

Setiap target menerima bidang umum berikut:

{
  "hookEventId": "1234abcd-12ab-34cd-56ef-1234567890ab",
  "name": "validate_request",
  "event": "before_invocation",
  "harnessArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-UuFdkQoXSL",
  "sessionId": "12345678-1234-5678-9abc-123456789012",
  "context": {
    "messageCount": 1,
    "messages": [
      {
        "role": "user",
        "content": [{"text": "Summarize this report."}]
      }
    ]
  }
}

contextBidang tergantung pada jenis acara.

before_invocationKonteksnya tidak menyertakan pesan yang dikembalikan harness dari status sesi setelah hook berjalan. Keputusan after_tool_call penolakan Lambda tidak menghapus hasil alat yang sudah selesai.

Tangani pemotongan konteks

Harness membatasi setiap context objek kait hingga 64 KiB.

Untukbefore_invocation, harness menyimpan urutan pesan lengkap terbaru yang bersebelahan yang sesuai dengan batas. Muatan disimpan messageCount dan disimpan messages sebagai daftar. Ini juga menambah "truncated": true konteksnya. Jika pesan terbaru saja melebihi batas, messages adalah daftar kosong.

Untuk jenis acara lainnya, harness menggantikan bidang konteks terbesar hingga konteksnya cocok. Setiap bidang diganti menggunakan formulir berikut:

{
  "truncated": true,
  "preview": "<prefix of the serialized field>"
}

Periksa penanda pemotongan sebelum menggunakan bidang. Target Lambda yang membutuhkan konteks lengkap dapat kembali deny saat menerima penanda pemotongan. SNS atau EventBridge konsumen dapat merekam acara dan mendapatkan data tambahan dari sistem catatannya sendiri.

Baca peristiwa hook dari aliran respons

InvokeHarnessmemancarkan a hookEvent untuk setiap kait yang dikonfigurasi yang menyala. Acara Lambda mencakup keputusan yang diterapkan dan alasan opsional:

{
  "hookEvent": {
    "hookEventId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "name": "validate_request",
    "type": "before_invocation",
    "decision": "allow",
    "reason": "Request accepted."
  }
}

Untuk SNS dan EventBridge target, decision dan tidak reason ada. Mereka hookEvent menegaskan bahwa harness menjadwalkan pengiriman. Itu tidak mengkonfirmasi bahwa target menerima acara tersebut.

Lanjutkan membaca sampai aliran acara ditutup. Ketika aliran menyertakan terminalmessageStop, apa pun hookEvent dengan type set untuk after_invocation mengikutinya. Beberapa jalur kesalahan dipancarkan after_invocation tanpa file. messageStop

Topik terkait