amazon-workspaces-agent-access

Amazon WorkSpaces Applications — エージェントアクセス

管理対象の Agent Access MCP サーバーを介して、Amazon WorkSpaces Applications（AppStream 2.0）上のリモート Windows デスクトップに AI エージェントを接続し、それらのデスクトップを確実に操作するためのドメイン知識です。

仕組み: Agent Access は MCP 専用です。デスクトップツールを呼び出す AWS CLI／SDK コマンドはありません。エージェントは、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、フリート／スタックの設定）にのみ使用します。SigV4 署名は mcp-proxy-for-aws が処理します。

推奨セットアップ: トランスポートには mcp-proxy-for-aws（Python）を使用します。各リクエストに署名し、DELETE のライフサイクルを管理します。Streamable HTTP と SigV4 をサポートする MCP クライアントであれば、どれでも使用できます。AWS CLI／SDK の セットアップ手順（create-streaming-url、スタック／フリートの設定）の実行には、サンドボックスでの実行と監査ログ記録が可能な AWS MCP サーバーを推奨します。

ガードレール — このスキルのファイルが置かれている場所（MCP とローカルインストール）

このスキルは 2 通りの方法で読み込めます。それぞれ、スキルに同梱されたファイルの参照先が異なります。リファレンスを読む前に、スキルがどのように読み込まれたかを確認してください。

• AWS MCP の retrieve_skill ツール経由で読み込まれた場合: スキルはローカルのファイルシステムにインストールされていません。各リファレンスは、file パラメーター（例：file="references/connection-setup.md"）を指定して retrieve_skill 経由で取得し、返された内容を使用する必要があります。これらのパスはディスク上に存在しないため、ローカルで file_read してはいけません。
• ローカルにインストールされている場合（例：.kiro/skills/amazon-workspaces-agent-access/ または ~/.claude/skills/amazon-workspaces-agent-access/）：相対パスを使い、ローカルのスキルディレクトリからファイルを読み込みます。

この違いが適用されるのは、スキルに同梱されたファイルのみです。ユーザーデータとセッションのアーティファクトは、常にユーザーの作業ディレクトリから読み書きします。retrieve_skill を介して顧客データを取得または書き込みしないでください。

エージェントが誤りやすい重要事項（詳細に回答する前にリファレンスを読み込んでください）

これらは 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 ツールだけです。エージェントは、返された状態が CONNECTED になるまで connection_status を繰り返し呼び出します。その後に限り、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",  # ご利用のフリートのリージョンを使用してください
        aws_service="agentaccess-mcp", aws_region="us-east-1",  # リージョンはフリートと一致する必要があります（一致しない場合は 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 ヘッダーを使用します。ドメイン参加済みのフリートでは、代わりに SAML アサーションとスタック ARN を、MCP の _meta キー aws.agentaccess/workspacesApplicationsSamlAssertion および aws.agentaccess/workspacesApplicationsStackArn で渡します。（詳細：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 も ENABLED にする必要があります。（詳細：enabling-agent-access.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> ツールとして公開する。ファイル／Web 関連のタスクには転送ツールを優先する	tool-forwarding.md
セッションのライフサイクル — クリーンアップ、削除時の有効期限切れ、アイドルタイムアウト、1 セッションにつき 1 エージェント	session-lifecycle.md
エラーをデバッグする（正確な文字列 → 原因 → 解決策）：dcv session not ready、client_disconnected、400/401/403、Unknown tool	troubleshooting.md

セキュリティに関する考慮事項

• エージェントは呼び出し元の AWS ID で動作します。 すべての MCP リクエストはサービス agentaccess-mcp を使用して SigV4 署名され、デスクトップセッションはその認証情報で実行されます。エージェントが呼び出す特定の agentaccess-mcp アクション（例：InvokeMcp、GetScreenshot、LeftClick、TypeText）のみを許可し、agentaccess-mcp:StackArn 条件キーで対象を絞り込んでください。一律の agentaccess-mcp:* や Resource: * は避けてください。長期間有効なユーザーより IAM ロールを優先してください。（アクションの一覧と例：connection-setup.md → IAM permissions）
• スクリーンショットには機密データが含まれる可能性があります。 COMPUTER_VISION はデスクトップに表示されているものをすべてキャプチャします。スクリーンショットには個人を特定できる情報や秘密情報が含まれる可能性があるものとして扱ってください。スクリーンショットの保存を有効にする場合、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 documentation と AWS security best practices を参照してください。

注： リージョン別エンドポイント、機能の提供状況、クォータは変更されます。正確性が重要な場合は、現在の Agent Access MCP server documentation で確認してください。参照資料では、間違いやすい値や注意点に重点を置いています。