Comece a fornecer aos agentes acesso aos WorkSpaces aplicativos

Para permitir que agentes de IA operem aplicativos de desktop por meio do Amazon WorkSpaces Applications, você cria uma pilha com acesso habilitado para agentes, gera uma URL de streaming e conecta seu agente ao serviço MCP gerenciado.

Se você estiver configurando o acesso do agente pela primeira vez, poderá usar a experiência de início rápido do Build Your First Agent. Você também pode seguir as etapas deste tópico para configurar o acesso do agente manualmente. A experiência de início rápido está disponível no GitHub repositório — código de amostra para acesso ao agente de espaço de trabalho.

Este tutorial leva aproximadamente 15 minutos para ser concluído.

Importante

Os recursos que você criar neste tutorial podem resultar em cobranças em sua AWS conta. Exclua a pilha e interrompa a frota quando terminar para evitar cobranças contínuas.

Neste tutorial, você conclui as seguintes tarefas:

• Etapa 1: criar uma pilha com o acesso do agente ativado

• Etapa 2: gerar um URL de streaming

• Etapa 3: Conecte seu agente ao serviço MCP

• Etapa 4: verificar a atividade do agente

• Etapa 5: Limpar os recursos do

Pré-requisitos

Antes de começar, você deve ter o seguinte:

• Uma frota ativa da Amazon WorkSpaces Applications. Se você ainda não configurou um, consulteComece a usar os WorkSpaces aplicativos da Amazon: configure com aplicativos de amostra.

• AWS credenciais (variáveis de ambiente, AWS perfil, função de instância do EC2 ou função de execução do Lambda) com as seguintes permissões do IAM:

  {
      "Sid": "MCP",
      "Effect": "Allow",
      "Action": ["agentaccess-mcp:*"],
      "Resource": "*"
  },
  {
      "Sid": "AppStream",
      "Effect": "Allow",
      "Action": ["appstream:CreateStreamingURL", "appstream:DescribeFleets"],
      "Resource": "*"
  }

• Uma estrutura de MCP-compatible agente. O agente deve ser capaz de fazer solicitações HTTP SigV4-signed transmissíveis para o endpoint MCP. O Strands Agents SDK fornece suporte nativo ao cliente MCP, ou você pode usar qualquer estrutura com o transporte mcp-proxy-for-aws.

• Python 3.10 ou posterior. Nenhum sistema operacional específico é necessário.

Etapa 1: criar uma pilha com o acesso do agente ativado

Crie uma pilha de WorkSpaces aplicativos com acesso de agente ativado para permitir que agentes de IA interajam com aplicativos de desktop.

Usar o AWS Console de Gerenciamento

Para criar uma pilha com acesso de agente

1. Abra o console de WorkSpaces aplicativos.

2. No painel de navegação esquerdo, escolha Pilhas e, em seguida, escolha Criar pilha.

3. Na página de detalhes da pilha (etapa 1 de 4), em Acesso ao agente de IA, selecione Ativar acesso ao agente de IA. Escolha Próximo.

4. Na página Habilitar armazenamento (etapa 2 de 4), habilite opcionalmente as pastas iniciais para permitir que seu agente salve arquivos em um bucket do Amazon S3 em AWS sua conta. A frota associada a essa pilha deve permitir o acesso ao Amazon S3 pela Internet ou a um endpoint do Amazon VPC para o Amazon S3. Escolha Próximo.

5. Na página Editar configurações do agente (etapa 3 de 4), configure o seguinte:

   • Ativar a entrada do computador — Permita que os agentes escolham botões, insiram texto e rolem pela área de trabalho. Se você habilitar a entrada do computador, também deverá habilitar a visão computacional.

   • Habilite a visão computacional — Permita que os agentes vejam a área de trabalho.

   • Armazenamento de capturas de tela — configure onde as capturas de tela do agente são armazenadas durante as sessões de streaming. Se habilitado, forneça um bucket do Amazon S3 no qual você tenha permissões para gravar.

   • Resolução da tela — Selecione a resolução da tela para o ambiente de streaming do agente (1280x720).

   • Tipo de imagem da tela — Selecione o formato da imagem para as capturas de tela do agente (PNG ou JPEG).

   • Persistência das configurações do aplicativo — Opcionalmente, habilite isso para salvar as personalizações do aplicativo do seu agente e as configurações do Windows entre as sessões. As configurações são salvas em um bucket do Amazon S3 em sua AWS conta.

   nota

   Você deve habilitar pelo menos uma das entradas do computador ou da visão computacional.

   Escolha Próximo.

6. Na página Revisar e criar (etapa 4 de 4), revise suas configurações e escolha Criar pilha.

Usar o AWS CLI

Execute o comando a seguir para criar uma pilha com o acesso do agente ativado:

aws appstream create-stack \
    --name your-stack-name \
    --agent-access-config '{
        "Settings": [
            {"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
            {"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"}
        ],
        "ScreenResolution": "W_1280xH_720",
        "ScreenImageFormat": "PNG"
    }'

Para também ativar o armazenamento de capturas de tela, adicione os ScreenshotsUploadEnabled parâmetros S3BucketArn e:

aws appstream create-stack \
    --name your-stack-name \
    --agent-access-config '{
        "Settings": [
            {"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
            {"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"}
        ],
        "ScreenResolution": "W_1280xH_720",
        "ScreenImageFormat": "PNG",
        "S3BucketArn": "arn:aws:s3:::your-bucket-name",
        "ScreenshotsUploadEnabled": true
    }'

Depois de criar a pilha, associe-a a uma frota. Os agentes não podem se conectar a uma pilha que não tenha uma frota associada.

aws appstream associate-fleet \
    --stack-name your-stack-name \
    --fleet-name your-fleet-name

Etapa 2: gerar um URL de streaming

Crie um URL de streaming usando a CreateStreamingURL API de WorkSpaces aplicativos padrão. Você não precisa de parâmetros específicos do agente. A configuração de acesso do agente da pilha determina o comportamento específico do agente.

Usar o AWS Console de Gerenciamento

Para gerar um URL de streaming usando o console

1. Abra o console de WorkSpaces aplicativos.

2. No painel de navegação esquerdo, escolha Pilhas e, em seguida, escolha a pilha que você criou com o acesso do agente ativado.

3. Escolha o botão Ações e, no menu suspenso, selecione Criar URL de streaming. Sua pilha deve ser selecionada para que essa opção esteja disponível.

4. Na seção UserID, insira um usuário. Você pode entrar TestUser se estiver testando.

5. Na seção Expiração do URL, selecione a hora em que você deseja que o URL seja válido. Um tempo menor é recomendado. 30 minutos é o padrão e é recomendado para testes.

6. Escolha GetURL e copie o URL gerado.

Usar o AWS CLI

Execute o comando a seguir para gerar um URL de streaming:

aws appstream create-streaming-url \
    --stack-name your-stack-name \
    --fleet-name your-fleet-name \
    --user-id your-agent-id \
    --validity 3600

A resposta inclui uma StreamingURL que você passa para seu agente na próxima etapa. O URL é válido pela duração especificada pelo --validity parâmetro.

Etapa 3: Conecte seu agente ao serviço MCP

Seu agente se conecta ao serviço MCP gerenciado no seguinte endpoint fixo:

https://agentaccess-mcp.region.api.aws/mcp

A conexão usa a assinatura SigV4 com o nome do serviço. agentaccess-mcp Você passa o URL de streaming da Etapa 2 como um cabeçalho em cada solicitação MCP.

O exemplo a seguir mostra como estabelecer a conexão usando 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,
    },
)

Depois que o agente se conectar, ele poderá usar as ferramentas MCP para inserir texto, escolher botões e fazer capturas de tela da área de trabalho.

Etapa 4: verificar a atividade do agente

Você pode verificar a atividade do agente usando os seguintes AWS serviços:

• AWS CloudTrail— AWS CloudTrail registra os eventos da sessão do agente. Abra o AWS CloudTrail console para ver a atividade do agente.

• CloudWatch— CloudWatch fornece métricas operacionais para sessões de agentes. Abra o CloudWatch console para ver as métricas.

• Amazon S3 — Se você habilitou o armazenamento de capturas de tela, o Amazon S3 armazena as capturas de tela no bucket que você especificou durante a configuração da pilha.

Etapa 5: Limpar os recursos do

Para evitar cobranças contínuas, exclua a pilha que você criou neste tutorial. Você deve parar a frota e desassociá-la da pilha antes de excluir a pilha. Opcionalmente, você também pode excluir a frota.

Usar o AWS Console de Gerenciamento

Para limpar os recursos

1. Abra o console de WorkSpaces aplicativos.

2. No painel de navegação à esquerda, escolha Fleets (Frotas).

3. Selecione a frota associada à pilha. Escolha Actions, Stop. Espere a frota parar.

4. No painel de navegação à esquerda, selecionePilhas.

5. Selecione a pilha que você criou e escolha Ações, Desassociar frota.

6. Com a pilha ainda selecionada, escolha Ações, Excluir.

7. (Opcional) Para excluir a frota, no painel de navegação esquerdo, escolha Frotas. Selecione a frota e escolha Ações, Excluir.

Usar o AWS CLI

Execute os seguintes comandos para limpar os recursos:

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

(Opcional) Para também excluir a frota depois que ela for interrompida:

aws appstream delete-fleet \
    --name your-fleet-name