Prerequisites
This topic covers what you need in place before an agent can connect: the AWS account and Amazon WorkSpaces Applications fleet that host the desktop session, and the permissions and software your agent uses to reach it. Setting these up first lets your agent authenticate and operate the desktop without interruption.
Supported operating systems
Agent access supports the same operating systems as WorkSpaces Applications. How you get an image depends on the operating system.
| Operating system | Image source | More information |
|---|---|---|
| Windows Server | AWS-provided base images, or bring your own image |
WorkSpaces Applications Base Image and Managed Image Update Release Notes |
| Linux | AWS-provided base images | WorkSpaces Applications Base Image and Managed Image Update Release Notes |
| Windows 11 | Bring Your Own License (BYOL): you supply the image | Bring Your Own Windows Desktop Licenses for Amazon WorkSpaces Applications |
Windows 11 requires additional BYOL setup. For requirements, see Bring Your Own Windows Desktop Licenses for Amazon WorkSpaces Applications.
For image builders, agent access supports Windows Server and Windows 11 (BYOL). Linux image builders aren't supported.
Account, fleet, and image builder requirements
To set up agent access on a stack, you need the following:
-
An AWS account with permissions to create and manage WorkSpaces Applications stacks.
-
An active WorkSpaces Applications fleet (Always-On or On-Demand). If you haven't created a fleet, see Get Started with Amazon WorkSpaces Applications: Set Up With Sample Applications.
-
A stack associated with a fleet. Agents cannot connect to a stack without an associated fleet.
-
If you plan to enable screenshot storage, an Amazon S3 bucket. The bucket policy must grant the AppStream service principal access to list buckets. The agent that connects to the Model Context Protocol (MCP) server must have the
s3:PutObjectpermission on the bucket. -
A fleet running the latest version of the WorkSpaces Applications Agent. This is the streaming software on the image, not the AI agent you build. For more information about updating it, see Keep Your Amazon WorkSpaces Applications Image Up-to-Date. For information about managing agent versions, see Managing agent versions.
To use agent access on an image builder, you need the following:
-
An AWS account with permissions to create and manage WorkSpaces Applications images.
-
An image builder in the
RUNNINGstate. An agent can't connect to an image builder that isn't running. -
If you plan to enable screenshot storage, an Amazon S3 bucket. The bucket policy must grant the AppStream service principal access to list buckets. The agent that connects to the Model Context Protocol (MCP) server must have the
s3:PutObjectpermission on the bucket. -
An image builder whose image uses a WorkSpaces Applications agent released on or after October 25, 2026. If you create the image builder from a WorkSpaces Applications base image, use a base image released on or after November 4, 2026. If the image uses an earlier version, the request to enable agent access fails with an
IncompatibleImageExceptionerror.To check an image, run the following command. In the response,
AppstreamAgentVersionshows the agent version andPublicBaseImageReleasedDateshows when the base image was released.aws appstream describe-images --namesyour-image-nameIf the image is older, use a newer base image, or update the agent on your image. For more information, see WorkSpaces Applications Agent Release Notes, WorkSpaces Applications Base Image and Managed Image Update Release Notes, and Update an Image by Using Managed WorkSpaces Applications Image Updates.
Agent and permissions requirements
To build and connect your agent, you need the following:
-
AWS credentials (environment variables, AWS profile, EC2 instance role, or Lambda execution role) with the following IAM permissions. The agent uses these credentials directly to sign requests to the MCP server:
{ "Sid": "MCP", "Effect": "Allow", "Action": ["agentaccess-mcp:*"], "Resource": "*" }, { "Sid": "AppStream", "Effect": "Allow", "Action": ["appstream:CreateStreamingURL", "appstream:DescribeFleets", "appstream:CreateImageBuilderStreamingURL"], "Resource": "*" }The
agentaccess-mcp:*wildcard includes the following actions:agentaccess-mcp:InvokeMcp: Initialize sessions and discover toolsagentaccess-mcp:GetScreenshot: Capture screen stateagentaccess-mcp:LeftClick: Perform left mouse clickagentaccess-mcp:DoubleClick: Perform double clickagentaccess-mcp:TripleClick: Perform triple clickagentaccess-mcp:RightClick: Perform right mouse clickagentaccess-mcp:MiddleClick: Perform middle mouse clickagentaccess-mcp:TypeText: Type text stringagentaccess-mcp:KeyPress: Press key or key combinationagentaccess-mcp:HoldKey: Hold key for durationagentaccess-mcp:Scroll: Scroll at coordinatesagentaccess-mcp:MovePointer: Move pointer to coordinatesagentaccess-mcp:LeftClickDrag: Perform left click dragagentaccess-mcp:LeftMouseDown: Press and hold left mouse buttonagentaccess-mcp:LeftMouseUp: Release left mouse buttonagentaccess-mcp:CheckConnectionStatus: Check connection status of a streaming sessionagentaccess-mcp:CallForwardedTool: Invoke a forwarded tool on a remote instanceagentaccess-mcp:LaunchApplication: Launch a cataloged application in the current sessionagentaccess-mcp:ToggleAppSwitcher: Open or close the app-switcher overlayagentaccess-mcp:SwitchUser: On an image builder, disconnect the current built-in user and log in as another built-in user (ADMINISTRATOR,TEMPLATE_USER, orTEST_USER)agentaccess-mcp:GetCurrentUser: Return the built-in user that's logged in to an image builder
The
agentaccess-mcp:*wildcard also allowsSwitchUserandGetCurrentUseron every image builder, as any of the three built-in users. To limit an agent on image builders, name the actions and use the condition keys, as in the example policy later in this topic.The agent needs the same
agentaccess-mcppermissions whether it connects to an image builder with a streaming URL or with the image builder name. -
An MCP-compatible agent framework that can send Streamable HTTP requests to the MCP endpoint, authorized in one of two ways:
-
Signature Version 4 (SigV4) signing – The agent signs each request to the MCP server with its AWS credentials.
-
OAuth bearer token – The agent uses OAuth 2.1 authorization through AWS Sign-In to retrieve a short-lived access token, and passes it as a bearer token on each request.
For more information about both authorization methods, see Request authorization. The Strands Agents SDK
provides native MCP client support, or you can use any framework with the mcp-proxy-for-awstransport. -
-
Python 3.10 or later on the machine where your agent runs. Your agent can run on any operating system, independent of the streamed desktop.
To enable or disable agent access, or change its settings on an
existing image builder, you need the
appstream:UpdateImageBuilder permission. This permission is
separate from the agent's permissions.
On an image builder, the agent logs in as one of three built-in Windows
users: ADMINISTRATOR, TEMPLATE_USER, or
TEST_USER. For more information about these users, see Built-in users on image builders. To control which image
builders an agent can use and which built-in users it can log in as, use the
following IAM condition keys:
-
agentaccess-mcp:ImageBuilderArn: The ARN of the image builder. -
agentaccess-mcp:LocalUser: The built-in user that the agent logs in as.
The LocalUser condition key is present only on requests that
log a user in. Use the StringEqualsIfExists operator with it, as
in the example policy later in this topic. With StringEquals,
other requests, such as tools/list, are denied.
We recommend that you restrict the agent to the least-privileged built-in
user that its tasks need. For example, an agent that only tests applications
can log in as TEST_USER.
The following example policy allows an agent to use one image builder and
to log in only as TEST_USER. The second statement lists the
tools that the agent can use on that image builder. Add the other actions
that your agent needs.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ConnectAndSwitchOnlyAsTestUser", "Effect": "Allow", "Action": ["agentaccess-mcp:InvokeMcp", "agentaccess-mcp:SwitchUser"], "Resource": "*", "Condition": { "ArnEquals": { "agentaccess-mcp:ImageBuilderArn": "arn:aws:appstream:region:account-id:image-builder/image-builder-name" }, "StringEqualsIfExists": { "agentaccess-mcp:LocalUser": "TEST_USER" } } }, { "Sid": "DriveTheDesktopOnThatBuilder", "Effect": "Allow", "Action": [ "agentaccess-mcp:GetCurrentUser", "agentaccess-mcp:CheckConnectionStatus", "agentaccess-mcp:GetScreenshot", "agentaccess-mcp:LeftClick", "agentaccess-mcp:TypeText", "agentaccess-mcp:KeyPress" ], "Resource": "*", "Condition": { "ArnEquals": { "agentaccess-mcp:ImageBuilderArn": "arn:aws:appstream:region:account-id:image-builder/image-builder-name" } } } ] }
Limitations
WorkSpaces Applications agent access configurations have the following limitations:
-
VPC endpoints are not supported.
-
Multi-session fleets are not supported.
-
Elastic fleets are not supported.
-
A single session supports only a single AI agent connection.
Agent access on image builders has the following additional limitations:
-
Domain-joined image builders are not supported.
-
App block builders, which you use with elastic fleets, aren't supported.
-
An image builder supports only one AI agent connection at a time.
-
Changes to agent access settings on the image builder cannot be made while the image builder is running. Stop the image builder first to make an update, and it takes effect on the next session.
-
Either the AI agent or a human can provide input on an image builder, but not both at the same time. To switch between agent and human input, stop the image builder, change the setting to enable or disable agent access, and restart the image builder.