Get started providing agents with access to WorkSpaces Applications

To enable AI agents to operate desktop applications through Amazon WorkSpaces Applications, you create a stack with access enabled for agents, generate a streaming URL, and connect your agent to the managed MCP service.

If you are setting up agent access for the first time, you can use the Build Your First Agent quick-start experience. You can also follow the steps in this topic to configure agent access manually. The quick-start experience is available in the GitHub repository — sample-code-for-workspaces-agent-access.

This tutorial takes approximately 15 minutes to complete.

In this tutorial, you complete the following tasks:

Prerequisites

Before you begin, make sure you have the following:

Step 1: Create a stack with agent access enabled

Create a WorkSpaces Applications stack with agent access enabled to allow AI agents to interact with desktop applications.

Using the AWS Management Console

Using the AWS CLI

Run the following command to create a stack with agent access enabled:

aws appstream create-stack \
    --name your-stack-name \
    --agent-access-config '{
        "Settings": [
            {"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
            {"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"}
        ],
        "ScreenResolution": "W_1280xH_720",
        "ScreenImageFormat": "PNG"
    }'

To also enable screenshot storage, add the S3BucketArn and ScreenshotsUploadEnabled parameters:

aws appstream create-stack \
    --name your-stack-name \
    --agent-access-config '{
        "Settings": [
            {"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
            {"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"}
        ],
        "ScreenResolution": "W_1280xH_720",
        "ScreenImageFormat": "PNG",
        "S3BucketArn": "arn:aws:s3:::your-bucket-name",
        "ScreenshotsUploadEnabled": true
    }'

After you create the stack, associate it with a fleet. Agents cannot connect to a stack that does not have an associated fleet.

aws appstream associate-fleet \
    --stack-name your-stack-name \
    --fleet-name your-fleet-name

Step 2: Generate a streaming URL

Create a streaming URL using the standard WorkSpaces Applications CreateStreamingURL API. You don't need agent-specific parameters. The stack's agent access configuration determines the agent-specific behavior.

Using the AWS Management Console

Using the AWS CLI

Run the following command to generate a streaming URL:

aws appstream create-streaming-url \
    --stack-name your-stack-name \
    --fleet-name your-fleet-name \
    --user-id your-agent-id \
    --validity 3600

The response includes a StreamingURL that you pass to your agent in the next step. The URL is valid for the duration specified by the --validity parameter.

Step 3: Connect your agent to the MCP service

Your agent connects to the managed MCP service at the following fixed endpoint:

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

The connection uses SigV4 signing with the service name agentaccess-mcp. You pass the streaming URL from Step 2 as a header on every MCP request.

The following example shows how to establish the connection using 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,
    },
)

After the agent connects, it can use the MCP tools to enter text, choose buttons, and take screenshots of the desktop.

Step 4: Verify agent activity

You can verify agent activity using the following AWS services:

Step 5: Clean up resources

To avoid ongoing charges, delete the stack you created in this tutorial. You must stop the fleet and disassociate it from the stack before you can delete the stack. Optionally, you can also delete the fleet.

Using the AWS Management Console

Using the AWS CLI

Run the following commands to clean up resources:

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

(Optional) To also delete the fleet after it has stopped:

aws appstream delete-fleet \
    --name your-fleet-name