本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 開始為客服人員提供 WorkSpaces 應用程式的存取權
<a name="getting-started-agent-access"></a>

若要讓 AI 代理器透過 Amazon WorkSpaces 應用程式操作桌面應用程式，您可以建立為代理程式啟用存取權的堆疊、產生串流 URL，並將您的代理程式連線至受管 MCP 服務。

如果您是第一次設定客服人員存取，您可以使用建置您的第一個客服人員快速入門體驗。您也可以遵循本主題中的步驟，手動設定客服人員存取。GitHub 儲存庫提供快速入門體驗 — [sample-code-for-workspaces-agent-access](https://github.com/aws-samples/sample-code-for-workspaces-agent-access)。

本教學課程大約需要 15 分鐘才能完成。

**重要**  
您在本教學課程中建立的資源可能會對您的帳戶 AWS 收取費用。刪除堆疊並在完成後停止機群，以避免持續收費。

在本教學課程中，您會完成下列任務：
+ 步驟 1：建立啟用客服人員存取的堆疊
+ 步驟 2：產生串流 URL
+ 步驟 3：將您的代理程式連線至 MCP 服務
+ 步驟 4：驗證客服人員活動
+ 步驟 5：清除 資源

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

開始前，請確定您具有下列項目：
+ 作用中的 Amazon WorkSpaces 應用程式機群。如果您尚未設定，請參閱 [Amazon WorkSpaces 應用程式入門：設定範例應用程式](getting-started.md)。
+ AWS 憑證 （環境變數、 AWS 設定檔、EC2 執行個體角色或 Lambda 執行角色），具有下列 IAM 許可。代理程式會直接使用這些登入資料來簽署對 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 相容的代理程式架構。代理程式必須能夠對 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. 在**堆疊詳細資訊**頁面 （步驟 4 之 1) 的 **AI 代理程式存取**下，選取**啟用 AI 代理程式存取**。選擇**下一步**。

1. 在**啟用儲存**頁面 （步驟 4 之 2) 上，選擇性地啟用**主資料夾**，以允許您的代理程式將檔案儲存至您 AWS 帳戶中的 Amazon S3 儲存貯體。與此堆疊相關聯的機群必須允許透過網際網路或 Amazon 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：產生串流 URL
<a name="getting-started-agent-access-streaming-url"></a>

使用標準 WorkSpaces 應用程式 `CreateStreamingURL` API 建立串流 URL。您不需要代理程式特定的參數。堆疊的代理程式存取組態會決定代理程式特定的行為。

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

**使用主控台產生串流 URL**

1. 開啟 [WorkSpaces 應用程式主控台](https://console.aws.amazon.com/appstream2/home)。

1. 在左側導覽窗格中，選擇 **Stacks**，然後選擇您在啟用代理程式存取的情況下建立的堆疊。

1. 選擇**動作**按鈕，然後在下拉式清單中，選取**建立串流 URL**。必須選取您的堆疊，此選項才能使用。

1. 在 **UserID** 區段中，輸入使用者。`TestUser` 如果您正在測試，則可以輸入 。

1. 在 **URL 過期**區段中，選取您希望 URL 有效的時間。建議使用較短的時間。預設為 30 分鐘，並建議用於測試。

1. 選擇 **GetURL** 並複製產生的 URL。

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

執行下列命令來產生串流 URL：

```
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`。您的代理程式會使用 AWS 先決條件中設定的登入資料搭配 `agentaccess-mcp:*`許可來簽署每個請求。您傳遞來自步驟 2 的串流 URL，做為每個 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. 在左側導覽窗格中，選擇 **Fleets (機群)**。

1. 選取與堆疊相關聯的機群。選擇 **Actions (動作)**、**Stop (停止)**。等待機群停止。

1. 在左側導覽窗格中，選擇 **Stacks (堆疊)**。

1. 選取您建立的堆疊，然後選擇**動作**、**取消關聯機群**。

1. 在仍選取堆疊的情況下，選擇**動作**、**刪除**。

1. （選用） 若要刪除機群，請在左側導覽窗格中，選擇**機群**。選取機群，然後選擇**動作**、**刪除**。

### 使用 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}}
```