rdp-cli
AI Agent가 RDP 스크린샷과 입력으로 원격 작업을 자동화하는 방법
대상 버전 및 환경: 0.1.2 · Windows / macOS · RDP
연결된 세션에서 시작하기
Mac 연결 안내에 따라 연결하고 JSON의 data.session을 사용합니다. Agent는 명령으로 작업하므로 로컬 뷰어를 열 필요가 없습니다. 사람이 진행 상황을 보고 싶을 때 열면 됩니다.
판단하기 전에 화면 관찰하기
스크린샷을 찍고 data.observation을 읽어 OBSERVATION에 넣습니다. 아래 좌표는 문법 예시일 뿐이므로 실제 클릭 위치는 자신의 화면에서 결정하세요. 연결, 제어권 또는 화면 구성이 바뀌면 다시 관찰해야 합니다.
Windows PowerShell에서는 실행 파일이 있는 폴더로 이동한 뒤 아래 명령의 rdp-cli를 .\rdp-cli.exe로 바꾸세요.
아래 Calc 예시에는 원격 Windows의 LibreOffice Calc와 RDP 드라이브 리디렉션이 필요합니다. 예제 통합 문서를 로컬에 service-activity.xlsx로 저장하세요. 업로드 응답의 data.transfer_id를 TRANSFER_ID로 저장하고 상태가 completed가 될 때까지 기다립니다. 원격 Calc에서 리디렉션 드라이브의 파일을 열고 A20을 선택하세요. 전체 Calc 가이드에서 파일과 예상 결과를 확인할 수 있습니다.
rdp-cli files upload --session SESSION --local ./service-activity.xlsx --path service-activity.xlsx
rdp-cli files status --session SESSION --transfer-id TRANSFER_ID
rdp-cli screenshot --session SESSION --out before.png
rdp-cli click --session SESSION --desktop --x 420 --y 315 --observation OBSERVATION
텍스트를 보내고 결과 확인하기
아래 예시에서는 원격 Calc에서 준비된 통합 문서를 열고 A20 셀을 선택합니다. 새 스크린샷을 확인하고 관찰 토큰을 사용해 완료 메모를 붙여넣습니다. 앱의 저장 버튼으로 저장한 뒤 표시된 결과를 확인하세요.
before.png 응답의 data.observation을 OBSERVATION으로 사용하세요. 클릭 후 clipboard-ready.png를 확인하고 그 응답의 새 data.observation을 NEW_OBSERVATION으로 사용하세요. 마지막으로 result.png에서 텍스트를 확인하세요. 명령 성공만으로 앱이 입력을 반영했다고 판단할 수 없습니다.
이번 붙여넣기에 고유한 PASTE_REQUEST를 정해 응답과 함께 보관하세요. 시간 초과 시 같은 ID로 조회합니다. 화면을 확인하기 전에 다른 ID로 다시 붙여넣지 마세요.
| PNG | data.observation |
|---|---|
| note-focused.png | FOCUSED_OBSERVATION |
| clipboard-ready.png | NEW_OBSERVATION |
rdp-cli screenshot --session SESSION --out note-focused.png
rdp-cli clipboard set --session SESSION --text "결과: 보고서가 완성되어 검토할 수 있습니다." --observation FOCUSED_OBSERVATION
rdp-cli screenshot --session SESSION --out clipboard-ready.png
rdp-cli key --session SESSION --keys CTRL+V --observation NEW_OBSERVATION --request-id PASTE_REQUEST
rdp-cli screenshot --session SESSION --out result.png
rdp-cli로 완료 메모를 붙여넣고 저장한 원격 Calc 보고서.
Calc 예제에는 가상의 서비스 데이터가 사용됩니다. 아래 결과 문서는 해당 언어와 테마의 화면에 대응합니다.
화면에 대응하는 결과 파일: 밝은 테마 · 어두운 테마

원본 스크린샷 보기 — 밝게 ↗ · 원본 스크린샷 보기 — 어둡게 ↗
결과가 불분명하면 상태부터 확인하기
시간 초과가 발생해도 입력은 이미 전송되었을 수 있습니다. 반환된 REQUEST_ID로 작업 상태를 확인하고 화면을 다시 관찰하세요. 저장이나 전송 클릭은 필요함을 확인한 뒤에만 반복합니다. 관찰 값이 오래되었다면 새 스크린샷을 받으세요. 자동으로 로컬 마우스 조작으로 전환하지 않습니다.
rdp-cli operations status --session SESSION --request-id PASTE_REQUEST
검증 가능한 작업 기록 남기기
작업에 필요한 상태와 결과 이미지를 보관하되 민감한 내용이 포함될 수 있음을 고려하세요. 사람은 같은 세션을 열어 일시 정지하거나 제어권을 가져올 수 있습니다. 제어권을 돌려받은 Agent는 현재 화면을 확인한 뒤 계속합니다. RDP 파일 작업에는 업로드, 진행 상태, 다운로드 전용 명령도 있습니다.
관련 글
내 원격 데스크톱에서 시작하기
rdp-cli 다운로드 · 사용하는 플랫폼의 빠른 시작 보기
관련 가이드
rdp-cli의 확장 명령
먼저 rdp-cli --version을 실행하세요. 아래 명령은 agent_execution.contract_version이 1인 빌드가 필요합니다. 이전 버전에서는 위의 단일 작업 방식을 계속 사용할 수 있습니다.
대문자 자리표시자는 실제 반환값으로 바꾸세요. Windows PowerShell에서는 프로그램 폴더에서 .\rdp-cli.exe를 사용하고, macOS·Linux에서는 설치한 명령 또는 실제 실행 파일 경로를 사용합니다.
필요한 영역만 확인
일부 영역이나 축소 이미지를 받아 이전 화면과 비교합니다. 변화가 없으면 이미지를 생략하며 좌표는 원격 화면과의 대응을 유지합니다.
화면 변화와 전송 완료 기다리기
지정 영역의 변화·안정 또는 연결·작업·파일 전송의 지정 상태를 기다립니다. 계속하기 전에 실제 결과도 확인하세요.
짧은 작업 묶음을 보내고 확인 지점에서 정지
에이전트가 결정한 동작을 묶고 새 관찰과 체크포인트를 넣습니다. 오류나 제어권 변경 시 후속 단계를 멈추며 이미 보낸 동작은 되돌리지 않습니다.
진행 상황을 기록하고 확인 후 이어가기
작업 진행, 체크포인트, 선택한 화면을 저장하고 로컬 보고서로 내보냅니다. 중단 후 완료 내용을 확인하고 결과를 모르는 동작을 반복하지 않은 채 새 단계로 진행합니다.
아래 JSON을 표준 입력으로 batch에 전달하세요. 이 예제는 화면을 관찰하고 체크포인트에서 멈추기만 합니다. 현재 화면을 확인한 뒤 실제 입력 작업을 추가하세요. tasks create가 반환한 작업 ID를 TASK_ID에 넣으면 이 배치가 같은 작업 기록에 저장됩니다.
rdp-cli screenshot --session SESSION --max-width 640
rdp-cli screenshot --session SESSION --region X,Y,WIDTH,HEIGHT --max-width 640
rdp-cli wait --session SESSION --condition changed --region X,Y,WIDTH,HEIGHT --timeout-ms 10000
rdp-cli tasks create --session SESSION --title "Review result"
rdp-cli batch --session SESSION --task TASK_ID --steps-stdin --request-id UNIQUE_REQUEST_ID
{"version":1,"steps":[{"id":"look","command":"observe","arguments":{"max-width":640}},{"id":"review","command":"checkpoint"}]}