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à. # WorkSpaces Applicazioni (server MCP) Il server WorkSpaces Applications MCP è un servizio completamente gestito che fornisce agli agenti AI strumenti MCP (Model Context Protocol) per interagire con le applicazioni desktop durante le sessioni di streaming. Gli agenti possono fare clic sui pulsanti, inserire testo, scorrere e acquisire schermate del desktop. ## Panoramica di Quando si abilita l'accesso degli agenti su uno stack, gli agenti possono connettersi al server MCP gestito per interagire con le applicazioni desktop. Il server MCP gestisce la comunicazione tra l'agente e la sessione di streaming. L'agente invia le richieste di strumenti MCP e il server le esegue sul desktop. Il server MCP è ospitato nel cloud. AWS Non è necessario installare o mantenere alcun componente del server. Il server utilizza Streamable HTTP come protocollo di trasporto. L'accesso agli agenti supporta sia le flotte non aggiunte al dominio che quelle aggiunte al dominio. Il metodo di connessione varia in base al tipo di parco veicoli. Non-domain-joined le flotte autenticano la sessione con un URL di streaming, mentre le flotte aggiunte al dominio si autenticano tramite la federazione SAML. Per il percorso che corrisponde alla tua flotta, consulta. [Connessione al server MCP](#agent-access-mcp-server-endpoint) ## Connessione al server MCP Gli agenti si connettono al server MCP sul seguente dispositivo: ``` https://agentaccess-mcp.{{region}}.api.aws/mcp ``` Il server MCP è ospitato nel AWS cloud e utilizza Streamable HTTP come protocollo di trasporto. Non è necessario installare o mantenere alcun componente del server. Ogni richiesta deve SigV4-signed utilizzare credenziali IAM con il nome `agentaccess-mcp` del servizio. Il seguente esempio di Python mostra lo schema di connessione generale utilizzando: `mcp-proxy-for-aws` ``` from mcp_proxy_for_aws import aws_iam_streamablehttp_client async with aws_iam_streamablehttp_client( endpoint="https://agentaccess-mcp.{{region}}.api.aws/mcp", aws_service="agentaccess-mcp", aws_region="{{region}}", headers={ # Fleet-type-specific headers (see the following subsections) }, metadata={ # Fleet-type-specific metadata (see the following subsections) }, ) as (read, write, _): # Use read/write streams with your MCP client ... ``` Per altri linguaggi, scrivete la vostra logica di firma SigV4 per le richieste MCP in uscita o utilizzate una libreria che supporti la firma SigV4. [Per ulteriori informazioni su, consulta mcp-proxy-for-aws on. `mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws) GitHub Il modo in cui autentichi la sessione di streaming dipende dal tipo di flotta: + **Non-domain-joined flotte**: passa un URL di streaming come intestazione. Per informazioni, consulta [Connessione con flotte non aggiunte al dominio](#agent-access-mcp-server-connect-ndj). + **Domain-joined flotte**: passa un'asserzione SAML firmata come metadati. Per informazioni, consulta [Connessione con flotte aggiunte a un dominio](#agent-access-mcp-server-connect-dj). **Nota** In un dato momento, solo un agente può connettersi a una sessione unica. Gli utenti denominati, specificati tramite il `UserId` parametro, possono avere solo una sessione attiva per flotta alla volta. Per eseguire più agenti contemporaneamente, ogni agente deve connettersi alla propria sessione unica. ### Connessione con flotte non aggiunte al dominio Per le flotte non aggiunte a un dominio, genera un URL di streaming utilizzando l'`CreateStreamingURL`API e passalo come intestazione per ogni richiesta. `X-Amzn-AgentAccess-Streaming-Session-Url` Non sono richiesti parametri specifici per l'agente. Il comportamento dell'agente è determinato dalla configurazione di accesso dell'agente dello stack. ``` import boto3 from mcp_proxy_for_aws import aws_iam_streamablehttp_client # Generate streaming URL appstream = boto3.client("appstream", region_name="{{region}}") response = appstream.create_streaming_url( StackName="{{stack-name}}", FleetName="{{fleet-name}}", UserId="{{user-id}}", ) streaming_url = response["StreamingURL"] # Connect to MCP server async with 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, }, ) as (read, write, _): ... ``` Per ulteriori informazioni sull'`CreateStreamingURL`API, consulta [CreateStreamingl'URL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) nell'*Amazon WorkSpaces Applications 2.0 API Reference*. ### Connessione con flotte aggiunte a un dominio Quando gli agenti accedono a istanze di streaming aggiunte al dominio, la connessione deve essere federata tramite un provider SAML. Questo requisito si applica sia alle sessioni tradizionali che a quelle con agenti. Per le sessioni con gli agenti, [Certificate-Based Autenticazione](certificate-based-authentication.md) è obbligatorio. Poiché le istanze di streaming aggiunte al dominio richiedono l'accesso tramite SAML, il client MCP deve fornire un'asserzione SAML firmata anziché un URL di streaming. Le asserzioni SAML codificate superano i limiti di dimensione dell'intestazione HTTP. Per evitare ciò, usa il campo in: `metadata` `mcp-proxy-for-aws` ``` from mcp_proxy_for_aws import aws_iam_streamablehttp_client # saml_response: your signed, base64-encoded SAML assertion # stack_arn: the ARN of the AppStream stack for the AD user async with aws_iam_streamablehttp_client( endpoint="https://agentaccess-mcp.{{region}}.api.aws/mcp", aws_service="agentaccess-mcp", aws_region="{{region}}", metadata={ "saml_response": saml_response, "stack_arn": stack_arn, }, ) as (read, write, _): ... ``` **Nota** Il `metadata` parametro è stato aggiunto nella `mcp-proxy-for-aws` versione 1.6.1. Le versioni precedenti non possono inserire il `_meta` campo senza ulteriore sviluppo. Per eseguire l'aggiornamento, esegui`pip install -U mcp-proxy-for-aws`. Per ulteriori informazioni sulla configurazione della federazione SAML con WorkSpaces Applications, consulta [Configurazione SAML](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html) nella *Amazon WorkSpaces Applications Administration Guide*. Per ulteriori informazioni e un esempio di funzionamento completo, consulta il repository [sample-code-for-workspaces-agent-access in Samples](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) on. AWS GitHub ## Modalità di connessione Puoi controllare il modo in cui l'agente attende che la sessione desktop diventi disponibile impostando l'`X-Amzn-AgentAccess-Connect-Mode`intestazione sulle tue richieste MCP. **Nota** Le modalità di connessione si applicano sia alle flotte non aggiunte al dominio che a quelle aggiunte al dominio. Imposta l'`X-Amzn-AgentAccess-Connect-Mode`intestazione in base al meccanismo di autenticazione utilizzato dal tipo di flotta (l'intestazione Streaming-URL per le flotte non aggiunte al dominio o i metadati delle asserzioni SAML per le flotte aggiunte al dominio). Sono disponibili le seguenti modalità: + **BLOCCO** (impostazione predefinita): il server MCP attende che la connessione al desktop sia completamente stabilita prima di rispondere. Al momento della `tools/list` restituzione, tutti gli strumenti sono immediatamente disponibili. + **SONDAGGIO** — Il server MCP risponde immediatamente senza attendere la connessione al desktop. Inizialmente, è disponibile solo lo `connection_status` strumento. L'agente interroga questo strumento fino a quando non viene stabilita la connessione, dopodiché diventa disponibile l'intero set di strumenti. Usa la modalità POLLING quando desideri che il tuo agente esegua altre operazioni in attesa della connessione al desktop o quando hai bisogno di un maggiore controllo sul comportamento di timeout della connessione. L'esempio seguente mostra come utilizzare la modalità POLLING: ``` # Pass the header when creating the MCP connection headers = { "X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url, # non-domain-joined fleets "X-Amzn-AgentAccess-Connect-Mode": "POLLING", } # After initialize, tools/list returns immediately with connection_status tools = await session.list_tools() # tools = [connection_status] # Poll connection_status until the desktop is ready while True: result = await session.call_tool("connection_status", {}) status = json.loads(result.content[0].text) if status["state"] == "CONNECTED": break time.sleep(2) # Now tools/list returns the full set (screenshot, left_click, type_text, etc.) tools = await session.list_tools() ``` ## Pulizia della sessione Puoi controllare se la sessione di streaming è scaduta quando l'agente termina la connessione impostando l'`X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete`intestazione sulle tue richieste MCP. Sono disponibili i seguenti valori: + **true**: quando l'agente invia una `DELETE` richiesta HTTP esplicita, il server MCP fa scadere la sessione di streaming delle WorkSpaces applicazioni come parte della pulizia. La scadenza della sessione termina l'istanza di streaming sottostante e attiva la politica di scalabilità automatica configurata dalla flotta. Per ulteriori informazioni, consulta [Auto Scaling della flotta per applicazioni Amazon WorkSpaces](autoscaling.md). + **false** (impostazione predefinita): la sessione di streaming continua a funzionare fino al raggiungimento del timeout di disconnessione. Per ulteriori informazioni sul timeout di disconnessione, consulta. [Crea una flotta nelle WorkSpaces applicazioni Amazon](set-up-stacks-fleets-create.md) **Nota** Per impostazione predefinita, un client `mcp-proxy-for-aws` MCP gestisce automaticamente la `DELETE` richiesta quando si termina correttamente il ciclo di vita del client. ## Strumenti disponibili Il server MCP fornisce i seguenti strumenti per consentire agli agenti di interagire con il desktop durante una sessione di streaming. Tutti i nomi degli strumenti utilizzano il `agentaccess___` prefisso. ### Strumenti del mouse `left_click` Esegui un clic sinistro sulle coordinate fornite. Parametri: `x` (richiesto), `y` (obbligatorio), `modifiers` (opzionale, ad esempio `ctrl` o`ctrl+shift`). `double_click` Effettua un doppio clic sulle coordinate fornite. Parametri: `x` `y` (obbligatorio), `modifiers` (opzionale). `triple_click` Esegui un triplo clic sulle coordinate fornite. Parametri: `x` `y` (obbligatorio), `modifiers` (opzionale). `right_click` Esegui un clic con il pulsante destro del mouse sulle coordinate fornite. Parametri: `x` `y` (obbligatorio), `modifiers` (opzionale). `middle_click` Esegui un clic centrale sulle coordinate fornite. Parametri: `x` `y` (obbligatorio), `modifiers` (opzionale). `left_click_drag` Esegui un clic con il pulsante sinistro del mouse e trascina dalle coordinate iniziali alle coordinate finali. Parametri: `start_x` (richiesto), `start_y` (obbligatorio), `end_x` (obbligatorio), `end_y` (obbligatorio). `left_mouse_down` Tieni premuto il pulsante sinistro del mouse sulle coordinate indicate. Parametri: `x` (richiesto), `y` (obbligatorio), `modifiers` (opzionale). `left_mouse_up` Rilascia il pulsante sinistro del mouse sulle coordinate indicate. Parametri: `x` (richiesto), `y` (obbligatorio), `modifiers` (opzionale). `move_pointer` Sposta il puntatore sulle coordinate indicate. Parametri: `x` (richiesto), `y` (obbligatorio). `scroll` Scorri la rotellina del mouse in base alle coordinate indicate. Parametri: `x` (obbligatorio), `y` (obbligatorio —,,, o`Right`) `Up` `Down``Left`, `scroll_direction` (obbligatorio: nelle zecche, dove 120 segni di spunta equivalgono a una tacca della ruota), `scroll_amount` (opzionale). `modifiers` ### Strumenti da tastiera `type_text` Digita il testo simulando gli eventi della tastiera per ogni personaggio. Parametri: `text` (obbligatorio: fino a 10.000 caratteri). `key` Premere un tasto o una combinazione di tasti. Parametri: `keys` (obbligatorio: un singolo tasto o combinazione unita`+`, ad esempio `a``ctrl+c`, da o`ctrl+shift+s`). `hold_key` Tieni premuto un tasto o una combinazione di tasti per una durata specificata. Parametri: `keys` (obbligatorio), `duration` (obbligatorio: da 1 a 30 secondi). ### Strumenti dello schermo `screenshot` Cattura uno screenshot del desktop. Le dimensioni dell'immagine restituita definiscono lo spazio delle coordinate per tutti gli strumenti del mouse. Parametri: `include_cursor` (opzionale, il valore predefinito è). `false` ## Inoltro di strumenti MCP L'inoltro degli strumenti MCP consente agli agenti di interagire con le applicazioni e il sistema operativo desktop tramite chiamate MCP dirette anziché utilizzare strumenti informatici. Quando abilitate l'inoltro degli strumenti, il server MCP inoltra gli strumenti configurati nella sessione dell'applicazione all'agente. WorkSpaces ### Configurazione dell'inoltro degli strumenti Per configurare l'inoltro degli strumenti MCP: 1. **Abilita l'inoltro degli strumenti**: attiva l'azione dell'`FORWARD_MCP_TOOLS`agente tramite l'API o le impostazioni della console. 1. **Verifica che il file di configurazione del server MCP sia presente**: il servizio cerca un file di configurazione nel seguente percorso: ``` C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json ``` 1. **Configura il server MCP sull' WorkSpaceimmagine: il** file di configurazione è JSON con un unico oggetto di primo livello. `mcpServers` Ogni chiave è un nome univoco che scegli per un server. Ogni valore specifica come avviare quel server. ``` { "mcpServers": { "filesystem": { "command": "C:/path/to/python.exe", "args": ["C:/mcpServerPath/filesystem.py", "C:/UserName/Documents"] }, "weather": { "command": "C:/Program Files/my-mcp/weather.exe" } } } ``` [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/appstream2/latest/developerguide/agent-access-mcp-server.html) 1. **Verifica della disponibilità dello strumento**: se il file di configurazione è presente, il servizio si connette ai server MCP configurati nel file e inoltra gli strumenti. Gli strumenti inoltrati vengono visualizzati quando l'agente elenca gli strumenti disponibili. **Nota** Affinché l'inoltro degli strumenti funzioni, è necessario abilitare sia l'accesso IAM che l'impostazione del servizio. Le autorizzazioni IAM non sostituiscono l'impostazione del servizio. ### Considerazioni sull'inoltro degli strumenti MCP Tenete presenti le seguenti considerazioni quando configurate l'inoltro degli strumenti MCP: + **Il trasporto è solo standard I/O (stdio).** Ogni voce deve avviare un processo che parli in modo MCP rispetto ai suoi input e output standard. Gli endpoint HTTP o SSE MCP remoti non sono supportati. Per utilizzare un endpoint remoto, inseriscilo in un server stdio locale. + **Sono supportati solo `command` e `args` 3.** Non esiste un campo per le variabili di ambiente o la directory di lavoro. Ogni server eredita l'ambiente della sessione di streaming e viene eseguito come utente della sessione. Usa percorsi assoluti per `command` e per qualsiasi argomento del percorso. + **Utilizzate le barre nei percorsi** (ad esempio,`C:/Program Files/my-mcp/server.exe`). JSON considera la barra rovesciata come un carattere di escape, quindi un Windows-style percorso scritto con barre rovesciate singole non è valido. Windows accetta barre direzionali per i percorsi assoluti, il che evita la necessità di uscire da ogni separatore come. `\\` + **Tool-call timeout.** Ogni chiamata all'utensile inoltrata deve essere completata entro 5 secondi. Il server MCP annulla le chiamate che richiedono più tempo e restituisce un errore all'agente. Progetta strumenti inoltrati per restituirli rapidamente. ### Come appaiono gli strumenti inoltrati all'agente Per evitare collisioni tra i server, il server MCP rinomina ogni strumento inoltrato nell'elenco degli strumenti dell'agente utilizzando lo schema seguente: ``` forwarded___{{server-name}}___{{original-tool-name}} ``` {{server-name}}Questa è la chiave del file di configurazione. Ad esempio, uno `get_forecast` strumento del `weather` server è elencato come`forwarded___weather___get_forecast`. Quando l'agente chiama il nome inoltrato, il server MCP indirizza la richiesta allo strumento originale sul server proprietario. Il codice dell'agente che corrisponde ai nomi degli strumenti deve prevedere questo prefisso. ### Autorizzazioni IAM per l'inoltro degli strumenti L'azione IAM per richiamare gli strumenti inoltrati è. `CallForwardedTool` Puoi definire l'accesso a stack specifici utilizzando la `StackArn` chiave condition: ``` { "Action": "agentaccess-mcp:*", "Resource": "*", "Condition": { "ArnLike": { "agentaccess-mcp:StackArn": "arn:aws:appstream:{{region}}:{{account-id}}:stack/{{stack-name}}" } } } ``` ## Framework compatibili È possibile connettersi al server MCP delle WorkSpaces applicazioni da qualsiasi framework di MCP-compatible agenti che supporti la firma Streamable HTTP e SigV4. Sono stati testati i seguenti framework: + [Strands Agents SDK: fornisce supporto](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) client MCP nativo. + [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — Un trasporto leggero che gestisce la firma SigV4 per le richieste MCP in Python. ## Monitoraggio È possibile monitorare l'attività degli agenti tramite i seguenti servizi: + **AWS CloudTrail**— Gli eventi della sessione dell'agente vengono registrati. CloudTrail È possibile visualizzare quando gli agenti si connettono, quali strumenti utilizzano e quando terminano le sessioni. Le chiamate agli strumenti sono eventi relativi ai dati e richiedono la configurazione di un percorso per registrare gli eventi relativi ai dati. Per ulteriori informazioni, consultare [Registrazione di eventi di dati](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) nella *Guida per l'utente di CloudTrail *. + **CloudWatch**— Le metriche operative per le sessioni degli agenti sono disponibili in CloudWatch. + **Amazon S3**: se configuri l'archiviazione degli screenshot, gli screenshot acquisiti durante le sessioni degli agenti sono disponibili nel bucket Amazon S3 specificato. Le schermate vengono archiviate con il seguente formato chiave: ``` agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png ``` L'UUID nel percorso è l'ID della sessione di streaming delle WorkSpaces applicazioni. ## Nozioni di base Per iniziare a usare il server MCP delle WorkSpaces applicazioni, consulta. [Inizia a fornire agli agenti l'accesso alle applicazioni WorkSpaces](getting-started-agent-access.md)