Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Creazione e configurazione manuale dell’agente
# Prerequisiti per la creazione di agenti di Amazon Bedrock
Assicurati che il tuo ruolo IAM disponga delle [autorizzazioni necessarie](security_iam_id-based-policy-examples-agent.md#iam-agents-ex-all) per eseguire azioni relative ad Agent per Amazon Bedrock.
Prima di creare un agente, esamina i prerequisiti indicati di seguito e determina quali occorre soddisfare.
1. Devi impostare almeno una delle seguenti opzioni per il tuo agente:
+ [Gruppo di operazioni](agents-action-create.md): definisce le azioni la cui esecuzione può essere semplificata dall’agente. Ogni gruppo di operazioni include i parametri che l’agente deve richiedere all’utente finale. È inoltre possibile definire le API che possono essere chiamate, come gestire l’azione e come restituire la risposta. Per visualizzare la quota per i gruppi di operazioni in un agente, consulta la quota **Gruppi di operazioni per agente** in [Endpoint e quote di Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) in Riferimenti generali di AWS. Se prevedi di non avere gruppi di operazioni per l’agente, puoi ignorare questo prerequisito.
+ [Knowledge base](knowledge-base.md); fornisce un repository di informazioni che l’agente può consultare per rispondere alle query dei clienti e migliorare le risposte generate. Associare almeno una knowledge base può aiutare a migliorare le risposte alle query dei clienti utilizzando origini dati private. Per visualizzare la quota di knowledge base collegata un agente, consulta la quota delle **Knowledge base associate per agente** in [Endpoint e quote di Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) in Riferimenti generali di AWS. Se prevedi di non avere knowledge base associate all’agente, puoi ignorare questo prerequisito.
1. (Facoltativo) [Crea un [ruolo di servizio](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role)AWS Identity and Access Management (IAM) personalizzato per l’agente con le autorizzazioni appropriate](agents-permissions.md). Se prevedi di utilizzare Console di gestione AWS affinché crei automaticamente un ruolo di servizio per tuo conto, puoi ignorare questo prerequisito.
1. (Facoltativo) Crea un [guardrail](guardrails.md) per implementare misure di salvaguardia per l’agente e impedire comportamenti indesiderati da parte di modelli di risposta e messaggi degli utenti e associalo all’agente.
1. (Facoltativo) Acquista [Throughput assegnato](prov-throughput.md) per aumentare il numero e la frequenza dei token che il tuo agente può elaborare in un determinato periodo di tempo. Puoi quindi associarlo a un alias dell’agente quando [crei una versione dell’agente e vi associ un alias](agents-deploy.md).
Per creare un agente con Amazon Bedrock, è necessario impostare i seguenti componenti:
+ La configurazione dell’agente, che definisce il relativo scopo e il modello di fondazione (FM) che deve utilizzare per generare prompt e risposte.
+ Almeno uno dei seguenti elementi:
+ Gruppi di operazioni che definiscono le azioni per cui l’agente è progettato.
+ Una knowledge base di origini dati per aumentare le capacità generative dell’agente consentendo ricerca e query.
Come minimo, è possibile creare un agente che abbia solo un nome. Per **preparare** un agente in modo da poterlo [testare](agents-test.md) o [implementare](agents-deploy.md), è necessario configurare almeno i seguenti componenti:
****
| Configurazione | Descrizione |
| --- | --- |
| Ruolo della risorsa agente | L’ARN del [ruolo di servizio con autorizzazioni per chiamare le operazioni API sull’agente](agents-permissions.md) |
| Modello di fondazione (FM) | Un FM che l’agente può invocare per eseguire l’orchestrazione |
| Istruzioni | Linguaggio naturale che descrive cosa deve fare l’agente e come deve interagire con gli utenti |
È inoltre necessario configurare almeno un gruppo di operazioni o una knowledge base per l’agente. Se prepari un agente senza gruppi di operazioni o knowledge base, restituirà risposte basate solo su FM, istruzioni e [modelli di prompt di base](advanced-prompts.md).
Per scoprire come creare un agente, scegli la scheda relativa al metodo che preferisci, quindi segui i passaggi sotto indicati.
------
#### [ Console ]
**Per creare un agente**
1. 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](https://console.aws.amazon.com/bedrock).
1. Seleziona **Agenti** nel riquadro di navigazione a sinistra.
1. Nella sezione **Agenti**, scegli **Crea agente**.
1. (Facoltativo) Modifica il **nome** generato automaticamente per l’agente e fornisci una **descrizione** facoltativa.
1. Seleziona **Create** (Crea). Una volta creato l’agente, l’utente viene indirizzato al relativo **Agente Builder** per configurarlo.
1. Puoi continuare con la seguente procedura e configurare subito l’agente o tornare ad Agente Builder in un secondo momento.
**Per configurare l’agente**
1. Se non hai già eseguito l’accesso ad Agente builder, procedi come segue:
1. 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](https://console.aws.amazon.com/bedrock).
1. Seleziona **Agenti** nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione **Agenti**.
1. Scegli **Modifica in Agente Builder**.
1. Nella sezione **Dettagli dell’agente** puoi eseguire le seguenti configurazioni:
1. Modifica il **Nome dell’agente** o la **Descrizione dell’agente**.
1. Per **Ruolo per la risorsa dell’agente**, seleziona una delle seguenti opzioni:
+ **Crea e usa un nuovo ruolo di servizio**: consenti ad Amazon Bedrock di creare il ruolo di servizio e configurare le autorizzazioni richieste per tuo conto.
+ **Usa un ruolo di servizio esistente**: utilizza un [ruolo personalizzato](agents-permissions.md) che hai impostato in precedenza.
1. Per **Seleziona modello**, seleziona un FM che l’agente possa invocare durante l’orchestrazione.
Per impostazione predefinita, vengono visualizzati i modelli ottimizzati per gli agenti. Per visualizzare tutti i modelli supportati da Agent per Amazon Bedrock, deseleziona **Agenti Bedrock ottimizzati**.
![\[È possibile creare agenti con qualsiasi modello di fondazione. Attualmente, alcuni modelli offerti sono ottimizzati con prompt/parser sottoposti a fine-tuning per l’integrazione con l’architettura degli agenti. Nel tempo intendiamo offrire l’ottimizzazione per tutti i modelli.\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/images/agents/agents-optimized-model-selection.png)
1. In **Istruzioni per l’agente**, fornisci i dettagli per indicare all’agente cosa deve fare e come deve interagire con gli utenti. Le istruzioni sostituiscono il segnaposto \$1instructions\$1 nel [modello di prompt di orchestrazione](prompt-placeholders.md#placeholders-orchestration). Di seguito è riportato un esempio di istruzioni:
```
You are an office assistant in an insurance agency. You are friendly and polite. You help with managing insurance claims and coordinating pending paperwork.
```
1. Se espandi **Impostazioni aggiuntive**, puoi modificare le seguenti configurazioni:
+ **Interprete di codice**: (facoltativo) scegli se consentire all’agente di gestire attività che implicano scrittura, esecuzione, test e risoluzione di problemi di codice. Per informazioni dettagliate, vedi [Generazione, esecuzione e test del codice con l’interpretazione del codice](agents-code-interpretation.md).
+ **Input dell’utente**: (facoltativo) scegli se consentire all’agente di richiedere ulteriori informazioni all’utente se non dispone di informazioni sufficienti. Per informazioni dettagliate, vedi [Configurazione dell’agente per richiedere informazioni all’utente](agents-user-input.md).
+ **Selezione chiave KMS**: (facoltativo) per impostazione predefinita, AWS crittografa le risorse dell’agente con una Chiave gestita da AWS. Per crittografare l’agente utilizzando la chiave gestita dal cliente, nella sezione Selezione chiave KMS scegli **Personalizza le impostazioni di crittografia (avanzate)**. Per creare una nuova chiave, seleziona **Crea una chiave AWS KMS** e aggiorna questa finestra. Per utilizzare una chiave esistente, selezionane una per **Scegli una chiave AWS KMS**.
+ **Timeout della sessione inattiva**: per impostazione predefinita, se un utente non risponde per 30 minuti in una sessione con un agente di Amazon Bedrock, l’agente non mantiene più la cronologia delle conversazioni. La cronologia delle conversazioni viene utilizzata sia per riprendere un'interazione sia per aumentare le risposte in base al contesto della conversazione. Per modificare questo periodo di tempo predefinito, inserisci un numero nel campo **Timeout della sessione** e scegli un’unità di tempo.
1. Nella sezione **Autorizzazioni IAM**, per il **Ruolo della risorsa dell’agente**, scegli un [ruolo di servizio](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role). Per consentire ad Amazon Bedrock di creare il ruolo di servizio per tuo conto, seleziona **Crea e usa un nuovo ruolo di servizio**. Per utilizzare un [ruolo personalizzato](agents-permissions.md) creato in precedenza, seleziona **Usa un ruolo di servizio esistente**.
**Nota**
Il ruolo di servizio che Amazon Bedrock crea per tuo conto non supporta le autorizzazioni per le funzionalità disponibili in anteprima. Per utilizzare queste funzionalità, [collega le autorizzazioni corrette al ruolo di servizio](agents-permissions.md).
1. (Facoltativo) Per impostazione predefinita, AWS crittografa le risorse degli agenti con una Chiave gestita da AWS. Per crittografare l’agente utilizzando la chiave gestita dal cliente, nella sezione **Selezione chiave KMS**, scegli **Personalizza le impostazioni di crittografia (avanzate)**. Per creare una nuova chiave, seleziona **Crea una chiave AWS KMS** e aggiorna questa finestra. Per utilizzare una chiave esistente, selezionane una per **Scegli una chiave AWS KMS**.
1. (Facoltativo) Per associare tag a questo agente, nella sezione **Tag - facoltativi**, scegli **Aggiungi nuovo tag** e fornisci una coppia chiave-valore.
1. Quando la configurazione dell’agente è completa, seleziona **Avanti**.
1. Nella sezione **Gruppi di operazioni**, puoi scegliere **Aggiungi** per aggiungere gruppi di operazioni al tuo agente. Per ulteriori informazioni sulla configurazione di gruppi di operazioni, consulta [Utilizzo di gruppi di operazioni per definire le azioni che l’agente deve eseguire](agents-action-create.md). Per informazioni su come aggiungere gruppi di operazioni all’agente, consulta [Aggiunta di un gruppo di operazioni all’agente in Amazon Bedrock](agents-action-add.md).
1. Nella sezione **Knowledge base**, puoi scegliere **Aggiungi** per associare i gruppi di conoscenza all’agente. Per ulteriori informazioni sull’impostazione delle knowledge base, consulta [Recupero di dati e generazione di risposte di IA con Knowledge Base per Amazon Bedrock](knowledge-base.md). Per informazioni su come associare le knowledge base all’agente, consulta [Aumento della generazione di risposte per il proprio agente con la knowledge base](agents-kb-add.md).
1. Nella sezione dei **Dettagli del guardrail**, puoi scegliere **Modifica** per associare un guardrail all’agente in modo da bloccare e filtrare i contenuti dannosi. Seleziona il guardrail che vuoi utilizzare dal menu a discesa in **Seleziona guardrail**, quindi scegli la versione desiderata in **Versione guardrail**. Per consultare le impostazioni del guardrail, seleziona **Visualizza**. Per ulteriori informazioni, consulta [Rilevare e filtrare contenuti dannosi utilizzando Guardrail per Amazon Bedrock](guardrails.md).
1. Nella sezione **Strategia di orchestrazione**, puoi scegliere **Modifica** per personalizzare l’orchestrazione dell’agente. Per ulteriori informazioni sulla strategia di orchestrazione che puoi utilizzare per l’agente, consulta [Personalizzazione della strategia di orchestrazione degli agenti](orch-strategy.md).
1. Nella sezione **Collaborazione multiagente**, puoi scegliere **Modifica** per creare un team di collaborazione multiagente. Per ulteriori informazioni sulla collaborazione multiagente, consulta [Utilizzo della collaborazione multiagente con Agent per Amazon Bedrock](agents-multi-agent-collaboration.md).
1. Al termine della configurazione dell’agente, seleziona una delle seguenti opzioni:
+ Per rimanere in **Agente Builder**, scegli **Salva**. Quindi **Prepara** l’agente per testarlo con le configurazioni aggiornate nella finestra di test. Per informazioni su come testare l’agente, consulta [Test e risoluzione dei problemi relativi al comportamento dell’agente](agents-test.md).
+ Per tornare alla pagina dei **Dettagli dell’agente**, scegli **Salva ed esci**.
------
#### [ API ]
Per creare un agente, invia una richiesta [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) (consulta il link per i formati di richiesta e risposta e i dettagli sui campi) con un [endpoint in fase di compilazione di Agent per Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt).
[Vedi esempi di codice](bedrock-agent_example_bedrock-agent_CreateAgent_section.md)
Per preparare il tuo agente in modo da poterlo [testare](agents-test.md) o [implementare](agents-deploy.md), devi includere almeno i seguenti campi (se preferisci, puoi saltare queste configurazioni ed effettuarle in un secondo momento inviando una richiesta [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html)):
****
| Campo | Caso d'uso |
| --- | --- |
| agentResourceRoleArn | Per specificare un ARN del ruolo di servizio con autorizzazioni per chiamare le operazioni API sull’agente |
| foundationModel | Per specificare un modello di fondazione (FM) che l’agente può utilizzare per l’orchestrazione |
| instruction | Per fornire istruzioni che indichino all’agente cosa fare; utilizzato nel segnaposto \$1instructions\$1 del modello di prompt di orchestrazione |
I seguenti campi sono facoltativi:
****
| Campo | Caso d'uso |
| --- | --- |
| description | Descrive cosa fa l’agente |
| idleSessionTTLInSeconds | Durata dopo la quale l’agente termina la sessione ed elimina tutte le informazioni archiviate |
| customerEncryptionKeyArn | ARN di una chiave KMS per crittografare le risorse degli agenti |
| tags | Per associare i [tag](tagging.md) all’agente. |
| promptOverrideConfiguration | Per [personalizzare i prompt](advanced-prompts.md) inviati al modello di fondazione in ogni fase dell’orchestrazione |
| guardrailConfiguration | Per aggiungere un [guardrail](guardrails.md) all’agente; specifica l’ID o l’ARN del guardrail e la versione da utilizzare |
| clientToken | Per garantire che la richiesta API venga completata solo una volta. Per ulteriori informazioni, consulta [Garanzia di idempotenza](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html). |
| cachingState | Per abilitare la caching immediata dei prompt dell’input nell’agente. Per ulteriori informazioni, consulta [Caching dei prompt per un’inferenza del modello più rapida](prompt-caching.md). |
| reasoning\$1config | Per abilitare il ragionamento del modello, così che spieghi come ha raggiunto le sue conclusioni. Utilizzalo all’interno di un campo additionalModelRequestFields. È necessario specificare il numero di budget\$1tokens utilizzati per il ragionamento del modello, ovvero un sottoinsieme dei token di output. Per ulteriori informazioni, consulta [Migliorare le risposte del modello con il ragionamento basato su modello](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html). |
La risposta restituisce un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) che contiene dettagli sull’agente appena creato. Se l’agente non viene creato, l’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) nella risposta restituisce un elenco di `failureReasons` e un elenco di `recommendedActions` per risolvere il problema.
```
def create_agent(self, agent_name, foundation_model, role_arn, instruction):
"""
Creates an agent that orchestrates interactions between foundation models,
data sources, software applications, user conversations, and APIs to carry
out tasks to help customers.
:param agent_name: A name for the agent.
:param foundation_model: The foundation model to be used for orchestration by the agent.
:param role_arn: The ARN of the IAM role with permissions needed by the agent.
:param instruction: Instructions that tell the agent what it should do and how it should
interact with users.
:return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
"""
try:
response = self.client.create_agent(
agentName=agent_name,
foundationModel=foundation_model,
agentResourceRoleArn=role_arn,
instruction=instruction,
)
except ClientError as e:
logger.error(f"Error: Couldn't create agent. Here's why: {e}")
raise
else:
return response["agent"]
```
Per ulteriori informazioni, consulta [Agent per Amazon Bedrock](bedrock-agent_example_bedrock-agent_Hello_section.md).
------