本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # WorkSpaces 應用程式 MCP 伺服器 WorkSpaces 應用程式 MCP 伺服器是一項全受管服務，為 AI 代理器提供模型內容協定 (MCP) 工具，以在串流工作階段期間與桌面應用程式互動。客服人員可以按一下按鈕、輸入文字、捲動和擷取桌面的螢幕擷取畫面。 ## 概觀 當您在堆疊上啟用代理程式存取時，代理程式可以連線至受管 MCP 伺服器，以與桌面應用程式互動。MCP 伺服器會處理您的代理程式與串流工作階段之間的通訊。您的代理程式會傳送 MCP 工具請求，而伺服器會在桌面上執行這些請求。 MCP 伺服器託管在 AWS 雲端。您不需要安裝或維護任何伺服器元件。伺服器使用可串流 HTTP 做為其傳輸通訊協定。 代理程式存取支援non-domain-joined和加入網域的機群。連線方法因機群類型而異。Non-domain-joined的機群會使用串流 URL 驗證工作階段，而加入網域的機群則透過 SAML 聯合進行驗證。如需符合機群的路徑，請參閱 [連線至 MCP 伺服器](#agent-access-mcp-server-endpoint)。 ## 連線至 MCP 伺服器 代理程式會在下列端點連線至 MCP 伺服器： ``` https://agentaccess-mcp.{{region}}.api.aws/mcp ``` MCP 伺服器託管於 AWS 雲端，並使用可串流 HTTP 做為其傳輸通訊協定。您不需要安裝或維護任何伺服器元件。 每個請求都必須使用服務名稱為 的 IAM 憑證 SigV4-signed`agentaccess-mcp`。下列 Python 範例顯示使用 的一般連線模式`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 ... ``` 對於其他語言，請撰寫您自己的 SigV4 簽署邏輯以進行傳出 MCP 請求，或使用支援 SigV4 簽署的程式庫。如需 的詳細資訊`mcp-proxy-for-aws`，請參閱 GitHub 上的 [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)。 驗證串流工作階段的方式取決於您的機群類型： + **Non-domain-joined的機群** — 傳遞串流 URL 做為標頭。請參閱 [與non-domain-joined的機群連線](#agent-access-mcp-server-connect-ndj)。 + **加入網域的機群** — 傳遞已簽署的 SAML 聲明做為中繼資料。請參閱 [與加入網域的機群連線](#agent-access-mcp-server-connect-dj)。 **注意** 在任何指定時間，只有一個代理程式可以連線到唯一的工作階段。透過 `UserId` 參數指定的具名使用者一次只能有一個作用中工作階段。若要同時執行多個代理程式，每個代理程式都必須連線到自己的唯一工作階段。 ### 與non-domain-joined的機群連線 對於non-domain-joined的機群，請使用 `CreateStreamingURL` API 產生串流 URL，並將其做為每個請求的`X-Amzn-AgentAccess-Streaming-Session-Url`標頭傳遞。不需要代理程式特定的參數。代理程式行為取決於堆疊的代理程式存取組態。 ``` 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, _): ... ``` 如需 `CreateStreamingURL` API 的詳細資訊，請參閱《*Amazon WorkSpaces 應用程式 2.0 API 參考*》中的 [CreateStreamingURL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html)。 ### 與加入網域的機群連線 當客服人員存取加入網域的串流執行個體時，必須透過 SAML 供應商聯合連線。此要求同時適用於傳統和代理程式工作階段。對於客服人員工作階段， [憑證型身分驗證](certificate-based-authentication.md) 為必要項目。 由於加入網域的串流執行個體需要透過 SAML 存取，因此您的 MCP 用戶端必須提供已簽署的 SAML 聲明，而不是串流 URL。編碼的 SAML 聲明超過 HTTP 標頭大小限制。若要避免這種情況，請使用 中的 `metadata` 欄位`mcp-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, _): ... ``` **注意** `metadata` 參數已新增至 1.6.1 `mcp-proxy-for-aws`版。舊版無法在沒有其他開發的情況下注入 `_meta` 欄位。若要升級，請執行 `pip install -U mcp-proxy-for-aws`。 如需使用 WorkSpaces 應用程式設定 SAML 聯合的詳細資訊，請參閱*《Amazon WorkSpaces 應用程式管理指南*》中的[設定 SAML](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html)。如需詳細資訊和完整的工作範例，請參閱 GitHub 上範例中的 [sample-code-for-workspaces-agent-access](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) 儲存庫。 AWS ## 連線模式 您可以在 MCP 請求上設定 `X-Amzn-AgentAccess-Connect-Mode`標頭，以控制代理程式等待桌面工作階段變成可用的方式。 **注意** 連線模式適用於non-domain-joined和加入網域的機群。將 `X-Amzn-AgentAccess-Connect-Mode` 標頭與機群類型使用的任何身分驗證機制一起設定 (non-domain-joined群的streaming-URL 標頭，或加入網域機群的 SAML 聲明中繼資料）。 下列模式可供使用： + **BLOCKING** （預設） — MCP 伺服器會等到桌面連線完全建立後再回應。`tools/list` 傳回 時，所有工具都會立即可用。 + **輪詢** — MCP 伺服器會立即回應，無需等待桌面連線。一開始，只有 `connection_status`工具可用。您的代理程式會輪詢此工具，直到建立連線為止，此時完整工具集便可供使用。 當您希望代理程式在等待桌面連線時執行其他工作，或當您需要更多控制連線逾時行為時，請使用 POLLING 模式。 下列範例示範如何使用 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() ``` ## 工作階段清除 當您的代理程式在 MCP 請求上設定 `X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete`標頭，即可控制串流工作階段是否過期。下列值可供使用： + **true** — 當您的代理程式傳送明確的 HTTP `DELETE`請求時，MCP 伺服器會在清除期間過期 WorkSpaces 應用程式串流工作階段。工作階段過期會終止基礎串流執行個體，並觸發機群設定的自動調整規模政策。如需詳細資訊，請參閱[Amazon WorkSpaces 應用程式的機群 Auto Scaling](autoscaling.md)。 + **false** （預設） — 串流工作階段會繼續執行，直到達到中斷連線逾時為止。如需中斷連線逾時的詳細資訊，請參閱 [在 Amazon WorkSpaces 應用程式中建立機群](set-up-stacks-fleets-create.md)。 **注意** 根據預設，當您正確結束用戶端生命週期時，`mcp-proxy-for-aws`MCP 用戶端會自動處理`DELETE`請求。 ## 可用的工具 MCP 伺服器提供下列工具，可讓客服人員在串流工作階段期間與桌面互動。所有工具名稱都使用 `agentaccess___`字首。 ### 滑鼠工具 `left_click` 在指定的座標執行滑鼠左鍵點選。 參數： `x` （必要）、 `y` （必要）、 `modifiers`（選用，例如 `ctrl`或 `ctrl+shift`)。 `double_click` 在指定的座標上執行按兩下。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `triple_click` 在指定的座標上執行三下點選。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `right_click` 在指定的座標執行滑鼠右鍵按一下。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `middle_click` 在指定的座標執行中間按一下。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `left_click_drag` 執行滑鼠左鍵從開始座標拖曳到結束座標。 參數： `start_x` （必要）、 `start_y` （必要）、 `end_x` （必要）、 `end_y`（必要）。 `left_mouse_down` 在指定的座標上按住滑鼠左鍵。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `left_mouse_up` 在指定的座標上放開滑鼠左鍵。 參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。 `move_pointer` 將指標移至指定的座標。 參數： `x` （必要）、 `y`（必要）。 `scroll` 在指定的座標上捲動滑鼠滾輪。 參數： `x`（必要）、 `y` （必要）、 `scroll_direction`（必要 — `Up`、`Down`、 或 `Right`)`Left`、 `scroll_amount`（必要 — 在刻度中，其中 120 個刻度等於一個車輪凹口）、 `modifiers`（選用）。 ### 鍵盤工具 `type_text` 透過模擬每個角色的鍵盤事件來輸入文字。 參數：`text`（必要 — 最多 10，000 個字元）。 `key` 按金鑰或金鑰組合。 參數：`keys`（必要 — 由 加入的單一金鑰或組合`+`，例如 `a`、 `ctrl+c`或 `ctrl+shift+s`)。 `hold_key` 在指定的持續時間內保留金鑰或金鑰組合。 參數： `keys` （必要）、 `duration`（必要 — 1 到 30 秒）。 ### 螢幕工具 `screenshot` 擷取桌面的螢幕擷取畫面。傳回的影像維度會定義所有滑鼠工具的座標空間。 參數：`include_cursor`（選用 — 預設為 `false`)。 ## MCP 工具轉送 MCP 工具轉送可讓客服人員透過直接 MCP 呼叫與應用程式和桌面作業系統互動，而不是使用電腦使用工具。當您啟用工具轉送時，MCP 伺服器會將 WorkSpaces 應用程式工作階段上設定的工具轉送至您的代理程式。 ### 設定工具轉送 若要設定 MCP 工具轉送： 1. **啟用工具轉送** — 透過 API 或主控台設定開啟`FORWARD_MCP_TOOLS`代理程式動作。 1. **確認 MCP 伺服器組態檔案存在** — 服務會在下列路徑尋找組態檔案： ``` C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json ``` 1. **在 WorkSpace 映像上設定 MCP 伺服器** — 組態檔案是具有單一頂層`mcpServers`物件的 JSON。每個金鑰都是您為伺服器選擇的唯一名稱。每個值指定如何啟動該伺服器。 ``` { "mcpServers": { "filesystem": { "command": "C:/path/to/python.exe", "args": ["C:/mcpServerPath/filesystem.py", "C:/UserName/Documents"] }, "weather": { "command": "C:/Program Files/my-mcp/weather.exe" } } } ``` [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/appstream2/latest/developerguide/agent-access-mcp-server.html) 1. **驗證工具可用性** — 如果組態檔案存在，服務會連線至檔案中設定的 MCP 伺服器，並轉送工具。代理程式列出其可用工具時，會顯示轉送的工具。 **注意** 必須啟用 IAM 存取和服務設定，工具轉送才能運作。IAM 許可不會覆寫服務設定。 ### MCP 工具轉送考量事項 設定 MCP 工具轉送時，請注意下列考量事項： + **Transport 僅為標準 I/O (stdio)。**每個項目都必須啟動透過其標準輸入和輸出說出 MCP 的程序。不支援遠端 HTTP 或 SSE MCP 端點。若要使用遠端端點，請在本機 stdio 伺服器中包裝它。 + **僅支援 `args` `command`和 。**環境變數或工作目錄沒有 欄位。每個伺服器都會繼承串流工作階段的環境，並以工作階段使用者身分執行。針對任何路徑引數使用 `command`和 的絕對路徑。 + **在路徑中使用正斜線 **（例如 `C:/Program Files/my-mcp/server.exe`)。JSON 會將反斜線視為逸出字元，因此以單一反斜線編寫的 Windows 樣式路徑無效。Windows 接受絕對路徑的正斜線，因此不需要將每個分隔符號逸出為 `\\`。 + **工具呼叫逾時。**每個轉送的工具呼叫必須在 5 秒內完成。MCP 伺服器會取消花費較長時間的呼叫，並將錯誤傳回給客服人員。設計可快速傳回的轉送工具。 ### 轉送的工具如何顯示給客服人員 為了防止伺服器之間發生衝突，MCP 伺服器會使用下列模式重新命名客服人員工具清單中的每個轉送工具： ``` forwarded___{{server-name}}___{{original-tool-name}} ``` {{server-name}} 是來自您組態檔案的金鑰。例如，來自`weather`伺服器的`get_forecast`工具會列為 `forwarded___weather___get_forecast`。當客服人員呼叫轉送的名稱時，MCP 伺服器會將請求路由到擁有伺服器上的原始工具。與工具名稱相符的客服人員代碼必須預期此字首。 ### 工具轉送的 IAM 許可 呼叫轉送工具的 IAM 動作為 `CallForwardedTool`。您可以使用 `StackArn`條件金鑰來限制對特定堆疊的存取： ``` { "Action": "agentaccess-mcp:*", "Resource": "*", "Condition": { "ArnLike": { "agentaccess-mcp:StackArn": "arn:aws:appstream:{{region}}:{{account-id}}:stack/{{stack-name}}" } } } ``` ## 相容架構 您可以從支援可串流 HTTP 和 SigV4 簽署的任何 MCP 相容代理程式架構連線至 WorkSpaces 應用程式 MCP 伺服器。已測試下列架構： + [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) — 提供原生 MCP 用戶端支援。 + [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — 在 Python 中處理 MCP 請求的 SigV4 簽署的輕量傳輸。 ## 監控 您可以透過下列服務監控客服人員活動： + **AWS CloudTrail** — 客服人員工作階段事件會記錄在 CloudTrail 中。您可以檢視客服人員何時連線、他們使用哪些工具，以及工作階段何時結束。工具呼叫是資料事件，需要您設定線索來記錄資料事件。如需詳細資訊，請參閱《*CloudTrail 使用者指南*》中的[記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)。 + **CloudWatch** — CloudWatch 提供代理程式工作階段的操作指標。 + **Amazon S3** — 如果您設定螢幕擷取畫面儲存，則在您指定的 Amazon S3 儲存貯體中提供客服人員工作階段期間擷取的螢幕擷取畫面。螢幕擷取畫面會以下列金鑰格式儲存： ``` agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png ``` 路徑中的 UUID 是 WorkSpaces 應用程式串流工作階段 ID。 ## 開始使用 若要開始使用 WorkSpaces 應用程式 MCP 伺服器，請參閱 [開始為客服人員提供 WorkSpaces 應用程式的存取權](getting-started-agent-access.md)。