Aggiunta di un gruppo di operazioni all’agente in Amazon Bedrock

Dopo aver impostato lo schema OpenAPI e la funzione Lambda per il gruppo di operazioni, è possibile creare il gruppo di operazioni. Scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:

Nota

Se stai utilizzando Anthropic Claude 3.5 Sonnet, assicurati che il nome dello strumento visualizzato nel modulo httpVerb__actionGroupName__apiName segua il formato del nome dello strumento Anthropic ^[a-zA-Z0-9_-]{1,64}$. actionGroupName e apiName non devono contenere trattini bassi doppi '__'.

Console

Quando crei un agente, puoi aggiungere gruppi di azioni alla bozza di lavoro.

Una volta creato un agente, è possibile aggiungervi gruppi di operazioni attenendosi alle seguenti fasi:

Per aggiungere un gruppo di operazioni a un agente

Accedi alla Console di gestione AWS con un’identità IAM che disponga delle autorizzazioni per utilizzare la console Amazon Bedrock. Quindi, apri la console Amazon Bedrock all’indirizzo https://console.aws.amazon.com/bedrock.
Seleziona Agenti nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione Agenti.
Scegli Modifica in Agente Builder.
Nella sezione Gruppi di operazioni, seleziona Aggiungi.
(Facoltativo) Nella sezione Dettagli del gruppo di operazioni, modifica il nome generato automaticamente e fornisci una descrizione facoltativa per il tuo gruppo di operazioni.
Nella sezione Tipo di gruppo di operazioni, seleziona uno dei seguenti metodi per definire i parametri che l’agente può richiedere agli utenti per facilitare l’esecuzione delle azioni:
1. Definisci con i dettagli della funzione: definisci i parametri che l’agente deve richiedere all’utente per eseguire le azioni. Per ulteriori informazioni sull’aggiunta di funzioni, consulta Definizione dei dettagli della funzione per i gruppi di operazioni dell’agente in Amazon Bedrock.
2. Definisci con schemi API: definisci le operazioni API che l’agente può invocare e i relativi parametri. Utilizza uno schema OpenAPI che hai creato o creane uno con l’editor di testo della console. Per ulteriori informazioni sull’impostazione di uno schema OpenAPI, consulta Definire schemi OpenAPI per i gruppi di operazioni dell’agente in Amazon Bedrock.
Nella sezione Invocazione di un gruppo di operazioni, imposta ciò che fa l’agente dopo aver previsto l’API o la funzione da invocare e aver ricevuto i parametri necessari. Scegli una delle seguenti opzioni:
- Crea rapidamente una nuova funzione Lambda (scelta consigliata): consenti ad Amazon Bedrock di creare per l’agente una funzione Lambda di base che potrai successivamente modificare in AWS Lambda a seconda del tuo caso d’uso. L’agente passerà alla funzione Lambda l’API o la funzione che ha previsto e i relativi parametri, in base alla sessione.
- Seleziona una funzione Lambda esistente: scegli una funzione Lambda creata in precedenza in AWS Lambda e la versione della funzione da utilizzare. L’agente passerà alla funzione Lambda l’API o la funzione che ha previsto e i relativi parametri, in base alla sessione.
  
  Nota
  Per consentire al principale del servizio di Amazon Bedrock di accedere alla funzione Lambda, collega alla funzione Lambda una policy basata sulle risorse.
- Controllo del ritorno: anziché passare alla funzione Lambda i parametri per l’API o la funzione che ha previsto, l’agente restituisce il controllo all’applicazione passando nella risposta InvokeAgent l’azione che prevede debba essere invocata, oltre ai parametri e alle informazioni per l’azione che ha determinato dalla sessione. Per ulteriori informazioni, consulta Restituzione del controllo allo sviluppatore dell’agente inviando le informazioni richieste in una risposta InvokeAgent.

A seconda della scelta del Tipo di gruppo di operazioni, verrà visualizzata una delle seguenti sezioni:

Se hai selezionato Definisci con i dettagli della funzione, verrà visualizzata una sezione Funzione del gruppo di operazioni. Per definire la funzione, effettua le seguenti operazioni:

Fornisci un Nome e una Descrizione facoltativa (ma consigliata).
Per richiedere la conferma all’utente prima che la funzione venga invocata, seleziona Abilitata. Richiedere la conferma prima di invocare la funzione può impedire all’applicazione di intraprendere azioni causate da iniezioni di prompt dannose.

Nella sottosezione Parametri, scegli Aggiungi parametro. Definisci i campi seguenti:

Campo	Descrizione
Nome	Assegna un nome al parametro.
Descrizione (facoltativa)	Descrivi il parametro.
Tipo	Specifica il tipo di dati del parametro.
Richiesto	Specifica se l’agente richiede il parametro all’utente.

Per aggiungere un altro parametro, scegli Aggiungi parametro.
Per modificare un campo in un parametro, selezionalo e apporta le modifiche necessarie.
Per eliminare un parametro, scegli l’icona di eliminazione ( ) nella riga contenente il parametro.

Se preferisci definire la funzione utilizzando un oggetto JSON, scegli Editor JSON anziché Tabella. Il formato dell’oggetto JSON è il seguente (ogni chiave nell’oggetto parameters è un nome di parametro fornito dall’utente):


{
    "name": "string",
    "description": "string",
    "parameters": [
        {
            "name": "string",
            "description": "string",
            "required": "True" | "False",
            "type": "string" | "number" | "integer" | "boolean" | "array"
        }
    ]
}

Per aggiungere un’ulteriore funzione al gruppo di operazioni definendo un altro set di parametri, scegli Aggiungi la funzione del gruppo di operazioni.

Se hai selezionato Definisci con schemi API, verrà visualizzata una sezione Schema del gruppo di operazioni con le seguenti opzioni:
- Per utilizzare uno schema OpenAPI precedentemente preparato con descrizioni, strutture e parametri delle API per il gruppo di operazioni, scegli Seleziona lo schema API e fornisci un link all’URI Amazon S3 dello schema.
- Per definire lo schema OpenAPI con l’editor di schemi in linea, seleziona Definizione tramite editor di schemi in linea. Viene visualizzato uno schema di esempio che puoi modificare.
  1. Seleziona il formato per lo schema utilizzando il menu a discesa accanto a Formato.
  2. Per importare uno schema esistente da S3 per modificarlo, seleziona Importa schema, fornisci l'URI S3 e seleziona Importa.
  3. Per ripristinare lo schema allo schema di esempio originale, seleziona Reimposta, quindi conferma il messaggio visualizzato selezionando nuovamente Reimposta.

Una volta completata la creazione del gruppo di operazioni, scegli Aggiungi. Se hai definito uno schema API e non si sono verificati problemi, viene visualizzato un banner verde che notifica la riuscita dell’operazione. In caso di problemi durante la convalida dello schema, viene visualizzato un banner rosso. Sono disponibili le seguenti opzioni:
- Scorri lo schema per visualizzare le righe in cui è presente un errore o un avviso sulla formattazione. Una X indica un errore di formattazione, mentre un punto esclamativo indica un avviso sulla formattazione.
- Seleziona Visualizza dettagli nel banner rosso per visualizzare un elenco di errori relativi al contenuto dello schema API.
Prepara l’agente per l’applicazione delle modifiche apportate prima di testarlo.

API

Per creare un gruppo di operazioni, invia una richiesta CreateAgentActionGroup con un endpoint in fase di compilazione di Agent per Amazon Bedrock. È necessario fornire uno schema di funzioni o uno schema OpenAPI.

Nell’elenco riportato di seguito sono descritti i campi presenti nella richiesta.

I seguenti campi sono obbligatori:

Campo	Breve descrizione
agentId	L’ID dell’agente a cui appartiene il gruppo di operazioni.
agentVersion	La versione dell’agente a cui appartiene il gruppo di operazioni.
actionGroupName	Il nome del gruppo di operazioni.

Per definire i parametri per il gruppo di operazioni, è necessario specificare uno dei seguenti campi (non è possibile specificarli entrambi).

Campo	Breve descrizione
functionSchema	Definisce i parametri per il gruppo di operazioni che l’agente richiede all’utente. Per ulteriori informazioni, consulta Definizione dei dettagli della funzione per i gruppi di operazioni dell’agente in Amazon Bedrock.
apiSchema	Specifica lo schema OpenAPI che definisce i parametri per il gruppo di operazioni o i collegamenti a un oggetto S3 che lo contiene. Per ulteriori informazioni, consulta Definire schemi OpenAPI per i gruppi di operazioni dell’agente in Amazon Bedrock.

Di seguito viene illustrato il formato generale di functionSchema e apiSchema:

Ogni elemento della matrice functionSchema è un oggetto FunctionSchema. Per ogni evento, specifica quanto segue:
- Fornisci un name e una description facoltativa (ma consigliata).
- Facoltativamente, specifica ENABLED per il campo requireConfirmation per richiedere la conferma all’utente prima che la funzione venga invocata. Richiedere la conferma prima di invocare la funzione può impedire all’applicazione di intraprendere azioni causate da iniezioni di prompt dannose.
- Nell’oggetto parameters, ogni chiave è un nome di parametro, mappato ai relativi dettagli in un oggetto ParameterDetail.
Il formato generale di functionSchema è il seguente:
```
"functionSchema": [
    {
        "name": "string",
        "description": "string",
        "requireConfirmation": ENABLED | DISABLED,
        "parameters": {
            "<string>": {
                "type": "string" | number | integer | boolean | array,
                "description": "string",
                "required": boolean
            },
            ... // up to 5 parameters
        }
    },
    ... // up to 11 functions
]
```
APISchema può avere uno dei seguenti formati:
1. Per quanto riguarda il formato seguente, è possibile incollare direttamente come valore lo schema OpenAPI in formato YAML o JSON.
```
"apiSchema": {
    "payload": "string"
}
```
2. Per quanto riguarda il formato seguente, specifica il nome del bucket Amazon S3 e la chiave oggetto in cui è archiviato lo schema OpenAPI.
```
"apiSchema": {
    "s3": {
        "s3BucketName": "string",
        "s3ObjectKey": "string"
    }
}
```

Per configurare il modo in cui il gruppo di operazioni gestisce la propria invocazione dopo aver ottenuto i parametri dall’utente, all’interno del campo actionGroupExecutor devi specificare uno dei campi indicati di seguito.

Campo	Breve descrizione
lambda	Per inviare i parametri a una funzione Lambda allo scopo di gestire i risultati dell’invocazione del gruppo di operazioni, specifica il nome della risorsa Amazon (ARN) della Lambda. Per ulteriori informazioni, consulta Configura le funzioni Lambda per inviare informazioni che un agente di Amazon Bedrock ricava dall’utente.
customControl	Per ignorare l’utilizzo di una funzione Lambda e restituire invece il gruppo di operazioni previsto, insieme alle informazioni e ai parametri richiesti, specifica `RETURN_CONTROL` nella risposta `InvokeAgent`. Per ulteriori informazioni, consulta Restituzione del controllo allo sviluppatore dell’agente inviando le informazioni richieste in una risposta InvokeAgent.

I seguenti campi sono facoltativi:

Campo	Breve descrizione
parentActionGroupSignature	Specifica `AMAZON.UserInput` per consentire all’agente di chiedere nuovamente all’utente ulteriori informazioni se non dispone di informazioni sufficienti per completare un altro gruppo di operazioni. Se si specifica questo campo, è necessario lasciare vuoti i campi `description`, `apiSchema` e `actionGroupExecutor`.
description	Descrizione del gruppo di regole.
actionGroupState	Stabilisce se consentire o meno all’agente di invocare il gruppo di operazioni.
clientToken	Un identificatore per impedire la duplicazione delle richieste.


    def create_agent_action_group(
            self, name, description, agent_id, agent_version, function_arn, api_schema
    ):
        """
        Creates an action group for an agent. An action group defines a set of actions that an
        agent should carry out for the customer.

        :param name: The name to give the action group.
        :param description: The description of the action group.
        :param agent_id: The unique identifier of the agent for which to create the action group.
        :param agent_version: The version of the agent for which to create the action group.
        :param function_arn: The ARN of the Lambda function containing the business logic that is
                             carried out upon invoking the action.
        :param api_schema: Contains the OpenAPI schema for the action group.
        :return: Details about the action group that was created.
        """
        try:
            response = self.client.create_agent_action_group(
                actionGroupName=name,
                description=description,
                agentId=agent_id,
                agentVersion=agent_version,
                actionGroupExecutor={"lambda": function_arn},
                apiSchema={"payload": api_schema},
            )
            agent_action_group = response["agentActionGroup"]
        except ClientError as e:
            logger.error(f"Error: Couldn't create agent action group. Here's why: {e}")
            raise
        else:
            return agent_action_group

Per ulteriori informazioni, consulta Agent per Amazon Bedrock.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Come ottenere la conferma dell’utente prima di invocare un’azione

Visualizzazione di informazioni su un gruppo di operazioni