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, consulteConectando-se ao servidor MCP.

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 sobremcp-proxy-for-aws, consulte mcp-proxy-for-aws on. GitHub

A forma como você autentica a sessão de streaming depende do tipo de sua frota:

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 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 emmcp-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, _):
    ...

Para obter mais informações sobre como configurar a federação SAML com WorkSpaces aplicativos, consulte Configurando o SAML 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 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.

Os seguintes modos estão disponíveis:

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:

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

Ferramentas de teclado

Ferramentas de tela

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:

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:

Monitoramento

Você pode monitorar a atividade do agente por meio dos seguintes serviços:

Conceitos básicos

Para começar a usar o servidor WorkSpaces Applications MCP, consulteComece a fornecer aos agentes acesso aos WorkSpaces aplicativos.