As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # WorkSpaces Servidor MCP de aplicativos O servidor WorkSpaces Applications MCP é um serviço totalmente gerenciado que fornece aos agentes de IA ferramentas do Model Context Protocol (MCP) para interagir com aplicativos de desktop durante as sessões de streaming. Os agentes podem clicar em botões, inserir texto, rolar e fazer capturas de tela da área de trabalho. ## Visão geral do Quando você ativa o acesso do agente em uma pilha, os agentes podem se conectar ao servidor MCP gerenciado para interagir com os aplicativos de desktop. O servidor MCP gerencia a comunicação entre seu agente e a sessão de streaming. Seu agente envia solicitações de ferramentas MCP e o servidor as executa no desktop. O servidor MCP está hospedado na AWS nuvem. Você não precisa instalar nem manter nenhum componente do servidor. O servidor usa HTTP Streamable como protocolo de transporte. O acesso do agente oferece suporte a frotas não associadas a um domínio e a frotas associadas a um domínio. O método de conexão difere de acordo com o tipo de frota. Non-domain-joined as frotas autenticam a sessão com uma URL de streaming, enquanto as frotas unidas ao domínio se autenticam por meio da federação SAML. Para o caminho que corresponde à sua frota, consulte[Conectando-se ao servidor MCP](#agent-access-mcp-server-endpoint). ## Conectando-se ao servidor MCP Os agentes se conectam ao servidor MCP no seguinte endpoint: ``` https://agentaccess-mcp.{{region}}.api.aws/mcp ``` O servidor MCP está hospedado na AWS nuvem e usa HTTP Streamable como protocolo de transporte. Você não precisa instalar nem manter nenhum componente do servidor. Cada solicitação deve SigV4-signed usar credenciais do IAM com o nome `agentaccess-mcp` do serviço. O exemplo de Python a seguir mostra o padrão geral de conexão usando: `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 ... ``` Para outras linguagens, escreva sua própria lógica de assinatura SigV4 para solicitações MCP enviadas ou use uma biblioteca que suporte a assinatura SigV4. Para obter mais informações sobre`mcp-proxy-for-aws`, consulte [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) on. GitHub A forma como você autentica a sessão de streaming depende do tipo de sua frota: + **Non-domain-joined frotas** — Passe um URL de streaming como cabeçalho. Consulte [Conexão com frotas não associadas a um domínio](#agent-access-mcp-server-connect-ndj). + **Domain-joined frotas** — Transmita uma declaração SAML assinada como metadados. Consulte [Conectando-se com frotas unidas a um domínio](#agent-access-mcp-server-connect-dj). ### Conexão com frotas não associadas a um domínio Para frotas não associadas a um domínio, gere um URL de streaming usando a `CreateStreamingURL` API e passe-o como cabeçalho em cada solicitação. `X-Amzn-AgentAccess-Streaming-Session-Url` Nenhum parâmetro específico do agente é necessário. O comportamento do agente é determinado pela configuração de acesso do agente da pilha. ``` 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, _): ... ``` Para obter mais informações sobre a `CreateStreamingURL` API, consulte o [CreateStreamingURL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) na *Referência de API do Amazon WorkSpaces Applications 2.0*. ### Conectando-se com frotas unidas a um domínio Quando os agentes acessam instâncias de streaming associadas ao domínio, a conexão deve ser federada por meio de um provedor SAML. Esse requisito se aplica às sessões padrão e de agente. As sessões padrão permitem que os usuários insiram sua senha manualmente ou usem a autenticação baseada em certificado para uma experiência de login perfeita. Para sessões de agentes, a autenticação baseada em certificado é necessária. Como as instâncias de streaming associadas ao domínio exigem acesso por meio do SAML, seu cliente MCP deve fornecer uma declaração SAML assinada em vez de uma URL de streaming. As asserções SAML codificadas excedem os limites de tamanho do cabeçalho HTTP. Para evitar isso, use o `metadata` campo em`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** O `metadata` parâmetro foi adicionado na `mcp-proxy-for-aws` versão 1.6.1. As versões anteriores não podem injetar o `_meta` campo sem desenvolvimento adicional. Para atualizar, execute`pip install -U mcp-proxy-for-aws`. Para obter mais informações sobre como configurar a federação SAML com WorkSpaces aplicativos, consulte [Configurando o SAML](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html) no *Amazon WorkSpaces Applications Administration Guide*. Para obter mais informações e um exemplo prático completo, consulte o repositório [sample-code-for-workspaces-agent-access em Samples](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) on. AWS GitHub ## Modos de conexão Você pode controlar como seu agente espera que a sessão de desktop fique disponível definindo o `X-Amzn-AgentAccess-Connect-Mode` cabeçalho em suas solicitações de MCP. **nota** Os modos de conexão se aplicam tanto a frotas não associadas a um domínio quanto a frotas associadas a um domínio. Defina o `X-Amzn-AgentAccess-Connect-Mode` cabeçalho ao lado de qualquer mecanismo de autenticação que seu tipo de frota usa (o cabeçalho Streaming-URL para frotas não associadas a um domínio ou os metadados de asserção SAML para frotas associadas a domínios). Os seguintes modos estão disponíveis: + **BLOQUEIO** (padrão) — O servidor MCP espera até que a conexão de desktop esteja totalmente estabelecida antes de responder. Quando `tools/list` devolvidas, todas as ferramentas estão imediatamente disponíveis. + **SONDAGEM** — O servidor MCP responde imediatamente sem esperar pela conexão com o desktop. Inicialmente, somente a `connection_status` ferramenta está disponível. Seu agente pesquisa essa ferramenta até que a conexão seja estabelecida, momento em que o conjunto completo de ferramentas fica disponível. Use o modo POLLING quando quiser que seu agente realize outro trabalho enquanto aguarda a conexão com o desktop ou quando precisar de mais controle sobre o comportamento do tempo limite da conexão. O exemplo a seguir mostra como usar o modo 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() ``` ## Limpeza da sessão Você pode controlar se a sessão de streaming expira quando seu agente encerra a conexão definindo o `X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete` cabeçalho em suas solicitações de MCP. Os seguintes valores estão disponíveis: + **true** — Quando seu agente envia uma `DELETE` solicitação HTTP explícita, o servidor MCP expira a sessão de streaming de WorkSpaces aplicativos como parte da limpeza. A expiração da sessão encerra a instância de streaming subjacente e aciona a política de escalonamento automático configurada da frota. Para obter mais informações, consulte [Fleet Auto Scaling para aplicativos da Amazon WorkSpaces](autoscaling.md). + **false** (padrão) — A sessão de streaming continua em execução até que o tempo limite de desconexão seja atingido. Para obter mais informações sobre o tempo limite de desconexão, consulte. [Crie uma frota nos WorkSpaces aplicativos da Amazon](set-up-stacks-fleets-create.md) **nota** Por padrão, um cliente `mcp-proxy-for-aws` MCP processa automaticamente a `DELETE` solicitação quando você encerra adequadamente o ciclo de vida do cliente. ## Ferramentas disponíveis O servidor MCP fornece as seguintes ferramentas para os agentes interagirem com o desktop durante uma sessão de streaming. Todos os nomes de ferramentas usam o `agentaccess___` prefixo. ### Ferramentas de mouse `left_click` Clique com o botão esquerdo nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional, por exemplo `ctrl` ou`ctrl+shift`). `double_click` Clique duas vezes nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `triple_click` Faça um clique triplo nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `right_click` Clique com o botão direito do mouse nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `middle_click` Clique com o botão do meio nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `left_click_drag` Clique com o botão esquerdo e arraste das coordenadas iniciais para as coordenadas finais. Parâmetros: `start_x` (obrigatório), `start_y` (obrigatório), `end_x` (obrigatório), `end_y` (obrigatório). `left_mouse_down` Pressione e segure o botão esquerdo do mouse nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `left_mouse_up` Solte o botão esquerdo do mouse nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `modifiers` (opcional). `move_pointer` Mova o ponteiro para as coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório). `scroll` Role a roda do mouse nas coordenadas fornecidas. Parâmetros: `x` (obrigatório), `y` (obrigatório), `scroll_direction` (obrigatório —`Up`,,`Down`, ou`Right`)`Left`, `scroll_amount` (obrigatório — em tiques, onde 120 tiques é igual ao entalhe de uma roda), (opcional). `modifiers` ### Ferramentas de teclado `type_text` Digite texto simulando eventos de teclado para cada caractere. Parâmetros: `text` (obrigatório — até 10.000 caracteres). `key` Pressione uma tecla ou uma combinação de teclas. Parâmetros: `keys` (obrigatório — uma única tecla ou combinação unida por `+``a`, por exemplo`ctrl+c`, ou`ctrl+shift+s`). `hold_key` Mantenha pressionada uma tecla ou uma combinação de teclas por um período especificado. Parâmetros: `keys` (obrigatório), `duration` (obrigatório — 1 a 30 segundos). ### Ferramentas de tela `screenshot` Faça uma captura de tela da área de trabalho. As dimensões da imagem retornada definem o espaço de coordenadas para todas as ferramentas do mouse. Parâmetros: `include_cursor` (opcional — o padrão é). `false` ## Encaminhamento de ferramentas MCP O encaminhamento de ferramentas MCP permite que os agentes interajam com os aplicativos e o sistema operacional do desktop por meio de chamadas diretas de MCP, em vez de usar ferramentas de uso do computador. Quando você ativa o encaminhamento de ferramentas, o servidor MCP encaminha as ferramentas configuradas na sessão do WorkSpaces aplicativo para o seu agente. ### Configurando o encaminhamento de ferramentas Para configurar o encaminhamento de ferramentas MCP: 1. **Ativar o encaminhamento de ferramentas** — ative a ação do `FORWARD_MCP_TOOLS` agente por meio das configurações da API ou do console. 1. **Configure o servidor MCP no WorkSpace** — O serviço procura um arquivo de configuração no seguinte caminho: ``` C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json ``` 1. **Verifique a disponibilidade da ferramenta** — Se o arquivo de configuração estiver presente, o serviço se conectará aos servidores MCP configurados no arquivo e encaminhará as ferramentas. As ferramentas encaminhadas aparecem quando o agente lista as ferramentas disponíveis. **nota** Tanto o acesso ao IAM quanto a configuração do serviço devem estar habilitados para que o encaminhamento de ferramentas funcione. As permissões do IAM não substituem a configuração do serviço. ### Permissões do IAM para encaminhamento de ferramentas A ação do IAM para chamar ferramentas encaminhadas é`CallForwardedTool`. Você pode definir o escopo do acesso a pilhas específicas usando a chave de `StackArn` condição: ``` { "Action": "agentaccess-mcp:*", "Resource": "*", "Condition": { "ArnLike": { "ponte-mcp:StackArn": "arn:aws:appstream:{{region}}:{{account-id}}:stack/{{stack-name}}" } } } ``` ## Estruturas compatíveis Você pode se conectar ao servidor WorkSpaces Applications MCP a partir de qualquer estrutura de MCP-compatible agente que ofereça suporte à assinatura Streamable HTTP e SigV4. As seguintes estruturas foram testadas: + [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) — Fornece suporte nativo ao cliente MCP. + [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — Um transporte leve que manipula a assinatura SigV4 para solicitações MCP em Python. ## Monitoramento Você pode monitorar a atividade do agente por meio dos seguintes serviços: + **AWS CloudTrail**— Os eventos da sessão do agente são registrados. CloudTrail Você pode ver quando os agentes se conectam, quais ferramentas eles usam e quando as sessões terminam. As chamadas de ferramentas são eventos de dados e exigem que você configure uma trilha para registrar eventos de dados. Para obter mais informações, consulte [Registrar eventos de dados](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html), no *Guia do usuário do CloudTrail *. + **CloudWatch**— As métricas operacionais para sessões de agentes estão disponíveis em CloudWatch. + **Amazon S3** — Se você configurar o armazenamento de capturas de tela, as capturas de tela capturadas durante as sessões do agente estarão disponíveis no bucket do Amazon S3 que você especificar. As capturas de tela são armazenadas com o seguinte formato de chave: ``` agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png ``` O UUID no caminho é o ID da sessão de streaming de WorkSpaces aplicativos. ## Conceitos básicos Para começar a usar o servidor WorkSpaces Applications MCP, consulte[Comece a fornecer aos agentes acesso aos WorkSpaces aplicativos](getting-started-agent-access.md).