amazon-workspaces-agent-access

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Amazon WorkSpaces Applications — Agent Access

Domain expertise for connecting AI agents to remote Windows desktops on Amazon WorkSpaces Applications (AppStream 2.0) via the managed Agent Access MCP server, and for driving those desktops reliably.

How it works: Agent Access is MCP-only — there is no AWS CLI/SDK command that calls the desktop tools. Agents connect to

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

over Streamable HTTP, SigV4-signed with service name

agentaccess-mcp

, and call MCP tools (

screenshot

left_click

type_text

, ...) to drive the desktop. The AWS CLI/SDK is used only for setup —

appstream create-streaming-url

, fleet/stack configuration.

mcp-proxy-for-aws

handles the SigV4 signing.

Recommended setup: use

mcp-proxy-for-aws

(Python) as the transport; it signs each request and manages the DELETE lifecycle. Any MCP client that supports Streamable HTTP + SigV4 works. When running the AWS CLI/SDK setup steps (create-streaming-url, stack/fleet configuration), the AWS MCP server is recommended for sandboxed execution and audit logging.

本技能提供专业指导，帮助AI代理通过托管的Agent Access MCP服务器连接到Amazon WorkSpaces Applications（AppStream 2.0）上的远程Windows桌面，并实现对这些桌面的可靠驱动。

工作原理： Agent Access是仅支持MCP的服务——没有AWS CLI/SDK命令可直接调用桌面工具。代理通过可流式传输的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签名。

推荐配置： 使用

mcp-proxy-for-aws

（Python）作为传输层；它会为每个请求签名并管理DELETE生命周期。任何支持可流式传输HTTP + SigV4的MCP客户端均可使用。当运行AWS CLI/SDK 配置步骤（创建流式URL、堆栈/集群配置）时，推荐使用AWS MCP服务器进行沙箱执行和审计日志记录。

Guardrail — where this skill's own files live (MCP vs local install)

防护规则——本技能文件的存储位置（MCP vs 本地安装）

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference:

Loaded through the AWS MCP
retrieve_skill
tool: The skill is not installed on the local filesystem. You MUST fetch each reference via
```
retrieve_skill
```
with the
```
file
```
parameter (e.g.
```
file="references/connection-setup.md"
```
), and use the returned content. Do NOT
```
file_read
```
these paths locally — they do not exist on disk.

Installed locally (e.g.

.kiro/skills/amazon-workspaces-agent-access/

~/.claude/skills/amazon-workspaces-agent-access/

): Read files from the local skill directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write customer data through

retrieve_skill

本技能可通过两种方式加载，其捆绑文件的读取路径不同。在查阅参考文档前，请先确定技能的加载方式：

通过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

获取或写入客户数据。

Key facts agents get wrong (load the reference before answering in detail)

代理容易出错的关键要点（详细解答前请先查阅参考文档）

These are HTTP headers / metadata on the MCP connection — not tool parameters, and there is no

connect_to_desktop

tool. Do not invent tools or parameters; the desktop tools are exactly those in tools-reference.md.

Connect mode. Selected by the X-Amzn-AgentAccess-Connect-Mode
HTTP header (value

BLOCKING

, the default, or

POLLING

) — sent on the MCP request alongside the streaming-URL/SAML auth. It is NOT a JSON tool argument.

❌ WRONG (common hallucination): calling a
```
connect_to_desktop
```
tool with a
```
connection_mode: "POLLING"
```
parameter, or a
```
session_id
```
/
```
application_id
```
/
```
user_id
```
argument. None of those exist.

✅ RIGHT: set the

X-Amzn-AgentAccess-Connect-Mode: POLLING

header. Then

tools/list

initially returns only the

connection_status

tool; the agent calls

connection_status

repeatedly until its returned state is

CONNECTED

, and only then does

tools/list

return the full desktop tool set (

screenshot

left_click

, ...). (details: connection-modes.md)

python

# Correct POLLING usage — the mode is an HTTP header on the MCP connection:
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.us-east-1.api.aws/mcp",  # use YOUR fleet's region
    aws_service="agentaccess-mcp", aws_region="us-east-1",  # region must match the fleet (else 400)
    headers={
        "X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
        "X-Amzn-AgentAccess-Connect-Mode": "POLLING",   # header, not a tool arg
    },
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # tools/list now returns ONLY connection_status until the desktop is up:
        while json.loads((await session.call_tool("connection_status", {})).content[0].text)["state"] != "CONNECTED":
            await asyncio.sleep(2)
        tools = await session.list_tools()   # now the full desktop tool set

Streaming session (non-domain-joined) is the
```
X-Amzn-AgentAccess-Streaming-Session-Url
```
header. Domain-joined fleets instead pass the SAML assertion + stack ARN via MCP
```
_meta
```
keys
```
aws.agentaccess/workspacesApplicationsSamlAssertion
```
and
```
aws.agentaccess/workspacesApplicationsStackArn
```
. (details: connection-setup.md)
Expire-on-delete is the
```
X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete
```
header (
```
true
```
/
```
false
```
; default
false
). Expiry happens on the client's explicit HTTP
```
DELETE
```
—
```
mcp-proxy-for-aws
```
sends it automatically on clean close. (details: session-lifecycle.md)

Forwarded tools are namespaced by server:

forwarded___<server-name>___<tool-name>

(e.g.

forwarded___filesystem___read_file

) — not

forwarded___<tool-name>

. (details: tool-forwarding.md)

COMPUTER_INPUT
requires
COMPUTER_VISION
to also be ENABLED in the stack's
```
AgentAccessConfig
```
. (details: enabling-agent-access.md)

这些是MCP连接的HTTP头/元数据——并非工具参数，且不存在

connect_to_desktop

工具。请勿虚构工具或参数；桌面工具完全与tools-reference.md中列出的一致。

连接模式：通过**

X-Amzn-AgentAccess-Connect-Mode

HTTP头选择（值为
BLOCKING
，默认值，或
POLLING
）——与流式URL/SAML认证一起在MCP请求中发送。它不是**JSON工具参数。

❌ 错误（常见幻觉）：调用带有
```
connection_mode: "POLLING"
```
参数或
```
session_id
```
/
```
application_id
```
/
```
user_id
```
参数的
```
connect_to_desktop
```
工具。这些均不存在。

✅ 正确：设置

X-Amzn-AgentAccess-Connect-Mode: POLLING

头。此时

tools/list

最初仅返回**

connection_status

工具**；代理需反复调用

connection_status

，直到其返回状态为

CONNECTED

，只有此时

tools/list

才会返回完整的桌面工具集（

screenshot

、

left_click

等）。（详情：connection-modes.md）

python

# Correct POLLING usage — the mode is an HTTP header on the MCP connection:
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.us-east-1.api.aws/mcp",  # use YOUR fleet's region
    aws_service="agentaccess-mcp", aws_region="us-east-1",  # region must match the fleet (else 400)
    headers={
        "X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
        "X-Amzn-AgentAccess-Connect-Mode": "POLLING",   # header, not a tool arg
    },
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # tools/list now returns ONLY connection_status until the desktop is up:
        while json.loads((await session.call_tool("connection_status", {})).content[0].text)["state"] != "CONNECTED":
            await asyncio.sleep(2)
        tools = await session.list_tools()   # now the full desktop tool set

流式会话（非域加入）使用

X-Amzn-AgentAccess-Streaming-Session-Url

头。域加入集群则通过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）
COMPUTER_INPUT
需要同时启用
COMPUTER_VISION
：需在堆栈的
```
AgentAccessConfig
```
中启用两者。（详情：enabling-agent-access.md）

Routing

路由指引

User need	Read
Enable agent access on a stack ( `AgentAccessConfig` : COMPUTER_INPUT/COMPUTER_VISION/FORWARD_MCP_TOOLS, screen resolution/format, prerequisites) — the admin setup step before any agent can connect	enabling-agent-access.md
Connect an agent to the MCP server — endpoint, SigV4, streaming URL (non-domain-joined), or Active Directory SAML/Domain Join	connection-setup.md
Choose BLOCKING vs POLLING; poll `connection_status` until the desktop is ready	connection-modes.md
The computer-use tool set (mouse, keyboard, screenshot) and their parameters	tools-reference.md
Automate reliably — screenshot budget, action batching, trusting UI actions, coordinate planning, dialog recovery	automation-best-practices.md
Expose your own MCP servers on the fleet as `forwarded___<server>___<tool>` tools; prefer forwarded tools for file/web tasks	tool-forwarding.md
Session lifecycle — cleanup, expire-on-delete, idle timeout, one-agent-per-session	session-lifecycle.md
Debug an error (exact string → cause → fix): `dcv session not ready` , `client_disconnected` , 400/401/403, `Unknown tool`	troubleshooting.md

用户需求	查阅文档
在堆栈上启用代理访问（ `AgentAccessConfig` ：COMPUTER_INPUT/COMPUTER_VISION/FORWARD_MCP_TOOLS、屏幕分辨率/格式、前提条件）——这是代理能够连接前的管理员配置步骤	enabling-agent-access.md
将代理连接到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
会话生命周期——清理、删除即过期、空闲超时、单代理单会话	session-lifecycle.md
调试错误（错误字符串→原因→修复）： `dcv session not ready` 、 `client_disconnected` 、400/401/403、 `Unknown tool`	troubleshooting.md

Security Considerations

安全注意事项

The agent acts under the caller's AWS identity. Every MCP request is SigV4-signed with service
```
agentaccess-mcp
```
; the desktop session runs with those credentials. Grant only the specific
```
agentaccess-mcp
```
actions the agent calls (e.g.
```
InvokeMcp
```
,
```
GetScreenshot
```
,
```
LeftClick
```
,
```
TypeText
```
) and scope them with the
```
agentaccess-mcp:StackArn
```
condition key — avoid a blanket
```
agentaccess-mcp:*
```
or
```
Resource: *
```
. Prefer IAM roles over long-lived users. (Full action list + example: connection-setup.md → IAM permissions.)
Screenshots can capture sensitive data.
```
COMPUTER_VISION
```
captures whatever is on the desktop — treat screenshots as potentially containing PII or secrets. If screenshot storage is enabled, the S3 bucket must enforce encryption at rest and in transit and least-privilege access: grant the AppStream service principal only what it needs and the connecting agent only
```
s3:PutObject
```
(see enabling-agent-access.md).
Enable only the capabilities you need.
```
COMPUTER_INPUT
```
,
```
COMPUTER_VISION
```
, and
```
FORWARD_MCP_TOOLS
```
are independent — do not enable input/forwarding on stacks that only need vision.
Tool forwarding executes code on the fleet. Forwarded MCP servers run on the instance under the session context. Install only trusted servers system-wide, gate with
```
FORWARD_MCP_TOOLS
```
, and scope the
```
CallForwardedTool
```
IAM action by
```
agentaccess-mcp:StackArn
```
(see tool-forwarding.md).
Keep a human in the loop where warranted.
```
UserControlMode: VIEW_STOP
```
lets an observer watch the live session and stop the agent. Treat agent-driven desktop actions as capable of arbitrary UI operations.
Audit with CloudTrail. Agent session events are logged; tool calls are CloudTrail data events and require a trail configured to log them. Create a trail with
```
agentaccess-mcp
```
data events enabled, encrypt it with SSE-KMS, and add CloudWatch alarms for anomalous patterns (e.g. high screenshot volume, unexpected
```
TypeText
```
, repeated auth failures). If screenshot storage is enabled, turn on S3 server access logging for the bucket.
Protect federation material. For domain-joined (SAML) fleets, safeguard the IdP signing certificate and the IAM SAML provider/role trust policy, and do not log the SAML assertion. Traffic is HTTPS + SigV4 — never disable TLS verification.
Treat typed input as potentially sensitive.
```
type_text
```
can enter secrets (passwords, tokens); these may then appear in screenshots, screenshot-storage S3, and CloudTrail data events. Avoid typing long-lived secrets into the desktop where possible, and restrict who can read those sinks.
Refer to the current Agent Access documentation and AWS security best practices for the latest guidance.

Note: Regional endpoints, feature availability, and quotas change. When precision matters, confirm against the current Agent Access MCP server documentation. The references focus on the values and gotchas that are easy to get wrong.

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

注意： 区域端点、功能可用性和配额会发生变化。如需精确信息，请对照最新的Agent Access MCP服务器文档确认。参考文档重点关注容易出错的参数和注意事项。