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à.
# Dettagli dell'architettura
Questa sezione descrive i componenti e i servizi AWS che compongono questa soluzione e i dettagli dell'architettura su come questi componenti interagiscono.
## Servizi AWS in questa soluzione
| Servizio AWS | Description |
| --- | --- |
| [Gateway Amazon API](https://aws.amazon.com/api-gateway/) | **Core**. Questo servizio fornisce il REST APIs per la dashboard di distribuzione e l' WebSocket API per il caso d'uso. |
| [AWS CloudFormation](https://aws.amazon.com/cloudformation/) | **Nucleo**. Questa soluzione è distribuita come CloudFormation modello e CloudFormation distribuisce le risorse AWS per la soluzione. |
| [Amazon CloudFront](https://aws.amazon.com/cloudfront/) | **Nucleo**. CloudFront serve i contenuti Web ospitati in Amazon S3. |
| [Amazon Cognito](https://aws.amazon.com/cognito/) | **Nucleo**. Questo servizio gestisce la gestione e l'autenticazione degli utenti per l'API. |
| [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | **Nucleo**. DynamoDB archivia le informazioni sulla distribuzione e i dettagli di configurazione per la dashboard di distribuzione. Memorizza la cronologia chat e le conversazioni IDs nel caso d'uso Text per abilitare la cronologia delle conversazioni e la disambiguazione delle query. |
| [AWS Lambda](https://aws.amazon.com/lambda/) | **Nucleo.** La soluzione utilizza le funzioni Lambda per: \$1 Supporta gli endpoint WebSocket REST e API \$1 Gestisci la logica di base di ogni use case orchestrator \$1 Implementa risorse personalizzate durante la distribuzione CloudFormation |
| [Amazon S3](https://aws.amazon.com/s3/) | **Nucleo.** Amazon S3 ospita i contenuti Web statici. |
| [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) | **Supporto**. [Questa soluzione pubblica i log dalle risorse della soluzione nei [CloudWatch registri](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) e pubblica le metriche nelle metriche. CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) [La soluzione crea anche una dashboard per visualizzare questi datiCloudWatch .](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) |
| [AWS Systems Manager](https://aws.amazon.com/systems-manager/) | **Supporto**. Systems Manager fornisce il monitoraggio delle risorse a livello di applicazione e la visualizzazione delle operazioni delle risorse e dei dati sui costi. Utilizzato anche per memorizzare i dati di configurazione in Parameter Store. |
| [AWS WAF](https://aws.amazon.com/waf/) | **Supporto.** AWS WAF viene distribuito prima della distribuzione API Gateway per proteggerlo. |
| [Amazon Bedrock](https://aws.amazon.com/bedrock/) | **Facoltativo**. La soluzione sfrutta Amazon Bedrock per accedere a modelli base o personalizzati, Amazon Bedrock Agents, Amazon Bedrock Knowledge Base. Amazon Bedrock è l'integrazione consigliata per impedire che i dati lascino la rete AWS. |
| [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) | **Opzionale** La soluzione sfrutta Amazon Bedrock AgentCore per eseguire e supportare connessioni a server MCP, nonché casi d'uso di Agent Builder e Workflow. |
| [Amazon Elastic Container Registry (Amazon ECR)](https://aws.amazon.com/ecr/) | **Facoltativo**. Per le implementazioni di Agent Builder, ECR archivia e distribuisce le immagini dei container degli agenti. La soluzione utilizza ECR Pull-Through Cache per recuperare automaticamente le immagini predefinite degli agenti dall'archivio ECR pubblico del team GAAB. |
| [AWS Distro per OpenTelemetry (ADOT)](https://aws.amazon.com/otel/) | **Facoltativo**. Per le implementazioni di Agent Builder, ADOT fornisce una strumentazione automatica per l'osservabilità degli agenti, abilitando la tracciabilità distribuita e la registrazione strutturata per le operazioni degli agenti. |
| [Amazon Kendra](https://aws.amazon.com/kendra/) | **Facoltativo**. Nel caso Text use case, gli utenti amministratori possono facoltativamente decidere di collegare un indice Amazon Kendra da utilizzare come knowledge base per la conversazione con il LLM. Questo può essere usato per inserire nuove informazioni nel LLM, dandogli la possibilità di utilizzare tali informazioni nelle sue risposte. |
| [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) | **Facoltativo**. La soluzione può integrarsi con un endpoint di inferenza Amazon SageMaker AI per accedere ospitato all'interno del tuo account e della tua regione AWS ed è un'integrazione preferita per evitare FMs che i tuoi dati lascino la rete AWS. È necessario distribuire la soluzione nella stessa regione in cui è disponibile l'endpoint di inferenza. |
| [Amazon Virtual Private Cloud](https://aws.amazon.com/vpc/) | **Facoltativo**. La soluzione offre la possibilità di implementare componenti con una configurazione abilitata per VPC. Durante l'implementazione della soluzione con una configurazione abilitata per VPC, hai la possibilità di lasciare che la soluzione crei un VPC per te o utilizzare un VPC esistente nello stesso account e nella stessa regione in cui verrà distribuita la soluzione (Bring Your Own VPC). Se la soluzione crea il VPC, crea i componenti di rete necessari che includono sottoreti, gruppi di sicurezza e relative regole, tabelle di routing, rete, gateway NAT ACLs, gateway Internet, endpoint VPC e relative politiche. |
# Dashboard di implementazione
## Autorizzatori personalizzati API Gateway
In apparenza, gli autorizzatori personalizzati Lambda per API Gateway vengono utilizzati per tutte le chiamate API ( RESTful entrambe WebSocket e basate) per verificare se un determinato utente è autorizzato a eseguire un'azione in base ai gruppi a cui appartiene. Questo autorizzatore personalizzato è supportato da una tabella DynamoDB contenente le politiche per ogni gruppo. Quando viene richiamata un'API, API Gateway richiama la funzione di autorizzazione personalizzata Lambda, che decodifica il token di accesso Amazon Cognito fornito per determinare a quali gruppi di utenti appartiene l'utente. La tabella delle politiche viene quindi interrogata in base al nome del gruppo per restituire la politica pertinente per quel gruppo.
Ad ogni nuova implementazione di un caso d'uso, la policy di amministrazione viene aggiornata per memorizzare una nuova istruzione che consente l'azione **Execute-API:Invoke sull'API** di quel caso d'uso. Quando i casi d'uso vengono eliminati, l'istruzione corrispondente viene rimossa dalla policy.
Per i gruppi creati per un singolo caso d'uso, nella policy è presente una sola istruzione, che consente l'azione **Execute-API:Invoke** solo sull'API di quel caso d'uso.
Grazie a questa struttura, qualsiasi utente appartenente al gruppo di un caso d'uso può accedere all'API di quel caso d'uso. Un singolo utente può anche essere aggiunto manualmente a più gruppi per consentire a quell'utente di utilizzare più casi d'uso.
**avvertimento**
Puoi anche modificare manualmente le politiche per un determinato gruppo nella tabella delle politiche se desideri concedere l'accesso a un nuovo caso d'uso a un gruppo di utenti esistente. Il gruppo di casi d'uso viene eliminato quando lo use case viene eliminato (anche se sono state apportate modifiche manuali), quindi procedi con cautela quando elimini un caso d'uso.
Nel caso in cui uno stack di casi d'uso venga distribuito in modo indipendente (senza l'uso della dashboard di distribuzione), viene creato un [pool di utenti Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) per quella distribuzione contenente un singolo utente con accesso all'API di quel caso d'uso. Questo pool di utenti appartiene solo a questo caso d'uso e non è condiviso tra altre distribuzioni autonome.
# Caso di utilizzo del testo
## Supporto per lo streaming
In un'applicazione di chat, la latenza è una metrica importante per consentire un'esperienza utente reattiva. La possibilità che le inferenze LLM richiedano da secondi a minuti pone sfide su come offrire al meglio i contenuti ai clienti. Per questo motivo, diversi provider LLM consentono lo streaming delle risposte al chiamante. Invece di attendere il completamento dell'intera inferenza prima di restituire una risposta, ogni token può essere restituito quando è disponibile.
Per supportare l'uso di questa funzionalità, il caso d'uso Text è stato progettato per utilizzare un' WebSocket API a supporto dell'esperienza di chat. Questo WebSocket viene distribuito tramite API Gateway. L'uso di un' WebSocket API consente di creare una connessione all'inizio di una sessione di chat e di trasmettere le risposte attraverso quel socket. Ciò consente alle applicazioni frontend di fornire un'esperienza utente migliore.
**Nota**
Anche se un modello fornisce supporto per lo streaming, ciò non significa necessariamente che la soluzione sarà in grado di trasmettere le risposte tramite l' WebSocket API. È necessario che la soluzione abiliti la logica personalizzata per supportare lo streaming per ogni fornitore di modelli. Se lo streaming è disponibile, gli utenti amministratori potranno utilizzare enable/disable questa funzionalità al momento dell'implementazione.
# Come funziona la soluzione Generative AI Application Builder on AWS
L'utente amministratore si interfaccia principalmente con la dashboard di Deployment per visualizzare, creare e gestire implementazioni di use case nuove ed esistenti. Tramite questa dashboard, l'utente amministratore ha accesso alle seguenti azioni:
+ Visualizza l'elenco delle distribuzioni
+ Crea nuove distribuzioni
+ Modifica le distribuzioni esistenti
+ Clona la configurazione di una distribuzione per crearne una nuova
+ Eliminare una distribuzione (rimuovere il provisioning delle risorse tramite un' CloudFormation eliminazione)
+ Eliminare definitivamente i dettagli di configurazione di una distribuzione
**Illustra il diagramma dei casi d'uso per l'utente amministratore del dashboard di distribuzione**
![\[immagine 4\]](http://docs.aws.amazon.com/it_it/solutions/latest/generative-ai-application-builder-on-aws/images/image4.png)
**Nota**
L'utente amministratore potrebbe non avere accesso diretto alla console AWS. In tal caso, l'utente amministratore deve collaborare con l' DevOps utente per supportare azioni come l'inserimento di dati in una knowledge base di Kendra.
Nel caso d'uso Text, l'utente aziendale ha accesso a un'interfaccia utente che gli consente di chattare con l'LLM. Le specifiche di questa configurazione sono controllate dalle impostazioni di distribuzione configurate dall'utente amministratore. Nel caso Text use case, l'utente aziendale ha accesso alle seguenti azioni:
+ Invia messaggi tramite l'interfaccia di chat
+ Visualizza la cronologia delle conversazioni
+ Cancella la cronologia delle conversazioni
+ Visualizza prompt
+ Richiesta di modifica
**Rappresenta il diagramma dei casi d'uso per l'utente aziendale dello use case Text**
![\[immagine 5\]](http://docs.aws.amazon.com/it_it/solutions/latest/generative-ai-application-builder-on-aws/images/image5.png)
Con lo use case Bedrock Agent, l'utente aziendale può accedere a un'interfaccia utente per chattare con l'Amazon Bedrock Agent configurato. L'utente amministratore può configurare queste specifiche nelle impostazioni di distribuzione. Nel caso d'uso di Bedrock Agent, l'utente aziendale ha accesso alle seguenti azioni:
+ Invia messaggi tramite l'interfaccia di chat
+ Visualizza la cronologia delle conversazioni
+ Cancella la cronologia delle conversazioni
**Illustra il diagramma dei casi d'uso per l'utente aziendale dello use case di Bedrock Agent**
![\[diagramma utente del caso d'uso dell'agente\]](http://docs.aws.amazon.com/it_it/solutions/latest/generative-ai-application-builder-on-aws/images/agent-use-case-user-diagram.png)
# Agent Builder
Agent Builder fornisce una piattaforma per la creazione, la distribuzione e la gestione di agenti AI pronti per la produzione su Amazon Bedrock. AgentCore Questa sezione descrive i componenti tecnici e i dettagli di implementazione.
## AgentCore integrazione
Agent Builder utilizza un approccio di distribuzione basato sulla configurazione con immagini predefinite degli agenti per consentire implementazioni rapide, sicure e scalabili.
**Immagini predefinite degli agenti**
Le immagini dei container degli agenti vengono create dal team GAAB durante la CI/CD pipeline e pubblicate in un repository ECR pubblico. Ogni versione dell'immagine è collegata alla versione della soluzione GAAB (ad esempio, v4.0.0 →:v4.0.0). gaab-strands-agent Le immagini sono basate su Strands SDK e includono:
+ Ambiente di runtime dell'agente
+ Integrazione del client MCP
+ Funzionalità di gestione della memoria
+ OpenTelemetry strumentazione
**Cache pull-through ECR**
La soluzione utilizza ECR Pull-Through Cache per distribuire automaticamente le immagini degli agenti dall'archivio ECR pubblico all'ECR privato del cliente. Questo servizio gestito da AWS:
+ Memorizza le immagini nella cache alla prima estrazione (ritardo di 2-5 minuti)
+ Elimina la logica di copia personalizzata delle immagini
+ Fornisce la disponibilità locale delle immagini per le distribuzioni successive
+ Crea regole di cache uniche per ogni distribuzione per evitare conflitti
**Archiviazione della configurazione**
Le configurazioni degli agenti sono archiviate in DynamoDB insieme alle configurazioni dei casi d'uso esistenti. Ogni configurazione include:
+ Modello di prompt di sistema
+ Fornitore e ID del modello
+ Parametri del modello (temperatura, max\$1tokens)
+ Riferimenti ed endpoint del server MCP
+ Impostazioni della memoria (commutazione della memoria a lungo termine)
+ Metadati di distribuzione
**Registro delle versioni dell'immagine**
Una tabella DynamoDB tiene traccia delle versioni delle immagini degli agenti disponibili e della relativa URIs cache, abilitando la gestione delle versioni e la compatibilità con le versioni precedenti.
## Configurazione dell'agente
**Richieste di sistema**
I prompt di sistema definiscono il comportamento, la personalità e le capacità degli agenti. Gli utenti amministratori possono:
+ Modificare il modello predefinito tramite l'interfaccia utente di Agent Builder
+ Include istruzioni per l'utilizzo degli strumenti e la formattazione delle risposte
+ Ripristina il modello predefinito in qualsiasi momento
**Selezione del modello**
Agent Builder supporta i modelli Amazon Bedrock nella versione 4.0.0:
+ Fornitore del modello: Amazon Bedrock (solo opzione nella versione 4.0.0)
+ Selezione del modello: Claude, Nova e altri modelli Bedrock
+ Parametri del modello: Temperature, max\$1tokens, top\$1p e impostazioni specifiche del modello
**Integrazione con server MCP**
I server Model Context Protocol forniscono agli agenti l'accesso a strumenti e dati aziendali:
+ Individuazione dei server tramite l'endpoint API GET /mcp
+ Configurazione dinamica senza modifiche al codice
+ Autenticazione e gestione degli endpoint
+ Esposizione delle funzionalità degli strumenti agli agenti
## Streaming ed elaborazione
**Streaming in tempo reale**
Agent Builder utilizza Server-Sent Events (SSE) da AgentCore bridge a per WebSocket lo streaming di risposte in tempo reale:
+ La funzione Lambda stabilisce la connessione SSE a Runtime AgentCore
+ Gli stream sono collegati all'API Gateway WebSocket
+ Consente la consegna delle token-by-token risposte ai clienti
+ Mantiene la connessione per le richieste di lunga durata
**Vincoli di elaborazione**
L'elaborazione dell'agente nella v4.0.0 è limitata al timeout di esecuzione Lambda:
+ Tempo massimo di elaborazione: 15 minuti
+ Modello di elaborazione sincrona
+ Adatto per agenti conversazionali e flussi di lavoro moderati
+ Supporto asincrono esteso previsto per la versione 4.1\$1
## Gestione della memoria
**Memoria a breve termine**
Abilitato per impostazione predefinita per tutti gli agenti che utilizzano una configurazione personalizzata MemoryHookProvider:
+ Cattura gli eventi di conversazione tramite i gestori di callback di Strands
+ Organizza per actorID e sessionID per l'isolamento del contesto
+ Mantiene il contesto della conversazione all'interno delle sessioni
+ Integrazione automatica con la AgentCore memoria
**Memoria a lungo termine**
Funzionalità opzionale che utilizza AgentCore Memory Tool di strands\$1tools:
+ Attivazione semplice nell'interfaccia utente di Agent Builder
+ Strategia di memoria semantica con impostazioni predefinite
+ Accesso controllato dall'agente tramite invocazione naturale degli strumenti
+ Memorizza le informazioni estratte tra le sessioni
+ Utilizza ConversationID come SessionID
## Osservabilità
** OpenTelemetry Distribuzione AWS (ADOT)**
Gli agenti vengono dotati automaticamente di strumenti durante la creazione del container:
+ Generazione automatica di tracce per le operazioni degli agenti
+ Tracciamento distribuito attraverso i confini del servizio
+ Registrazione strutturata con correlazione IDs
+ Integrazione con Transaction Search CloudWatch
**Flusso di autenticazione**
Gli utenti si autenticano tramite Amazon Cognito con token JWT convalidati da autorizzatori Lambda personalizzati che recuperano le policy IAM da DynamoDB in base ai gruppi di utenti.
## Workflow Builder
Workflow Builder consente l'orchestrazione multiagente creando un agente supervisore che coordina più agenti Agent Builder utilizzando il modello di delega Agents as Tools.
### Architettura del workflow
**Componenti chiave**
+ Agente **supervisore: agente** Entrypoint che riceve le richieste degli utenti e delega ad agenti specializzati
+ **Agenti specializzati: Agent** Builder utilizza casi registrati come strumenti per il supervisore
+ **Agent Registry**: tabella DynamoDB che memorizza le configurazioni e i metadati degli agenti
+ Livello di **orchestrazione: implementazione del pattern Agents as Tools tramite Strands** SDK
### Istanziazione dell'agente
**Creazione di agenti locali**
Tutti gli agenti specializzati vengono istanziati localmente all'interno dello stesso AgentCore Runtime:
1. Recupera le configurazioni degli agenti da DynamoDB
1. Crea istanze locali di ogni agente Agent Builder
1. Ogni agente mantiene le proprie connessioni al server MCP
1. L'agente supervisore registra agenti specializzati come strumenti
1. Strands SDK gestisce la selezione e la delega degli agenti