Hook del ciclo di vita

Gli hook del ciclo di vita inviano un evento a una funzione AWS Lambda, a un argomento Amazon SNS o a un bus di EventBridge eventi Amazon in un punto definito del ciclo dell'agente harness. Usa gli hook per convalidare una chiamata o una chiamata allo strumento, registrare l'attività in un altro sistema o avviare un flusso di lavoro asincrono.

È possibile configurare i ganci su un cablaggio con o. CreateHarness UpdateHarness La configurazione dei ganci non è disponibile come alternativaInvokeHarness. Un'imbracatura supporta fino a 20 ganci e il nome di ogni gancio deve essere univoco all'interno dell'imbracatura.

Scegli un evento del ciclo di vita

Il tipo di evento determina quando viene eseguito l'hook, il contesto inviato alla destinazione e l'effetto di una decisione Lambdadeny.

Usa gli hook tool-call con funzioni in linea

Tool-call i ganci funzionano anche per gli strumenti. inline_function Il cablaggio viene richiamato before_tool_call dopo che il modello ha generato la richiesta dell'utensile e prima che il cablaggio invii la chiamata in sospeso per l'esecuzione sul lato client. Consuma il flusso di risposta completo, quindi elabora la chiamata in linea solo se l'ultimo evento è impostato su. messageStop stopReason tool_use La richiesta generata dal modello può comparire negli eventi di stream precedenti alla decisione sull'hook; before_tool_call controlla l'esecuzione, non la visibilità nel flusso.

Restituisce la corrispondenza toolResult in una InvokeHarness richiesta successiva che utilizza la stessa. runtimeSessionId L'harness riprende la chiamata in sospeso, la richiama after_tool_call con il risultato fornito dal client e continua il ciclo dell'agente se l'hook consente il risultato. Per il flusso di callback completo, vedete Inline function calls.

Gli strumenti in una risposta del modello mantengono l'ordine di esecuzione sequenziale. Per lo strumento A eseguito tramite cablaggio, la funzione in linea B e lo strumento C eseguito tramite cablaggio, l'harness esegue A prima di consegnare B e attende il risultato di B prima di eseguire C. La richiesta di follow-up è una nuova chiamata, quindi gli hook di invocazione vengono eseguiti nuovamente, poiché la funzione inline in sospeso non viene ripetuta e viene eseguita una sola volta con il risultato inviato. before_tool_call after_tool_call

Puoi inviare il risultato in sospeso e tutti i risultati in linea immediatamente successivi in un'unica richiesta di follow-up. L'imbracatura elabora i ganci e i ganci in sequenzabefore_tool_call. after_tool_call Se il cliente richiede una allow decisione prima di ogni azione esterna, restituisci un risultato in linea per passaggio. Una richiesta successiva può apparire nello stream prima che venga eseguito l'hook.

Se before_tool_call nega B, l'harness salta B e continua con C senza consegnare B al client. Se after_tool_call nega B dopo che il client ha restituito il risultato, l'harness mantiene il risultato di B e si ferma prima di C.

Scegli un obiettivo

Gli hook supportano i seguenti tipi di bersagli.

Il cablaggio pianifica l'SNS e EventBridge la consegna senza attendere una risposta. Un errore di consegna non interrompe la chiamata. Per un argomento FIFO SNS, l'harness ricava l'ID del gruppo di messaggi dall'ARN del cablaggio e dall'ID della sessione. Ciò mantiene l'ordine di pubblicazione all'interno di quella sessione. Argomenti SNS standard e EventBridge non garantiscono l'ordine degli eventi del ciclo di vita.

Concedi al ruolo di esecuzione dell'harness l'autorizzazione a chiamare ogni destinazione. Per un esempio di policy, vedi Lifecycle hook targets.

Configura gli hook

L'esempio seguente configura un hook decisionale Lambda prima di ogni chiamata, una notifica SNS dopo ogni chiamata allo strumento e EventBridge una notifica dopo ogni chiamata. hooks.jsonDefinisci gli hook in:

[
  {
    "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"
        }
      }
    }
  }
]

Quando si passa hooks aUpdateHarness, l'elenco fornito sostituisce la configurazione hook esistente. Passa una lista vuota per rimuovere tutti gli hook. Ometti hooks per mantenere la configurazione esistente.

Restituire una decisione Lambda

Un target Lambda riceve direttamente il payload dell'hook. Deve restituire un oggetto JSON con il decision valore o. allow deny Può anche restituire unreason. L'harness include questo motivo nell'evento del flusso di hookEvent risposta e lo limita a 1.024 caratteri.

Il seguente gestore nega un before_invocation evento quando il target non è in grado di valutare il contesto dell'hook completo. Sostituisci questa logica con le regole per la tua applicazione.

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

Per i target Lambda, il timeoutSeconds valore predefinito è 60 secondi e accetta valori da 1 a 900 secondi. failureModedetermina la decisione quando la funzione scade, restituisce un errore o restituisce una risposta non valida:

import boto3
from botocore.config import Config

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

Il troncamento del contesto non si attiva. failureMode La funzione Lambda riceve il contesto troncato e deve restituire una decisione.

Quando più hook Lambda utilizzano lo stesso tipo di evento, l'harness li richiama contemporaneamente. Qualsiasi deny decisione si applica al comportamento di negazione dell'evento. Se più di un hook nega l'evento, il motivo viene fornito dal primo hook di negazione nell'elenco configurato.

Elabora il payload dell'hook

Ogni destinazione riceve i seguenti campi comuni:

{
  "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."}]
      }
    ]
  }
}

I context campi dipendono dal tipo di evento.

Il before_invocation contesto non include i messaggi che l'harness ripristina dallo stato della sessione dopo l'esecuzione dell'hook. Una decisione di rifiuto after_tool_call Lambda non rimuove il risultato completo dello strumento.

Gestisci il troncamento del contesto

L'imbracatura limita ogni context oggetto hook a 64 KiB.

Infattibefore_invocation, il cablaggio mantiene la sequenza contigua più recente di messaggi completi che rientra nel limite. Il payload viene conservato e conservato come elenco. messageCount messages Inoltre si aggiunge "truncated": true al contesto. Se solo il messaggio più recente supera il limite, messages è un elenco vuoto.

Per altri tipi di eventi, l'harness sostituisce i campi di contesto più grandi finché il contesto non si adatta. Ogni campo sostituito utilizza il seguente modulo:

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

Controlla gli indicatori di troncamento prima di utilizzare un campo. Un target Lambda che richiede un contesto completo può tornare deny quando riceve un indicatore di troncamento. Un SNS o un EventBridge consumatore può registrare l'evento e ottenere dati aggiuntivi dal proprio sistema di registrazione.

Leggi gli eventi hook dal flusso di risposta

InvokeHarnessemette un hookEvent per ogni hook configurato che si attiva. Un evento Lambda include la decisione applicata e il motivo facoltativo:

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

Per SNS e EventBridge target, decision e reason sono assenti. hookEventConfermano che l'imbracatura ha programmato l'invio. Non conferma che l'obiettivo abbia ricevuto l'evento.

Continua a leggere fino alla chiusura dello stream dell'evento. Quando lo stream include un terminalemessageStop, qualsiasi hookEvent con type set to lo after_invocation segue. Alcuni percorsi di errore vengono emessi after_invocation senza unmessageStop.

Argomenti correlati