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á.

# Comece a fornecer aos agentes acesso aos WorkSpaces aplicativos
<a name="getting-started-agent-access"></a>

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.](https://github.com/aws-samples/sample-code-for-workspaces-agent-access)

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
<a name="getting-started-agent-access-prereqs"></a>

Antes de começar, você deve ter o seguinte:
+ Uma frota ativa da Amazon WorkSpaces Applications. Se você ainda não configurou um, consulte[Comece a usar os WorkSpaces aplicativos da Amazon: configure com aplicativos de amostra](getting-started.md).
+ 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](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) 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
<a name="getting-started-agent-access-create-stack"></a>

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
<a name="getting-started-agent-access-create-stack-console"></a>

**Para criar uma pilha com acesso de agente**

1. Abra o [console de WorkSpaces aplicativos](https://console.aws.amazon.com/appstream2/home).

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

1. 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**.

1. 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**.

1. 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**.

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

### Usar o AWS CLI
<a name="getting-started-agent-access-create-stack-cli"></a>

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
<a name="getting-started-agent-access-streaming-url"></a>

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
<a name="getting-started-agent-access-streaming-url-console"></a>

**Para gerar um URL de streaming usando o console**

1. Abra o [console de WorkSpaces aplicativos](https://console.aws.amazon.com/appstream2/home).

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

1. 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.

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

1. 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.

1. Escolha **GetURL** e copie o URL gerado.

### Usar o AWS CLI
<a name="getting-started-agent-access-streaming-url-cli"></a>

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
<a name="getting-started-agent-access-connect"></a>

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
<a name="getting-started-agent-access-verify"></a>

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
<a name="getting-started-agent-access-cleanup"></a>

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
<a name="getting-started-agent-access-cleanup-console"></a>

**Para limpar os recursos**

1. Abra o [console de WorkSpaces aplicativos](https://console.aws.amazon.com/appstream2/home).

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

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

1. No painel de navegação à esquerda, selecione**Pilhas**.

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

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

1. (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
<a name="getting-started-agent-access-cleanup-cli"></a>

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}}
```