agent-rdp

agent-rdp による Windows リモートデスクトップ制御

クイックスタート

agent-rdp connect --host <ip> -u <user> -p <pass> --enable-win-automation
agent-rdp automate snapshot -i              # See interactive elements
agent-rdp automate click "@e5"              # Click button by ref
agent-rdp automate fill "@e7" "Hello"       # Type into field
agent-rdp disconnect

基本的なワークフロー

1. 自動化を有効にして接続します：agent-rdp connect --host <ip> -u <user> -p <pass> --enable-win-automation
2. スナップショットを取得します：agent-rdp automate snapshot -i（参照付きのアクセシビリティツリーを取得）
3. 操作します：agent-rdp automate click @e5 または agent-rdp automate fill @e7 "text"
4. 繰り返します：スナップショット → 操作 → スナップショット → 操作…

トラブルシューティング

-i を指定したスナップショットに要素がない場合

-i フラグを外してみてください。一部の要素はインタラクティブとしてマークされていなくても、操作できる場合があります：

agent-rdp automate snapshot              # Full tree, no filtering
agent-rdp automate snapshot -d 5         # Limit depth if too large

アクセシビリティツリーに要素がまったくない場合

一部の UI 要素（WebView のコンテンツ、一部のダイアログ、トースト通知など）はアクセシビリティツリーに表示されません。最後の手段として OCR を使用します：

1. スクリーンショットを撮影し、必要なものを特定します：agent-rdp screenshot -o screen.png
2. locate を使って座標を検索します：agent-rdp locate "Button Text"
3. 返された座標を使ってクリックします：agent-rdp mouse click <x> <y>

コマンド

接続

agent-rdp connect --host 192.168.1.100 -u Admin -p secret
agent-rdp connect --host 192.168.1.100 -u Admin --password-stdin  # Read password from stdin
agent-rdp connect --host 192.168.1.100 --width 1920 --height 1080
agent-rdp connect --host 192.168.1.100 --drive /tmp/share:Share   # Map local directory
agent-rdp disconnect

スクリーンショット

agent-rdp screenshot                      # Save to ./screenshot.png
agent-rdp screenshot -o desktop.png       # Save to specific file
agent-rdp screenshot --format jpeg        # JPEG format

マウス

agent-rdp mouse click 500 300             # Left click at (500, 300)
agent-rdp mouse right-click 500 300       # Right click
agent-rdp mouse double-click 500 300      # Double click
agent-rdp mouse move 100 200              # Move cursor
agent-rdp mouse drag 100 100 500 500      # Drag from (100,100) to (500,500)

キーボード

agent-rdp keyboard type "Hello World"     # Type text (supports Unicode)
agent-rdp keyboard press "ctrl+c"         # Key combination
agent-rdp keyboard press "alt+tab"        # Switch windows
agent-rdp keyboard press "ctrl+shift+esc" # Task manager
agent-rdp keyboard press "win+r"          # Run dialog
agent-rdp keyboard press enter            # Single key (use press, not key)
agent-rdp keyboard press escape
agent-rdp keyboard press f5

スクロール

agent-rdp scroll up --amount 3            # Scroll up 3 notches
agent-rdp scroll down --amount 5          # Scroll down 5 notches
agent-rdp scroll left
agent-rdp scroll right

クリップボード

agent-rdp clipboard set "Text to paste"   # Set clipboard (paste on Windows)
agent-rdp clipboard get                   # Get clipboard (after copy on Windows)

ドライブのマッピング

# Map at connect time
agent-rdp connect --host <ip> -u <user> -p <pass> --drive /local/path:DriveName

# List mapped drives
agent-rdp drive list

セッション管理

agent-rdp session list                    # List active sessions
agent-rdp session info                    # Current session info
agent-rdp --session work connect ...      # Named session
agent-rdp --session work screenshot       # Use named session

待機

agent-rdp wait 2000                       # Wait 2 seconds

locate（OCR）

agent-rdp locate "Cancel"                 # Find lines containing "Cancel"
agent-rdp locate "Save*" --pattern        # Glob pattern matching
agent-rdp locate --all                    # Get all text on screen
agent-rdp locate "OK" --json              # JSON output with coordinates

クリック用のテキスト行と、バウンディングボックスおよび中心座標を返します：

Found 1 line(s) containing 'Cancel':
  'Cancel' at (650, 420) size 45x14 - center: (672, 427)

To click the first match: agent-rdp mouse click 672 427

UI オートメーション

# Connect with automation enabled
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --enable-win-automation

# Snapshot - get accessibility tree (refs always included)
agent-rdp automate snapshot                # Full desktop tree
agent-rdp automate snapshot -i             # Interactive elements only
agent-rdp automate snapshot -c             # Compact (remove empty elements)
agent-rdp automate snapshot -d 5           # Limit depth to 5 levels
agent-rdp automate snapshot -s "~*Notepad*"# Scope to a window/element
agent-rdp automate snapshot -f             # Start from focused element
agent-rdp automate snapshot -i -c -d 3     # Combine options

# Pattern-based element operations (use selectors: @eN, #automationId, .className, or name)
agent-rdp automate click "#SaveButton"    # Click button
agent-rdp automate click "@e5"            # Click by ref number
agent-rdp automate click "@e5" -d         # Double-click (for file list items)
agent-rdp automate select "@e10"          # Select item (SelectionItemPattern)
agent-rdp automate select "@e5" --item "Option 1"  # Select item by name in container
agent-rdp automate toggle "@e7"           # Toggle checkbox (TogglePattern)
agent-rdp automate toggle "@e7" --state on  # Set specific state
agent-rdp automate expand "@e3"           # Expand menu/tree (ExpandCollapsePattern)
agent-rdp automate collapse "@e3"         # Collapse menu/tree
agent-rdp automate context-menu "@e5"     # Open context menu (Shift+F10)
agent-rdp automate focus <selector>       # Focus element
agent-rdp automate get <selector>         # Get element properties

# Text input
agent-rdp automate fill <selector> "text" # Clear and fill text (ValuePattern)
agent-rdp automate clear <selector>       # Just clear

# Scrolling
agent-rdp automate scroll <selector> --direction down --amount 3

# Window operations
agent-rdp automate window list
agent-rdp automate window focus "~*Notepad*"
agent-rdp automate window maximize
agent-rdp automate window minimize
agent-rdp automate window restore
agent-rdp automate window close "~*Notepad*"

# Run commands/apps (best way to open apps)
agent-rdp automate run "notepad.exe"                                        # Open Notepad
agent-rdp automate run "Start-Process ms-settings:" --wait                  # Open Settings
agent-rdp automate run "calc.exe"                                           # Open Calculator
agent-rdp automate run "Get-Process" --wait --process-timeout 5000          # With 5s timeout

# Wait for element
agent-rdp automate wait-for <selector> --timeout 5000
agent-rdp automate wait-for <selector> --state visible

# Status
agent-rdp automate status

セレクターの構文：

• @e5 または @5 - スナップショットの参照番号（e 接頭辞を推奨）
• #SaveButton - オートメーション ID
• .Edit - Win32 クラス名
• ~*pattern* - ワイルドカードを含む名前
• File - 要素名（完全一致）

スナップショットの出力形式：

- Window "Notepad" [ref=e1, id=Notepad]
  - MenuBar "Application" [ref=e2]
    - MenuItem "File" [ref=e3]
  - Edit "Text Editor" [ref=e5, value="Hello"]

JSON 出力

機械可読形式の出力には --json を追加します：

agent-rdp --json clipboard get
agent-rdp --json session info
agent-rdp --json automate snapshot

例：PowerShell を開いてコマンドを実行する

agent-rdp connect --host 192.168.1.100 -u Admin -p secret
agent-rdp wait 3000                       # Wait for desktop
agent-rdp keyboard press "win+r"          # Open Run dialog
agent-rdp wait 1000
agent-rdp keyboard type "powershell"
agent-rdp keyboard press enter
agent-rdp wait 2000                       # Wait for PowerShell
agent-rdp keyboard type "Get-Process"
agent-rdp keyboard press enter
agent-rdp screenshot --output result.png
agent-rdp disconnect

例：マッピングしたドライブ経由でファイルを転送する

# Connect with local directory mapped
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --drive /tmp/transfer:Transfer

# On Windows, access files at \\tsclient\Transfer
agent-rdp keyboard press "win+r"
agent-rdp wait 500
agent-rdp keyboard type "\\\\tsclient\\Transfer"
agent-rdp keyboard press enter

例：UI オートメーションで Notepad を自動化する

# Connect with automation enabled
agent-rdp connect --host 192.168.1.100 -u Admin -p secret --enable-win-automation

# Open Notepad
agent-rdp automate run "notepad.exe"
agent-rdp wait 2000

# Get accessibility snapshot (refs are always included)
agent-rdp automate snapshot -i            # Interactive elements only

# Type text into the edit control (use ref from snapshot)
agent-rdp automate fill "@e5" "Hello from automation!"

# Use File menu to save - expand menu, then invoke menu item
agent-rdp automate expand "File"          # Expand menu (ExpandCollapsePattern)
agent-rdp wait 500
agent-rdp automate click "Save As..."     # Click menu item

# Wait for Save dialog
agent-rdp automate wait-for "#FileNameControlHost" --timeout 5000

# Fill filename and save
agent-rdp automate fill "#FileNameControlHost" "test.txt"
agent-rdp automate click "#1"             # Click Save button

環境変数

export AGENT_RDP_HOST=192.168.1.100
export AGENT_RDP_PORT=3389
export AGENT_RDP_USERNAME=Administrator
export AGENT_RDP_PASSWORD=secret
export AGENT_RDP_SESSION=default
agent-rdp connect    # Uses env vars for connection

WebSocket ストリーミングによるデバッグ

# Enable streaming viewer on port 9224
agent-rdp --stream-port 9224 connect --host 192.168.1.100 -u Admin -p secret

# Open web viewer in browser
agent-rdp view --port 9224

# Or manually access WebSocket at ws://localhost:9224 (broadcasts JPEG frames)

ヒント

自動化が有効な場合は、keyboard type よりも automate fill を優先してください。文字が欠落せず、より高速に入力できます。

アプリケーションを開く

automate run を使って、アプリを直接起動します：

agent-rdp automate run "notepad.exe"
agent-rdp automate run "calc.exe"
agent-rdp automate run "Start-Process ms-settings:" --wait   # Settings
agent-rdp automate run "explorer.exe C:\\"                   # File Explorer

制限事項

重要：自動化タスクを実行する前に、これらの制限事項をよくお読みください。

UI オートメーションでは WebView にアクセスできません

• Windows のスタートメニュー検索、Edge ブラウザーのコンテンツ、Electron アプリのコンテンツ、その他の WebView ベースの UI には、automate snapshot ではアクセスできません。
• 回避策：スタートメニューから移動する代わりに、Win+R（「ファイル名を指定して実行」ダイアログ）または automate run を使ってプログラムを直接起動します。

UI オートメーションでは UAC ダイアログを操作できません

• ユーザーアカウント制御の昇格プロンプトは、UI オートメーションから隔離されたセキュアデスクトップ上で実行されます。
• UAC ダイアログは automate snapshot の出力には表示されません。
• 回避策：locate コマンド（OCR）でボタンのテキストを探し、mouse click で操作します。確実ではありませんが、単純な「はい／いいえ」ダイアログなら動作する場合があります。

OCR（locate）の信頼性は高くありません

• locate コマンドは OCR を使用するため、文字を誤認したり、テキストを見落としたり、不正確な座標を返したりすることがあります。
• UI オートメーションで要素にアクセスできない場合の最後の手段として使用してください。
• 重要なボタンをクリックする前に、必ず座標を確認してください。

スクリーンショットから座標を推定しないでください（Claude のみ）

• コンピューター操作モードではない Claude モデル（Claude Code など）は、ピクセルの数え上げが非常に苦手です。
• スクリーンショットを見て座標を推測しないでください。推定値はおそらく正しくありません。
• 注：Gemini モデルは、一般にピクセル座標の推定が得意です。
• Claude で画像を使った座標検出が必要な場合、ユーザーは Claude の Computer Use Tool を使用するハーネスを実装する必要があります。

UI Automation が失敗した場合の推奨ワークフロー

1. まず、必ず automate snapshot を試してください（-i フラグを付けた場合と付けない場合の両方）。
2. 要素が見つからない場合は、locate "text" を試して OCR で検索してください。
3. locate の出力にある座標を mouse click で使用してください。
4. スクリーンショットを見て座標を推測することは絶対にしないでください。