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à.
# Inizia a fornire agli agenti l'accesso alle applicazioni WorkSpaces
Per consentire agli agenti AI di gestire le applicazioni desktop tramite Amazon WorkSpaces Applications, devi creare uno stack con accesso abilitato per gli agenti, generare un URL di streaming e connettere il tuo agente al servizio MCP gestito.
Se stai configurando l'accesso degli agenti per la prima volta, puoi utilizzare l'esperienza di avvio rapido Build Your First Agent. Puoi anche seguire i passaggi descritti in questo argomento per configurare manualmente l'accesso dell'agente. [L'esperienza di avvio rapido è disponibile nel GitHub repository: sample-code-for-workspaces-agent-access.](https://github.com/aws-samples/sample-code-for-workspaces-agent-access)
Il completamento di questo tutorial richiede circa 15 minuti.
**Importante**
Le risorse che crei in questo tutorial potrebbero comportare addebiti sul tuo AWS account. Elimina lo stack e ferma la flotta quando hai finito per evitare addebiti continui.
In questo tutorial, completerai le seguenti attività:
+ Fase 1: Creare uno stack con l'accesso dell'agente abilitato
+ Fase 2: Generazione di un URL di streaming
+ Fase 3: Collega il tuo agente al servizio MCP
+ Fase 4: Verifica l'attività dell'agente
+ Fase 5: eliminazione delle risorse
## Prerequisiti
Prima di iniziare, assicurati di disporre di:
+ Una flotta di WorkSpaces applicazioni Amazon attiva. Se non ne hai ancora configurato uno, consulta[Inizia a usare Amazon WorkSpaces Applications: Configurazione con applicazioni di esempio](getting-started.md).
+ AWS credenziali (variabili di ambiente, AWS profilo, ruolo dell'istanza EC2 o ruolo di esecuzione Lambda) con le seguenti autorizzazioni IAM. L'agente utilizza queste credenziali direttamente per firmare le richieste al servizio MCP:
```
{
"Sid": "MCP",
"Effect": "Allow",
"Action": ["agentaccess-mcp:*"],
"Resource": "*"
},
{
"Sid": "AppStream",
"Effect": "Allow",
"Action": ["appstream:CreateStreamingURL", "appstream:DescribeFleets"],
"Resource": "*"
}
```
Il `agentaccess-mcp:*` jolly include le seguenti azioni:
+ `agentaccess-mcp:InvokeMcp`— Inizializza le sessioni e scopri gli strumenti
+ `agentaccess-mcp:GetScreenshot`— Acquisisci lo stato dello schermo
+ `agentaccess-mcp:LeftClick`— Esegui il clic sinistro del mouse
+ `agentaccess-mcp:DoubleClick`— Esegui un doppio clic
+ `agentaccess-mcp:TripleClick`— Esegui un triplo clic
+ `agentaccess-mcp:RightClick`— Esegui il clic con il tasto destro del mouse
+ `agentaccess-mcp:MiddleClick`— Eseguire il clic centrale del mouse
+ `agentaccess-mcp:TypeText`— Digitare una stringa di testo
+ `agentaccess-mcp:KeyPress`— Premere il tasto o la combinazione di tasti
+ `agentaccess-mcp:HoldKey`— Tieni premuto il tasto per tutta la durata
+ `agentaccess-mcp:Scroll`— Scorri fino alle coordinate
+ `agentaccess-mcp:MovePointer`— Sposta il puntatore sulle coordinate
+ `agentaccess-mcp:LeftClickDrag`— Esegui il trascinamento con il tasto sinistro
+ `agentaccess-mcp:LeftMouseDown`— Tieni premuto il pulsante sinistro del mouse
+ `agentaccess-mcp:LeftMouseUp`— Rilascia il pulsante sinistro del mouse
+ `agentaccess-mcp:CheckConnectionStatus`— Verifica lo stato della connessione di una sessione di streaming
+ `agentaccess-mcp:CallForwardedTool`— Richiama uno strumento inoltrato su un'istanza remota
+ Un MCP-compatible framework di agenti. L'agente deve essere in grado di effettuare richieste HTTP SigV4-signed Streamable all'endpoint MCP. L'[SDK Strands Agents](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) fornisce supporto client MCP nativo oppure puoi utilizzare qualsiasi framework con il trasporto mcp-proxy-for-aws.
+ Python 3.10 o successivo. Non è richiesto alcun sistema operativo specifico.
## Fase 1: Creare uno stack con l'accesso dell'agente abilitato
Crea uno stack di WorkSpaces applicazioni con accesso agli agenti abilitato per consentire agli agenti AI di interagire con le applicazioni desktop.
### Utilizzo di AWS Console di gestione
**Per creare uno stack con accesso da agente**
1. Apri la [console WorkSpaces Applicazioni](https://console.aws.amazon.com/appstream2/home).
1. Nel riquadro di navigazione a sinistra, scegli **Stacks**, quindi scegli **Crea stack**.
1. Nella pagina dei **dettagli dello stack** (passaggio 1 di 4), in **Accesso all'agente AI, seleziona Abilita l'accesso all'agente** **AI.** Scegli **Next (Successivo)**.
1. Nella pagina **Abilita lo storage** (passaggio 2 di 4), abilita facoltativamente **le cartelle Home** per consentire al tuo agente di salvare i file in un bucket Amazon S3 del tuo account. AWS La flotta associata a questo stack deve consentire l'accesso ad Amazon S3 tramite Internet o un endpoint Amazon VPC per Amazon S3. Scegli **Next (Successivo)**.
1. Nella pagina **Modifica delle impostazioni dell'agente** (passaggio 3 di 4), configura quanto segue:
+ **Abilita l'input dal computer**: consenti agli agenti di scegliere i pulsanti, inserire il testo e scorrere sul desktop. Se si abilita l'input da computer, è necessario abilitare anche la visione artificiale.
+ **Abilita la visione artificiale**: consenti agli agenti di vedere il desktop.
+ **Archiviazione delle schermate**: configura dove vengono archiviate le schermate degli agenti durante le sessioni di streaming. Se abilitato, fornisci un bucket Amazon S3 su cui disponi delle autorizzazioni di scrittura.
+ **Risoluzione dello schermo**: seleziona la risoluzione dello schermo per l'ambiente di streaming dell'agente (1280x720).
+ **Tipo di immagine dello schermo**: seleziona il formato di immagine per le schermate dell'agente (PNG o JPEG).
+ **Persistenza delle impostazioni dell'applicazione**: abilita facoltativamente questa opzione per salvare le personalizzazioni delle applicazioni dell'agente e le impostazioni di Windows tra le sessioni. Le impostazioni vengono salvate in un bucket Amazon S3 nel tuo account. AWS
+ **Abilita l'inoltro degli strumenti MCP**: consenti agli agenti di interagire con le applicazioni e il sistema operativo desktop tramite chiamate MCP dirette anziché utilizzare strumenti di utilizzo del computer. Se abilitati, gli strumenti MCP configurati nella sessione dell' WorkSpaces applicazione vengono inoltrati all'agente.
+ **Abilita la modalità di controllo utente**: consente agli utenti di osservare le sessioni degli agenti in tempo reale tramite il proprio browser. Gli osservatori vedono una visualizzazione dal vivo del desktop mentre l'agente lavora. In modalità VIEW\_STOP, gli osservatori possono fermare l'agente utilizzando un pulsante nella parte superiore dello schermo. Una volta interrotto, l'agente deve iniziare una nuova sessione per riprenderla.
**Nota**
È necessario abilitare almeno uno degli input o della visione artificiale.
Scegli **Next (Successivo)**.
1. Nella pagina **Revisione e creazione** (passaggio 4 di 4), rivedi le impostazioni e scegli **Create Stack**.
### Utilizzo di AWS CLI
Esegui il comando seguente per creare uno stack con accesso agente abilitato:
```
aws appstream create-stack \
--name {{your-stack-name}} \
--agent-access-config '{
"Settings": [
{"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
{"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"},
{"AgentAction": "FORWARD_MCP_TOOLS", "Permission": "ENABLED"}
],
"ScreenResolution": "W_1280xH_720",
"ScreenImageFormat": "PNG"
}'
```
Per abilitare anche l'archiviazione degli screenshot, aggiungi i parametri `S3BucketArn` and`ScreenshotsUploadEnabled`:
```
aws appstream create-stack \
--name {{your-stack-name}} \
--agent-access-config '{
"Settings": [
{"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
{"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"},
{"AgentAction": "FORWARD_MCP_TOOLS", "Permission": "ENABLED"}
],
"ScreenResolution": "W_1280xH_720",
"ScreenImageFormat": "PNG",
"S3BucketArn": "{{arn:aws:s3:::your-bucket-name}}",
"ScreenshotsUploadEnabled": true
}'
```
Dopo aver creato lo stack, associalo a una flotta. Gli agenti non possono connettersi a uno stack a cui non è associata una flotta.
```
aws appstream associate-fleet \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}}
```
## Fase 2: Generazione di un URL di streaming
Crea un URL di streaming utilizzando l'`CreateStreamingURL`API WorkSpaces Applications standard. Non sono necessari parametri specifici per l'agente. La configurazione di accesso agli agenti dello stack determina il comportamento specifico dell'agente.
### Utilizzo di AWS Console di gestione
**Per generare un URL di streaming utilizzando la console**
1. Apri la [console WorkSpaces Applicazioni](https://console.aws.amazon.com/appstream2/home).
1. Nel riquadro di navigazione a sinistra, scegli **Stacks**, quindi scegli lo stack che hai creato con l'accesso agente abilitato.
1. Scegli il pulsante **Azioni** e, nel menu a discesa, seleziona **Crea** URL di streaming. Il tuo stack deve essere selezionato affinché questa opzione sia disponibile.
1. Nella sezione **UserID**, inserisci un utente. Puoi entrare `TestUser` se stai testando.
1. Nella sezione **Scadenza dell'URL**, seleziona l'ora in cui desideri che l'URL sia valido. Si consiglia un periodo di tempo più breve. 30 minuti è l'impostazione predefinita e consigliata per il test.
1. Scegli **getURL** e copia l'URL generato.
### Utilizzo di AWS CLI
Esegui il seguente comando per generare un URL di streaming:
```
aws appstream create-streaming-url \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}} \
--user-id {{your-agent-id}} \
--validity 3600
```
La risposta include un `StreamingURL` messaggio che trasmetterai al tuo agente nel passaggio successivo. L'URL è valido per la durata specificata dal `--validity` parametro.
## Fase 3: Collega il tuo agente al servizio MCP
L'agente si connette al servizio MCP gestito al seguente endpoint fisso:
`https://agentaccess-mcp.{{region}}.api.aws/mcp`
La connessione utilizza la firma SigV4 con il nome del servizio. `agentaccess-mcp` L'agente firma ogni richiesta utilizzando le AWS credenziali configurate nei prerequisiti con le autorizzazioni. `agentaccess-mcp:*` L'URL di streaming dello Step 2 viene passato come intestazione per ogni richiesta MCP.
L'esempio seguente mostra come stabilire la connessione utilizzando mcp-proxy-for-aws:
```
aws_iam_streamablehttp_client(
endpoint="https://agentaccess-mcp.{{region}}.api.aws/mcp",
aws_service="agentaccess-mcp",
aws_region="{{region}}",
headers={
"X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
},
)
```
Dopo la connessione, l'agente può utilizzare gli strumenti MCP per inserire testo, scegliere i pulsanti e acquisire schermate del desktop.
## Fase 4: Verifica dell'attività dell'agente
È possibile verificare l'attività dell'agente utilizzando i seguenti AWS servizi:
+ **AWS CloudTrail**— AWS CloudTrail registra gli eventi della sessione dell'agente. Apri la AWS CloudTrail console per visualizzare l'attività dell'agente.
+ **CloudWatch**— CloudWatch fornisce metriche operative per le sessioni degli agenti. Apri la CloudWatch console per visualizzare le metriche.
+ **Amazon S3**: se hai abilitato l'archiviazione degli screenshot, Amazon S3 archivia gli screenshot nel bucket specificato durante la configurazione dello stack.
## Fase 5: eliminazione delle risorse
Per evitare addebiti continui, elimina lo stack che hai creato in questo tutorial. Devi fermare la flotta e dissociarla dalla pila prima di poter eliminare la pila. Facoltativamente, puoi anche eliminare la flotta.
### Utilizzo di AWS Console di gestione
**Per eliminare le risorse**
1. Apri la [console WorkSpaces delle applicazioni](https://console.aws.amazon.com/appstream2/home).
1. Nel riquadro di navigazione a sinistra selezionare **Fleets (Parchi istanze)**.
1. Seleziona la flotta associata allo stack. Scegliere **Actions (Operazioni)**, **Stop (Arresta)**. Attendi che la flotta si fermi.
1. Nel riquadro di navigazione a sinistra, selezionare **Stacks (Stack)**.
1. Seleziona lo stack che hai creato e scegli **Azioni**, **Dissocia flotta**.
1. **Con lo stack ancora selezionato, scegli **Azioni**, Elimina.**
1. (Facoltativo) Per eliminare la flotta, nel riquadro di navigazione a sinistra, scegli **Flotte**. Seleziona la flotta e scegli **Azioni**, **Elimina**.
### Utilizzo di AWS CLI
Esegui i seguenti comandi per ripulire le risorse:
```
aws appstream stop-fleet \
--name {{your-fleet-name}}
aws appstream disassociate-fleet \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}}
aws appstream delete-stack \
--name {{your-stack-name}}
```
(Facoltativo) Per eliminare il parco veicoli anche dopo che si è fermato:
```
aws appstream delete-fleet \
--name {{your-fleet-name}}
```