amazon-workspaces-agent-access

Q: How do I install amazon-workspaces-agent-access?

Run npx skills add https://github.com/aws/agent-toolkit-for-aws --skill amazon-workspaces-agent-access in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/amazon-workspaces-agent-access/ (personal) or .claude/skills/amazon-workspaces-agent-access/ (project).

by awsAI & Agents

Connects AI agents to remote Windows desktop applications on Amazon WorkSpaces Applications (AppStream 2.0) through the managed Agent Access MCP server, and guides reliable desktop automation. Covers connecting an agent to the MCP endpoint (SigV4, streaming URL, and Active Directory SAML/Domain Join), BLOCKING vs POLLING connect modes, the computer-use tools (screenshot, click, type, key, scroll), screenshot-budget and action-batching discipline, MCP tool forwarding (forwarded tools), session lifecycle and expire-on-delete, and troubleshooting connection errors. Use when building or debugging an agent that drives a remote Windows desktop or GUI application via WorkSpaces Applications / AppStream — including "dcv session not ready", "clientdisconnected", 400 signing-region, POLLING/connectionstatus, SAML assertion, or forwarded tool questions. Not for Amazon WorkSpaces Personal/Core virtual desktops or general AppStream fleet administration unrelated to agent access.

Installs: 1.8K
Last 24h: +39
Trending rank: #3947
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/aws/agent-toolkit-for-aws --skill amazon-workspaces-agent-access

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads amazon-workspaces-agent-access automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

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

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/ or ~/.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.

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)

# 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)

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

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.

FAQ

What does the amazon-workspaces-agent-access skill do?

How do I install amazon-workspaces-agent-access?

Run npx skills add https://github.com/aws/agent-toolkit-for-aws --skill amazon-workspaces-agent-access in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/amazon-workspaces-agent-access/ (personal) or .claude/skills/amazon-workspaces-agent-access/ (project).

Which AI agents can use amazon-workspaces-agent-access?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is amazon-workspaces-agent-access safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains amazon-workspaces-agent-access?

It is published by aws in aws/agent-toolkit-for-aws. It has 1,795 recorded installs.

More from aws/agent-toolkit-for-aws

View all →

aws-iam

aws/agent-toolkit-for-aws

Provides verified corrections for IAM behaviors that AI agents frequently get wrong — policy evaluation edge cases, trust policy gotchas, STS session limits, Organizations quirks, and SAML/MFA specifics. Also provides structured workflows for IAM role management and baseline policy generation from application source code or a Terraform plan JSON. Covers condition operator safety (ForAnyValue/ForAllValues with Null checks), bucket policy deny patterns (VPC endpoint restrictions, org paths), confused deputy protection, and service role creation for AWS services (Glue, CloudTrail, Lambda, ECS, etc.) with aws:SourceAccount/aws:SourceArn trust conditions. Applies when creating IAM roles, writing IAM or bucket policies, generating policies from application source code or a Terraform plan JSON, working with STS, Organizations, or condition operators, or any task needing a service or execution role. Does not cover non-IAM authorization like Cognito user-pool policies or app-level RBAC.

OfficialDevOps & Cloud10.3K installs

aws-serverless

aws/agent-toolkit-for-aws

Routes serverless requests to a compute form factor and the skill that owns it. Applies first to Lambda, API Gateway, EventBridge, Step Functions and event-driven work while the compute, orchestration or integration choice is open — API backends, webhooks, jobs, cron, queue/stream consumers, durable workflows, event routing, Step Functions vs Durable Functions, and Pipes vs native event source mappings for queues and streams. Decides Event Functions on-demand vs Managed Instances, Web Functions, MicroVMs, EventBridge rules/Scheduler/Pipes/bus, HTTP vs REST API. Owns shared Lambda references (cold starts, SnapStart, concurrency, event sources, function URLs, throttling, troubleshooting). Defers to the specialized skill once a request commits to one form factor or service, or describes its defining feature, even unnamed (durable checkpointing and automatic step retries, Firecracker sandbox, managed instances, Node.js server). Not for EC2, ECS/EKS/Fargate or Amplify hosting.

OfficialDevOps & Cloud10.2K installs

aws-observability

aws/agent-toolkit-for-aws

Builds, configures, debugs, and optimizes AWS observability - operator-symptom questions and detecting Omni vs classic CloudWatch. CloudWatch on an already-reporting service: Log Insights, metric/composite/anomaly alarms, custom metrics/EMF, dashboards, X-Ray/ADOT tracing, canaries, CloudTrail, Dynamic Instrumentation (live breakpoints/snapshots), the Application Signals service map, and fleet health views. CloudWatch Omni on an existing Space: SQL over logs and traces, PromQL over metrics, Omni dashboards, Omni alerts, context graph for root cause, programmatic/IaC access (API/SDK/CLI/CloudFormation), driving Omni from a coding agent or skills, and evaluating AI agent quality from traces - on-demand and online scoring of live traffic, readback, custom evaluators. For first-time setup - creating an Omni Space, granting access, ingestion, or ADOT instrumentation for Application Signals (ServiceEvents, CI/CD metadata) or Omni - use setting-up-cloudwatch-observability. Not for app logging

OfficialDevOps & Cloud10K installs

aws-cdk

aws/agent-toolkit-for-aws

Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.

OfficialDevOps & Cloud9.5K installs

aws-containers

aws/agent-toolkit-for-aws

Builds and deploys containerized workloads on Elastic Kubernetes Service (EKS), Elastic Container Service (ECS), Fargate, and ECR (Elastic Container Registry). Covers general EKS knowledge, Karpenter, AWS Load Balancer Controller and leveraging various open source Kubernetes projects with EKS. Covers general ECS knowledge, task definitions, Fargate services, ECS Exec, ECS Express Mode and ECS Managed Instances. Covers general Elastic Beanstalk knowledge, Elastic Beanstalk configuration and platforms supported by Elastic Beanstalk. Covers general ECR knowledge, ECR repository setup and lifecycle policies. Includes recommending, enabling, and reading Amazon ECS Action Logs to troubleshoot control-plane failures (deployment rollback/circuit-breaker, task placement, scaling, task replacement). Applies when deploying, debugging, or optimizing containers on AWS. Should be used instead of relying on internal knowledge for these services.

OfficialDevOps & Cloud9.5K installs

aws-billing-and-cost-management

aws/agent-toolkit-for-aws

Analyze AWS costs, find savings, manage budgets, evaluate Savings Plans and Reserved Instances, right-size EC2/Lambda/RDS/EBS with Compute Optimizer, look up service pricing, query CUR with Athena, detect cost anomalies, scope costs to billing views, and monitor Free Tier usage. Triggers on: AWS bill, cost analysis, reduce spend, savings plan, reserved instance, right-size, budget alert, cost optimization, pricing, free tier, cost anomaly, CUR, cost audit, billing view, billing view ARN.

OfficialDevOps & Cloud9K installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs

amazon-workspaces-agent-access

Install

Install

Describe the task

Review the result

SKILL.md

Amazon WorkSpaces Applications — Agent Access

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

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

Routing

Security Considerations

FAQ

More from aws/agent-toolkit-for-aws

Popular ai & agents skills