amazon-workspaces-agent-access

Amazon WorkSpaces Applications — Agent Access

连接 AI Agent 与 Amazon WorkSpaces Applications（AppStream 2.0）上的远程 Windows 桌面，并可靠地操作这些桌面的领域专业知识。本技能使用托管的 Agent Access MCP 服务。

**工作原理：**Agent Access 仅支持 MCP——没有可调用桌面工具的 AWS CLI/SDK 命令。Agent 通过 Streamable HTTP 连接到 https://agentaccess-mcp.{region}.api.aws/mcp，使用服务名称 agentaccess-mcp 进行 SigV4 签名，并调用 MCP 工具（screenshot、left_click、type_text……）来操作桌面。AWS CLI/SDK 仅用于设置——appstream create-streaming-url、队列/堆栈配置。mcp-proxy-for-aws 负责 SigV4 签名。

**推荐设置：**使用 Python 版 mcp-proxy-for-aws 作为传输层；它会为每个请求签名并管理 DELETE 生命周期。任何支持 Streamable HTTP + SigV4 的 MCP 客户端都适用。在运行 AWS CLI/SDK 设置步骤（create-streaming-url、堆栈/队列配置）时，推荐使用 AWS MCP 服务，以便在沙箱中执行并记录审计日志。

防护措施 — 本技能自身文件的存放位置（MCP 与本地安装）

本技能有两种加载方式，它们会从不同位置解析本技能自带的文件。读取参考资料前，请先确认本技能是如何加载的：

• **通过 AWS MCP 的 retrieve_skill 工具加载：**本技能不会安装在本地文件系统中。你必须通过 retrieve_skill 并使用 file 参数获取每个参考文件（例如 file="references/connection-setup.md"），并使用返回的内容。不要在本地使用 file_read 读取这些路径——它们不存在于磁盘上。
• 本地安装（例如 .kiro/skills/amazon-workspaces-agent-access/ 或 ~/.claude/skills/amazon-workspaces-agent-access/）：使用相对路径从本地技能目录读取文件。

这一区别仅适用于本技能打包的文件。用户数据和会话产物始终从用户的工作目录读取并写入其中。切勿通过 retrieve_skill 获取或写入客户数据。

Agent 容易弄错的关键信息（详细回答前请先加载参考资料）

这些是 MCP 连接上的 HTTP 标头／元数据——不是工具参数，也不存在 connect_to_desktop 工具。请勿编造工具或参数；桌面工具仅限 tools-reference.md 中列出的工具。

• 连接模式。 由 X-Amzn-AgentAccess-Connect-Mode HTTP 标头选择（值为 BLOCKING，这是默认值，或 POLLING）——与流式 URL／SAML 身份验证信息一同在 MCP 请求中发送。它不是 JSON 工具参数。

  • ❌ 错误（常见幻觉）：调用 connect_to_desktop 工具并传入 connection_mode: "POLLING" 参数，或传入 session_id／application_id／user_id 参数。这些参数都不存在。

  • ✅ 正确：设置 X-Amzn-AgentAccess-Connect-Mode: POLLING 标头。此后，tools/list 最初只会返回 connection_status 工具；Agent 会反复调用 connection_status，直到返回的状态为 CONNECTED，然后 tools/list 才会返回完整的桌面工具集（screenshot、left_click……）。（详情：connection-modes.md）

    # 正确使用 POLLING——模式是 MCP 连接上的 HTTP 标头：
    async with aws_iam_streamablehttp_client(
        endpoint="https://agentaccess-mcp.us-east-1.api.aws/mcp",  # 使用你所在区域的 fleet
        aws_service="agentaccess-mcp", aws_region="us-east-1",  # 区域必须与 fleet 匹配（否则返回 400）
        headers={
            "X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
            "X-Amzn-AgentAccess-Connect-Mode": "POLLING",   # 标头，不是工具参数
        },
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            # 桌面启动前，tools/list 现在只会返回 connection_status：
            while json.loads((await session.call_tool("connection_status", {})).content[0].text)["state"] != "CONNECTED":
                await asyncio.sleep(2)
            tools = await session.list_tools()   # 现在返回完整的桌面工具集
    

• 流式会话（非域加入型）使用 X-Amzn-AgentAccess-Streaming-Session-Url 标头。域加入型 fleet 则通过 MCP _meta 键 aws.agentaccess/workspacesApplicationsSamlAssertion 和 aws.agentaccess/workspacesApplicationsStackArn 传入 SAML 断言和堆栈 ARN。（详情：connection-setup.md）

• 删除时过期由 X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete 标头控制（true／false；默认值为 false）。过期操作会在客户端显式发送 HTTP DELETE 时发生——mcp-proxy-for-aws 会在正常关闭时自动发送该请求。（详情：session-lifecycle.md）

• 转发的工具以服务端命名空间区分： forwarded___<server-name>___<tool-name>（例如 forwarded___filesystem___read_file）——不是 forwarded___<tool-name>。（详情：tool-forwarding.md）

• 在堆栈的 AgentAccessConfig 中，COMPUTER_INPUT 还要求启用 COMPUTER_VISION。（详情：enabling-agent-access.md）

路由

用户需求	阅读
在堆栈上启用 Agent 访问权限（AgentAccessConfig：COMPUTER_INPUT/COMPUTER_VISION/FORWARD_MCP_TOOLS、屏幕分辨率/格式、先决条件）——任何 Agent 连接前的管理员设置步骤	enabling-agent-access.md
将 Agent 连接到 MCP 服务——端点、SigV4、流式传输 URL（非域加入设备）或 Active Directory SAML/域加入	connection-setup.md
选择 BLOCKING 还是 POLLING；轮询 connection_status，直到桌面准备就绪	connection-modes.md
计算机操作工具集（鼠标、键盘、屏幕截图）及其参数	tools-reference.md
可靠地实现自动化——屏幕截图预算、操作批处理、信任 UI 操作、坐标规划、对话框恢复	automation-best-practices.md
在设备群上公开你自己的 MCP 服务，作为 forwarded___<server>___<tool> 工具；文件/网页任务优先使用转发工具	tool-forwarding.md
会话生命周期——清理、删除时过期、空闲超时、每个会话仅限一个 Agent	session-lifecycle.md
调试错误（准确字符串 → 原因 → 修复）：dcv session not ready、client_disconnected、400/401/403、Unknown tool	troubleshooting.md

安全注意事项

• Agent 使用调用者的 AWS 身份运行。 每个 MCP 请求都会使用服务 agentaccess-mcp 进行 SigV4 签名；桌面会话使用这些凭证运行。仅授予 Agent 调用的特定 agentaccess-mcp 操作（例如 InvokeMcp、GetScreenshot、LeftClick、TypeText），并使用 agentaccess-mcp:StackArn 条件键限制其范围——避免使用宽泛的 agentaccess-mcp:* 或 Resource: *。优先使用 IAM 角色，而非长期有效的用户。（完整操作列表和示例：connection-setup.md → IAM permissions。）
• 屏幕截图可能捕获敏感数据。 COMPUTER_VISION 会捕获桌面上的所有内容——请将屏幕截图视为可能包含个人身份信息（PII）或机密信息。如果启用了屏幕截图存储，S3 存储桶必须确保静态和传输中加密，并遵循最小权限原则：仅向 AppStream 服务主体授予所需权限，并且仅向连接的 Agent 授予 s3:PutObject 权限（参见 enabling-agent-access.md）。
• 仅启用所需功能。 COMPUTER_INPUT、COMPUTER_VISION 和 FORWARD_MCP_TOOLS 相互独立——如果堆栈只需要视觉功能，请勿启用输入或转发功能。
• 工具转发会在资源池中执行代码。 转发的 MCP 服务会在实例上以会话上下文运行。仅在系统范围内安装可信服务，通过 FORWARD_MCP_TOOLS 控制访问，并使用 agentaccess-mcp:StackArn 限制 IAM 操作 CallForwardedTool 的范围（参见 tool-forwarding.md）。
• 必要时让人工参与监督。 UserControlMode: VIEW_STOP 允许观察者查看实时会话并停止 Agent。请将 Agent 驱动的桌面操作视为可能执行任意 UI 操作。
• 使用 CloudTrail 进行审计。 Agent 会话事件会被记录；工具调用属于 CloudTrail 数据事件，需要配置跟踪以记录这些事件。创建启用了 agentaccess-mcp 数据事件的跟踪，使用 SSE-KMS 对其加密，并为异常模式添加 CloudWatch 警报（例如屏幕截图数量过多、出现意外的 TypeText、反复发生身份验证失败）。如果启用了屏幕截图存储，请为存储桶启用 S3 服务器访问日志记录。
• 保护联合身份验证材料。 对于加入域的（SAML）资源池，请妥善保护 IdP 签名证书和 IAM SAML 提供商／角色信任策略，并且不要记录 SAML 断言。流量使用 HTTPS + SigV4——切勿禁用 TLS 验证。
• 将键入的内容视为可能包含敏感信息。 type_text 可输入机密信息（密码、令牌）；这些内容之后可能出现在屏幕截图、用于存储屏幕截图的 S3 存储桶以及 CloudTrail 数据事件中。尽可能避免在桌面上输入长期有效的机密信息，并限制可读取这些存储目标的人员。
• 请参阅最新的 Agent Access 文档 和 AWS 安全最佳实践，了解最新指南。

注意： 区域端点、功能可用性和配额会发生变化。需要精确的信息时，请以最新的 Agent Access MCP 服务文档 为准。参考资料重点介绍了容易出错的值和注意事项。