Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # WorkSpaces Serveur MCP pour applications Le serveur WorkSpaces Applications MCP est un service entièrement géré qui fournit aux agents d'intelligence artificielle des outils MCP (Model Context Protocol) pour interagir avec les applications de bureau pendant les sessions de streaming. Les agents peuvent cliquer sur des boutons, saisir du texte, faire défiler l'écran et prendre des captures d'écran du bureau. ## Présentation de Lorsque vous activez l'accès des agents sur une pile, les agents peuvent se connecter au serveur MCP géré pour interagir avec les applications de bureau. Le serveur MCP gère la communication entre votre agent et la session de streaming. Votre agent envoie des demandes d'outil MCP et le serveur les exécute sur le poste de travail. Le serveur MCP est hébergé dans le AWS cloud. Il n'est pas nécessaire d'installer ou de gérer les composants du serveur. Le serveur utilise Streamable HTTP comme protocole de transport. L'accès aux agents prend en charge à la fois les flottes non jointes à un domaine et les flottes jointes à un domaine. La méthode de connexion varie selon le type de flotte. Non-domain-joined les flottes authentifient la session à l'aide d'une URL de streaming, tandis que les flottes jointes à un domaine s'authentifient via la fédération SAML. Pour le trajet correspondant à votre flotte, voir[Connexion au serveur MCP](#agent-access-mcp-server-endpoint). ## Connexion au serveur MCP Les agents se connectent au serveur MCP au point de terminaison suivant : ``` https://agentaccess-mcp.{{region}}.api.aws/mcp ``` Le serveur MCP est hébergé dans le AWS cloud et utilise Streamable HTTP comme protocole de transport. Il n'est pas nécessaire d'installer ou de gérer les composants du serveur. Chaque demande doit SigV4-signed utiliser les informations d'identification IAM associées au nom `agentaccess-mcp` du service. L'exemple Python suivant montre le modèle de connexion général en utilisant `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 ... ``` Pour les autres langages, écrivez votre propre logique de signature Sigv4 pour les requêtes MCP sortantes ou utilisez une bibliothèque qui prend en charge la signature Sigv4. Pour plus d'informations sur`mcp-proxy-for-aws`, consultez [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) sur. GitHub La manière dont vous authentifiez la session de streaming dépend du type de flotte : + **Non-domain-joined flottes** — Transmettez une URL de diffusion en tant qu'en-tête. Consultez [Connexion avec des flottes n'appartenant pas à un domaine](#agent-access-mcp-server-connect-ndj). + **Domain-joined flottes** — Transmettez une assertion SAML signée sous forme de métadonnées. Consultez [Connexion avec des flottes jointes à un domaine](#agent-access-mcp-server-connect-dj). ### Connexion avec des flottes n'appartenant pas à un domaine Pour les flottes n'appartenant pas à un domaine, générez une URL de streaming à l'aide de l'`CreateStreamingURL`API et transmettez-la comme `X-Amzn-AgentAccess-Streaming-Session-Url` en-tête de chaque demande. Aucun paramètre spécifique à l'agent n'est requis. Le comportement de l'agent est déterminé par la configuration d'accès aux agents de la pile. ``` 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, _): ... ``` Pour plus d'informations sur l'`CreateStreamingURL`API, consultez [CreateStreamingl'URL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) dans le manuel *Amazon WorkSpaces Applications 2.0 API Reference*. ### Connexion avec des flottes jointes à un domaine Lorsque les agents accèdent à des instances de streaming jointes à un domaine, la connexion doit être fédérée via un fournisseur SAML. Cette exigence s'applique à la fois aux sessions standard et aux sessions d'agent. Les sessions standard permettent aux utilisateurs de saisir leur mot de passe manuellement ou d'utiliser l'authentification basée sur des certificats pour une expérience de connexion fluide. Pour les sessions d'agent, une authentification basée sur des certificats est requise. Étant donné que les instances de streaming jointes à un domaine nécessitent un accès via SAML, votre client MCP doit fournir une assertion SAML signée au lieu d'une URL de streaming. Les assertions SAML codées dépassent les limites de taille des en-têtes HTTP. Pour éviter cela, utilisez le `metadata` champ dans `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, _): ... ``` **Note** Le `metadata` paramètre a été ajouté dans la `mcp-proxy-for-aws` version 1.6.1. Les versions antérieures ne peuvent pas injecter le `_meta` champ sans développement supplémentaire. Pour effectuer la mise à niveau, exécutez`pip install -U mcp-proxy-for-aws`. Pour plus d'informations sur la configuration de la fédération SAML avec WorkSpaces les applications, consultez la section [Configuration de SAML](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html) dans le guide d'*administration d'Amazon WorkSpaces Applications*. Pour plus d'informations et un exemple de fonctionnement complet, consultez le référentiel [sample-code-for-workspaces-agent-access dans Samples](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) on. AWS GitHub ## Modes de connexion Vous pouvez contrôler la façon dont votre agent attend que la session de bureau soit disponible en définissant l'`X-Amzn-AgentAccess-Connect-Mode`en-tête de vos demandes MCP. **Note** Les modes de connexion s'appliquent à la fois aux flottes non jointes à un domaine et aux flottes jointes à un domaine. Définissez l'`X-Amzn-AgentAccess-Connect-Mode`en-tête à côté du mécanisme d'authentification utilisé par votre type de flotte (l'en-tête Streaming-URL pour les flottes non jointes à un domaine, ou les métadonnées d'assertion SAML pour les flottes jointes à un domaine). Les modes suivants sont disponibles : + **BLOCAGE** (par défaut) — Le serveur MCP attend que la connexion au bureau soit complètement établie avant de répondre. Lors des `tools/list` retours, tous les outils sont immédiatement disponibles. + **SONDAGE** — Le serveur MCP répond immédiatement sans attendre la connexion au bureau. Dans un premier temps, seul l'`connection_status`outil est disponible. Votre agent interroge cet outil jusqu'à ce que la connexion soit établie, date à laquelle l'ensemble complet d'outils devient disponible. Utilisez le mode POLLING lorsque vous souhaitez que votre agent effectue d'autres tâches en attendant la connexion au poste de travail ou lorsque vous avez besoin de mieux contrôler le comportement en cas d'expiration de la connexion. L'exemple suivant montre comment utiliser le mode 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() ``` ## Nettoyage de session Vous pouvez contrôler si la session de streaming expire lorsque votre agent met fin à sa connexion en définissant l'`X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete`en-tête de vos demandes MCP. Les valeurs disponibles sont les suivantes : + **true** — Lorsque votre agent envoie une `DELETE` requête HTTP explicite, le serveur MCP fait expirer la session de streaming d' WorkSpaces applications dans le cadre du nettoyage. L'expiration de la session met fin à l'instance de streaming sous-jacente et déclenche la politique de dimensionnement automatique configurée pour le parc. Pour de plus amples informations, veuillez consulter [Fleet Auto Scaling pour les WorkSpaces applications Amazon](autoscaling.md). + **false** (par défaut) — La session de streaming continue de fonctionner jusqu'à ce que le délai de déconnexion soit atteint. Pour plus d'informations sur le délai de déconnexion, consultez[Création d'une flotte dans Amazon WorkSpaces Applications](set-up-stacks-fleets-create.md). **Note** Par défaut, un client `mcp-proxy-for-aws` MCP gère automatiquement la `DELETE` demande lorsque vous terminez correctement le cycle de vie du client. ## Outils disponibles Le serveur MCP fournit les outils suivants permettant aux agents d'interagir avec le bureau pendant une session de streaming. Tous les noms d'outils utilisent le `agentaccess___` préfixe. ### Outils pour souris `left_click` Effectuez un clic gauche sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif, par exemple `ctrl` ou`ctrl+shift`). `double_click` Effectuez un double clic sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `triple_click` Effectuez un triple clic sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `right_click` Effectuez un clic droit sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `middle_click` Effectuez un clic central sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `left_click_drag` Effectuez un clic gauche pour faire glisser les coordonnées de départ vers les coordonnées de fin. Paramètres : `start_x` (obligatoire), `start_y` (obligatoire), `end_x` (obligatoire), `end_y` (obligatoire). `left_mouse_down` Appuyez sur le bouton gauche de la souris et maintenez-le enfoncé aux coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `left_mouse_up` Relâchez le bouton gauche de la souris aux coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `modifiers` (facultatif). `move_pointer` Déplacez le pointeur sur les coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire). `scroll` Faites défiler la molette de la souris aux coordonnées indiquées. Paramètres : `x` (obligatoire), `y` (obligatoire), `scroll_direction` (obligatoire —`Up`,`Down`, ou`Right`)`Left`, `scroll_amount` (obligatoire — en ticks, où 120 ticks équivalent à un cran de roue), `modifiers` (facultatif). ### Outils de clavier `type_text` Tapez du texte en simulant les événements du clavier pour chaque caractère. Paramètres : `text` (obligatoire — jusqu'à 10 000 caractères). `key` Appuyez sur une touche ou une combinaison de touches. Paramètres : `keys` (obligatoire : une seule touche ou combinaison jointe par`+`, par exemple `a``ctrl+c`, ou`ctrl+shift+s`). `hold_key` Maintenez une touche ou une combinaison de touches enfoncée pendant une durée spécifiée. Paramètres : `keys` (obligatoire), `duration` (obligatoire — 1 à 30 secondes). ### Outils d'écran `screenshot` Capturez une capture d'écran du bureau. Les dimensions de l'image renvoyée définissent l'espace de coordonnées de tous les outils de la souris. Paramètres : `include_cursor` (facultatif, la valeur par défaut est`false`). ## Transfert d'outils MCP Le transfert d'outils MCP permet aux agents d'interagir avec les applications et le système d'exploitation du bureau par le biais d'appels MCP directs plutôt que d'utiliser des outils informatiques. Lorsque vous activez le transfert d'outils, le serveur MCP transmet les outils configurés lors de la session WorkSpaces d'application à votre agent. ### Configuration du transfert d'outils Pour configurer le transfert d'outils MCP : 1. **Activer le transfert d'outils** : activez l'action de l'`FORWARD_MCP_TOOLS`agent via les paramètres de l'API ou de la console. 1. **Configurez le serveur MCP sur le WorkSpace** — Le service recherche un fichier de configuration au chemin suivant : ``` C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json ``` 1. **Vérifier la disponibilité de l'outil** : si le fichier de configuration est présent, le service se connecte aux serveurs MCP configurés dans le fichier et transmet les outils. Les outils transférés apparaissent lorsque l'agent répertorie les outils disponibles. **Note** L'accès IAM et le paramètre de service doivent être activés pour que le transfert d'outils fonctionne. Les autorisations IAM ne remplacent pas le paramètre du service. ### Autorisations IAM pour le transfert d'outils L'action IAM pour appeler les outils transférés est`CallForwardedTool`. Vous pouvez définir l'accès à des piles spécifiques à l'aide de la clé de `StackArn` condition : ``` { "Action": "agentaccess-mcp:*", "Resource": "*", "Condition": { "ArnLike": { "ponte-mcp:StackArn": "arn:aws:appstream:{{region}}:{{account-id}}:stack/{{stack-name}}" } } } ``` ## Frameworks compatibles Vous pouvez vous connecter au serveur WorkSpaces Applications MCP à partir de n'importe quel framework d' MCP-compatible agents prenant en charge la signature HTTP et SigV4 streamable. Les frameworks suivants ont été testés : + [SDK Strands Agents](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) — Fournit un support client MCP natif. + [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — Transport léger qui gère la signature SigV4 pour les requêtes MCP en Python. ## Contrôle Vous pouvez surveiller l'activité des agents par le biais des services suivants : + **AWS CloudTrail**— Les événements de session de l'agent sont enregistrés CloudTrail. Vous pouvez voir quand les agents se connectent, quels outils ils utilisent et quand les sessions se terminent. Les appels d'outils sont des événements liés aux données et nécessitent que vous établissiez un suivi pour enregistrer les événements liés aux données. Pour plus d’informations, consultez [Journalisation des événements de données](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) dans le *Guide de l’utilisateur CloudTrail *. + **CloudWatch**— Les métriques opérationnelles pour les sessions des agents sont disponibles dans CloudWatch. + **Amazon S3** — Si vous configurez le stockage des captures d'écran, les captures d'écran capturées pendant les sessions de l'agent sont disponibles dans le compartiment Amazon S3 que vous spécifiez. Les captures d'écran sont enregistrées avec le format de clé suivant : ``` agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png ``` L'UUID indiqué dans le chemin est l'ID de session de streaming WorkSpaces des applications. ## Mise en route Pour commencer à utiliser le serveur WorkSpaces Applications MCP, consultez[Commencez à fournir aux agents un accès aux WorkSpaces applications](getting-started-agent-access.md).