Richiama un agente Runtime AgentCore

L'InvokeAgentRuntimeoperazione consente di inviare richieste a specifici endpoint AgentCore di Runtime identificati dal relativo Amazon Resource Name (ARN) e ricevere risposte in streaming contenenti l'output dell'agente. L'API supporta la gestione delle sessioni tramite identificatori di sessione, consentendoti di mantenere il contesto della conversazione tra più interazioni. Puoi indirizzare gli endpoint degli agenti specifici utilizzando qualificatori opzionali.

Per chiamareInvokeAgentRuntime, sono necessarie le autorizzazioni. bedrock-agentcore:InvokeAgentRuntime Nella chiamata puoi anche passare un token bearer che l'agente può utilizzare per l'autenticazione dell'utente.

L'InvokeAgentRuntimeoperazione accetta il payload della richiesta come dati binari di dimensioni fino a 100 MB e restituisce una risposta in streaming che fornisce blocchi di dati in tempo reale mentre l'agente elabora la richiesta. Questo approccio di streaming consente di ricevere risultati parziali immediatamente anziché attendere la risposta completa, il che lo rende ideale per le applicazioni interattive.

Per eseguire comandi di shell (come l'esecuzione di test, le operazioni git o la configurazione dell'ambiente) nella stessa sessione, usa i comandi della shell Execute nell'operazione AgentCore Runtime sessions. Entrambe le operazioni funzionano sullo stesso runtime e sulla stessa sessione dell'agente.

Se prevedi di integrare il tuo agente con OAuth, non puoi utilizzare l' AWS SDK per chiamare. InvokeAgentRuntime Effettua invece una richiesta HTTPS a. InvokeAgentRuntime Per ulteriori informazioni, consulta Autenticazione e autorizzazione con autenticazione in entrata e autenticazione in uscita.

Richiama gli agenti di streaming

L'esempio seguente mostra come usare boto3 per richiamare il runtime di un agente:

import boto3
import json

# Initialize the Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)


# Process and print the response
if "text/event-stream" in response.get("contentType", ""):

    # Handle streaming response
    content = []
    for line in response["response"].iter_lines(chunk_size=10):
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                line = line[6:]
                print(line)
                content.append(line)
    print("\nComplete response:", "\n".join(content))

elif response.get("contentType") == "application/json":
    # Handle standard JSON response
    content = []
    for chunk in response.get("response", []):
        content.append(chunk.decode('utf-8'))
    print(json.loads(''.join(content)))

else:
    # Print raw response for other content types
    print(response)

Invoca agenti multimodali

È possibile utilizzare l'InvokeAgentRuntimeoperazione per inviare richieste multimodali che includono sia testo che immagini. L'esempio seguente mostra come richiamare un agente multimodale:

import boto3
import json
import base64

# Read and encode image
with open("image.jpg", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

# Prepare multi-modal payload
payload = json.dumps({
    "prompt": "Describe what you see in this image",
    "media": {
        "type": "image",
        "format": "jpeg",
        "data": image_data
 }
}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)

Gestione della sessione

L'InvokeAgentRuntimeoperazione supporta la gestione della sessione tramite il parametro. runtimeSessionId Fornendo lo stesso identificatore di sessione per più richieste, è possibile mantenere il contesto della conversazione, consentendo all'agente di fare riferimento alle interazioni precedenti.

Per iniziare una nuova conversazione, genera un identificatore di sessione univoco. Per continuare una conversazione esistente, utilizza lo stesso identificatore di sessione delle richieste precedenti. Questo approccio consente di creare applicazioni interattive che mantengono il contesto nel tempo.

Suggerimento

Per ottenere risultati ottimali, utilizzate un UUID o un altro identificatore univoco per gli ID di sessione per evitare collisioni tra utenti o conversazioni diversi.

Gestione degli errori

Durante l'utilizzo dell'InvokeAgentRuntimeoperazione, è possibile che si verifichino diversi errori. Ecco alcuni errori comuni e come gestirli:

ValidationException

Si verifica quando i parametri della richiesta non sono validi. Verifica che l'ARN, l'ID di sessione e il payload dell'agente siano formattati correttamente.

ResourceNotFoundException

Si verifica quando non è possibile trovare il runtime dell'agente specificato. Verifica che l'ARN dell'agente sia corretto e che l'agente esista nel tuo AWS account.

AccessDeniedException

Si verifica quando non si dispone delle autorizzazioni necessarie. Assicurati che la tua policy IAM includa l'bedrock-agentcore:InvokeAgentRuntimeautorizzazione.

ThrottlingException

Si verifica quando si superano i limiti di frequenza delle richieste. Implementa la logica esponenziale di backoff e riprova nell'applicazione.

Implementate una corretta gestione degli errori nell'applicazione per fornire una migliore esperienza utente e risolvere i problemi in modo efficace.

Best practice

Segui queste best practice quando utilizzi l'InvokeAgentRuntimeoperazione:

• Utilizza la gestione delle sessioni per mantenere il contesto della conversazione per una migliore esperienza utente.

• Elabora le risposte in streaming in modo incrementale per fornire feedback in tempo reale agli utenti.

• Implementa una corretta gestione degli errori e riprova la logica per un'applicazione affidabile.

• Considerate le limitazioni delle dimensioni del payload (100 MB) quando inviate richieste, in particolare per i contenuti multimodali.

• Utilizzate i qualificatori appropriati per individuare versioni o endpoint specifici degli agenti.

• Implementa meccanismi di autenticazione, se necessario, utilizzando token bearer.

• Utilizzali InvokeAgentRuntimeCommand per operazioni deterministiche (tests, git, build) invece di indirizzarle tramite il LLM dell'agente. Vedi Eseguire i comandi della shell nelle sessioni di Runtime. AgentCore