本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 开始为代理提供 WorkSpaces 应用程序访问权限
<a name="getting-started-agent-access"></a>

要让 AI 代理通过 Amazon Applications 操作桌面 WorkSpaces 应用程序，您需要创建一个允许代理访问的堆栈，生成一个直播 URL，然后将您的代理连接到托管 MCP 服务。

如果您是首次设置代理访问权限，则可以使用 “构建您的第一个代理” 快速入门体验。您也可以按照本主题中的步骤手动配置代理访问权限。 GitHub存储库中提供了快速入门体验——工作空间的[示例](https://github.com/aws-samples/sample-code-for-workspaces-agent-access)代码代理访问权限。

本教程大约需要 15 分钟才能完成。

**重要**  
您在本教程中创建的资源可能会导致您的 AWS 账户产生费用。删除堆栈并在完成后停止舰队，以避免持续收费。

在本教程中，您将完成以下任务：
+ 步骤 1：创建启用代理访问权限的堆栈
+ 第 2 步：生成直播网址
+ 第 3 步：将您的代理连接到 MCP 服务
+ 步骤 4：验证代理活动
+ 第 5 步：清除 资源

## 先决条件
<a name="getting-started-agent-access-prereqs"></a>

在开始之前，请确保您具有以下各项：
+ 活跃的 Amazon WorkSpaces 应用程序队列。如果您尚未设置，请参阅[Amazon WorkSpaces 应用程序入门：使用示例应用程序进行设置](getting-started.md)。
+ AWS 具有以下 IAM 权限的证书（环境变量、 AWS 配置文件、EC2 实例角色或 Lambda 执行角色）。代理直接使用以下凭证签署对 MCP 服务的请求：

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

  通`agentaccess-mcp:*`配符包括以下操作：
  + `agentaccess-mcp:InvokeMcp`— 初始化会话并发现工具
  + `agentaccess-mcp:GetScreenshot`— 捕获屏幕状态
  + `agentaccess-mcp:LeftClick`— 执行鼠标左键单击
  + `agentaccess-mcp:DoubleClick`— 执行双击
  + `agentaccess-mcp:TripleClick`— 执行三次单击
  + `agentaccess-mcp:RightClick`— 执行鼠标右键单击
  + `agentaccess-mcp:MiddleClick`— 执行鼠标中键单击
  + `agentaccess-mcp:TypeText`— 键入文本字符串
  + `agentaccess-mcp:KeyPress`— 按键或组合键
  + `agentaccess-mcp:HoldKey`— 按住键持续时间
  + `agentaccess-mcp:Scroll`— 在坐标处滚动
  + `agentaccess-mcp:MovePointer`— 将指针移动到坐标
  + `agentaccess-mcp:LeftClickDrag`— 执行左键单击拖动
  + `agentaccess-mcp:LeftMouseDown`— 按住鼠标左键
  + `agentaccess-mcp:LeftMouseUp`— 松开鼠标左键
  + `agentaccess-mcp:CheckConnectionStatus`— 检查直播会话的连接状态
  + `agentaccess-mcp:CallForwardedTool`— 在远程实例上调用转发工具
+  MCP-compatible 代理框架。代理必须能够向 MCP 端点发出 SigV4-signed 可流式传输的 HTTP 请求。[Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) 提供原生 MCP 客户端支持，或者你可以将任何框架与 mcp-proxy-for-aws 传输一起使用。
+ Python 3.10 或更高版本。不需要特定的操作系统。

## 步骤 1：创建启用代理访问权限的堆栈
<a name="getting-started-agent-access-create-stack"></a>

创建启用代理访问权限的 WorkSpaces 应用程序堆栈，以允许 AI 代理与桌面应用程序交互。

### 使用 AWS 管理控制台
<a name="getting-started-agent-access-create-stack-console"></a>

**创建具有代理访问权限的堆栈**

1. 打开[WorkSpaces 应用程序控制台](https://console.aws.amazon.com/appstream2/home)。

1. 在左侧导航窗格中，选择**堆栈**，然后选择**创建堆栈**。

1. 在**堆栈详细信息**页面（第 1 步，共 4 步）上，在 **AI 代理访问权限**下，选择**启用 AI 代理访问权限**。选择**下一步**。

1. 在 “**启用存储**” 页面（第 2 步，共 4 步）上，可以选择启用**主文件夹**，以允许您的代理将文件保存到您 AWS 账户中的 Amazon S3 存储桶中。与此堆栈关联的队列必须允许通过互联网或亚马逊 S3 的 Amazon VPC 终端节点访问 Amazon S3。选择**下一步**。

1. 在**编辑代理设置**页面（第 3 步，共 4 步）上，配置以下内容：
   + **启用计算机输入**-允许代理选择按钮、输入文本并在桌面上滚动。如果启用计算机输入，则还必须启用计算机视觉。
   + **启用计算机视觉**-允许代理查看桌面。
   + **屏幕截图存储**-配置直播会话期间代理屏幕截图的存储位置。如果启用，请提供您有权写入的 Amazon S3 存储桶。
   + **屏幕分辨率**-选择代理流媒体环境的显示分辨率 (1280x720)。
   + **屏幕图像类型**-选择代理屏幕截图的图像格式（PNG 或 JPEG）。
   + **应用程序设置持久性**-（可选）启用此选项以在会话之间保存代理的应用程序自定义设置和 Windows 设置。设置将保存到您 AWS 账户中的 Amazon S3 存储桶中。
   + **启用 MCP 工具转发**-允许代理通过直接 MCP 呼叫而不是使用计算机使用工具与应用程序和桌面操作系统进行交互。启用后，在 WorkSpaces 应用程序会话中配置的 MCP 工具将转发给代理。
   + **启用用户控制模式**-允许用户通过浏览器实时观察代理会话。代理工作时，观察者可以看到桌面的实时视图。在 VIEW\_STOP 模式下，观察者可以使用屏幕顶部的按钮停止代理。停止后，代理必须启动新的会话才能恢复。
**注意**  
您必须启用至少一个计算机输入或计算机视觉。

   选择**下一步**。

1. 在 “**查看并创建**” 页面（第 4 步，共 4 步）上，查看您的设置并选择 “**创建堆栈**”。

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

运行以下命令创建启用代理访问权限的堆栈：

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

要同时启用屏幕截图存储，请添加`S3BucketArn`和`ScreenshotsUploadEnabled`参数：

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

创建堆栈后，将其与队列关联。代理无法连接到没有关联队列的堆栈。

```
aws appstream associate-fleet \
    --stack-name {{your-stack-name}} \
    --fleet-name {{your-fleet-name}}
```

## 第 2 步：生成直播网址
<a name="getting-started-agent-access-streaming-url"></a>

使用标准 WorkSpaces 应用程序 `CreateStreamingURL` API 创建直播网址。您不需要代理特定的参数。堆栈的代理访问配置决定了代理特定的行为。

### 使用 AWS 管理控制台
<a name="getting-started-agent-access-streaming-url-console"></a>

**使用控制台生成直播 URL**

1. 打开[WorkSpaces 应用程序控制台](https://console.aws.amazon.com/appstream2/home)。

1. 在左侧导航窗格中，选择**堆栈**，然后选择在启用代理访问权限的情况下创建的堆栈。

1. 选择 “**操作**” 按钮，然后在下拉列表中选择 “**创建直播网址**”。必须选择您的堆栈才能使用此选项。

1. 在 “**用户 ID**” 部分，输入用户。`TestUser`如果您正在测试，则可以输入。

1. 在 “**URL 过期**” 部分中，选择您希望 URL 的有效时间。建议缩短时间。默认时间为 30 分钟，建议用于测试。

1. 选择 **getUrl** 并复制生成的网址。

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

运行以下命令生成直播地址：

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

响应包括`StreamingURL`您在下一步中传递给代理的。URL 在`--validity`参数指定的持续时间内有效。

## 第 3 步：将您的代理连接到 MCP 服务
<a name="getting-started-agent-access-connect"></a>

您的代理通过以下固定端点连接到托管 MCP 服务：

`https://agentaccess-mcp.{{region}}.api.aws/mcp`

连接使用带有服务名称的 Sigv4 签名。`agentaccess-mcp`您的代理使用先决条件中配置的具有`agentaccess-mcp:*`权限的 AWS 凭证对每个请求进行签名。您将步骤 2 中的直播网址作为每个 MCP 请求的标题传递。

以下示例说明如何使用 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,
    },
)
```

代理连接后，可以使用 MCP 工具输入文本、选择按钮和截取桌面的屏幕截图。

## 步骤 4：验证代理活动
<a name="getting-started-agent-access-verify"></a>

您可以使用以下 AWS 服务验证代理活动：
+ **AWS CloudTrail**— AWS CloudTrail 记录代理会话事件。打开 AWS CloudTrail 控制台查看代理活动。
+ **CloudWatch**— CloudWatch 提供代理会话的操作指标。打开 CloudWatch 控制台查看指标。
+ **Amazon S3** — 如果您启用了屏幕截图存储，Amazon S3 会将屏幕截图存储在您在堆栈配置期间指定的存储桶中。

## 第 5 步：清除 资源
<a name="getting-started-agent-access-cleanup"></a>

为避免持续收费，请删除您在本教程中创建的堆栈。您必须先停止队列并将其与堆栈断开关联，然后才能删除堆栈。或者，您也可以删除舰队。

### 使用 AWS 管理控制台
<a name="getting-started-agent-access-cleanup-console"></a>

**清理资源**

1. 打开[WorkSpaces 应用程序控制台](https://console.aws.amazon.com/appstream2/home)。

1. 在左侧导航窗格中，选择**实例集**。

1. 选择与堆栈关联的舰队。依次选择 **Actions** 和 **Stop**。等待实例集停止。

1. 在左侧导航窗格中，选择**堆栈**。

1. 选择您创建的堆栈，然后选择**操作**、**取消关联舰队**。

1. 在堆栈仍处于选中状态的情况下，选择**操作**、**删除**。

1. （可选）要删除舰队，请在左侧导航窗格中选择 **Fleets**。选择舰队并选择 “**操作**”、“**删除”**。

### 使用 AWS CLI
<a name="getting-started-agent-access-cleanup-cli"></a>

运行以下命令来清理资源：

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

（可选）要同时在队列停止后将其删除，请执行以下操作：

```
aws appstream delete-fleet \
    --name {{your-fleet-name}}
```