Windows 365 for Agents MCP 서버 참조

비고

이 글에서는 표준 하네스로 구동되는 에이전트 또는 에이전트 플로우에서 사용되는 기능에 대해 설명합니다.

Windows 365 for Agents는 Windows 365 클라우드 PC의 완전한 운영 제어를 제공하는 MCP 서버입니다. 이 MCP 서버를 사용해 데스크톱 상호작용(마우스, 키보드, 스크린 캡처, 명령 실행), Microsoft Edge를 통한 브라우저 자동화, Windows UI 자동화를 통한 의미 UI 검사를 통해 실제 Windows 환경을 구동합니다.

비고

브라우저 자동화는 Microsoft Edge에서 작동합니다. 엣지는 첫 번째 브라우저 툴 호출 시 자동으로 실행됩니다. focus_browser 또한 크롬이나 파이어폭스를 대상으로 할 수 있지만, DOM 수준의 브라우저 도구는 Edge 인스턴스에서만 작동합니다.

Windows 365 for Agents에 대해 자세히 알아보려면 Windows 365 for Agents 설명서를 참조하세요.

개요

서버 ID	테넌트 수준의 URL	표시 이름	Description
mcp_W365ComputerUse	https://agent365.svc.cloud.microsoft/ agents/tenants/{tenantId}/ servers/mcp_W365ComputerUse	에이전트용 Windows 365 MCP 서버	Windows 365 클라우드 PC의 완전한 운영 제어권을 제공하며, 데스크톱 상호작용, 브라우저 자동화, UI 검사 등이 포함됩니다.

사용 가능한 도구

mcp_W365ComputerUse_StartSession

Windows 365 컴퓨터 사용 세션을 시작하고, 클라우드 PC에 연결을 설정하며, 클라우드 PC 리소스를 할당합니다. 세션을 관리하는 데 사용할 수 있는 sessionId를 반환합니다.

필요한 매개변수는 없습니다.

mcp_W365ComputerUse_EndSession

활성 Windows 365 컴퓨터 사용 세션을 종료하고 관련 클라우드 PC 리소스를 해제합니다. sessionId에서 반환된 mcp_W365ComputerUse_StartSession를 전달하세요.

필수 기준: sessionId

mcp_W365ComputerUse_GetSessionDetails

Windows 365 컴퓨터 사용 세션의 메타데이터를 반환하며, 이 세션은 .로 식별됩니다.sessionId sessionId에서 반환된 mcp_W365ComputerUse_StartSession를 전달하세요. 여러 세션이 나열되지 않습니다.

필수 기준: sessionId

move_mouse

커서를 화면 위치로 이동합니다. 목적지를 클릭할 계획이라면 대신 사용 click 하세요. 필수 매개 변수:

• x: 화면 픽셀 단위의 X 좌표
• y: 화면 픽셀 내 Y 좌표

click

위치를 클릭하거나 좌표가 생략된 경우 현재 커서 위치를 클릭합니다. 싱글 클릭, 더블 클릭, 그리고 다섯 개의 마우스 버튼 모두를 지원합니다.

선택적 매개 변수:

• x: 화면 픽셀 단위의 X 좌표 (현재 위치는 생략)
• y: 화면 픽셀 단위의 Y 좌표 (현재 위치는 생략)
• 버튼: 왼쪽, 오른쪽, 가운데, 앞으로, 또는 뒤로 (기본 왼쪽)
• 클릭 횟수: 1 = 싱글 클릭, 2 = 더블 클릭 (기본 1)

get_cursor_position

현재 커서 좌표를 반환합니다. 매개 변수는 없습니다. {cursorX, cursorY}를 반환합니다.

드래그_마우스

한 위치에서 다른 위치로 끌어옵니다. 객체 이동, 창 크기 조정, 픽셀 단위 정밀한 스크롤에 유용합니다. 필수 매개 변수:

• startX: X 좌표 시작.
• startY: Y 좌표 시작.
• endX: 끝 X 좌표.
• endY: Y 좌표 끝. 선택적 매개 변수:
• 버튼: 왼쪽, 오른쪽, 가운데 (기본값은 왼쪽)

스크롤

픽셀이 아닌 노치 단위를 사용하여 한 위치에서 스크롤합니다. 세 개의 노치는 대략 한 페이지에 해당합니다.

필수 매개 변수:

• x: 스크롤 위치 X
• y: 스크롤 위치 Y

선택적 매개 변수:

• deltaX: 가로 노치, 양수이면 오른쪽(기본값 0)
• deltaY: 세로 노치, 양수 = 아래로(기본값 0)

비고

값은 [-20, 20] 범위로 고정됩니다.

type_text

키보드 입력을 시뮬레이션하여 텍스트를 입력합니다. 키보드 단축키는 .을 사용 press_keys하세요. 웹 폼 필드는 .을 사용하세요 browser_type.

필수 매개 변수:

• 텍스트: 입력할 텍스트.

선택적 매개 변수:

• usePaste: 타이핑 대신 클립보드에서 텍스트를 붙여넣으세요.

press_keys

키 조합을 동시에 누릅니다. 수정키, 기능 키, 표준 키를 지원합니다.

필수 매개 변수:

• 키: 함께 누르는 키 이름 배열(예: ["ctrl","c"], , ["alt","tab"]) ["ctrl","shift","s"]

스크린샷 찍기

전체 화면 또는 잘린 영역을 PNG 이미지(base64로 인코딩됨)로 캡처합니다.

선택적 매개 변수:

• x: 자르기 영역의 왼쪽 가장자리
• y: 크롭 영역 상단 가장자리
• 너비: 크롭 영역 너비
• 높이: 작물 지역 높이

비고

네 가지 크롭 매개변수를 모두 함께 제공하거나, 전체 화면 캡처를 위해 네 가지 매개변수를 모두 생략하세요.

zoom_region

화면 영역을 기본 해상도로 PNG 이미지(base64 인코딩)로 캡처합니다. 이 기능을 활용해 다운스케일된 전체 화면 스크린샷에서 읽기 어려운 작은 텍스트나 빽빽한 UI 요소를 살펴보세요.

필수 매개 변수:

• x: 화면 픽셀 단위의 왼쪽 가장자리 X 좌표
• y: 화면 픽셀 단위의 상단 가장자리 Y 좌표
• width: 픽셀 단위의 영역 너비
• 높이: 픽셀 단위의 영역 높이

비고

최대 영역 크기는 1920x1080 픽셀입니다.

화면 분석

전체 화면에 OCR을 수행합니다. 매개 변수는 없습니다. {fullText, averageConfidence, boxes[{text, confidence, x, y, width, height}], width, height}을(를) 반환합니다.

get_screen_size

화면 해상도를 반환합니다. 매개 변수는 없습니다. {width, height}을(를) 반환합니다.

list_windows

보이는 모든 창과 그 제목, 위치, 크기를 나열합니다. 매개 변수는 없습니다. . 배열 {title, processName, handle, x, y, width, height}을 반환합니다.

창_활성화

유사 항목 제목 일치를 사용하여 창을 포그라운드로 가져옵니다.

필수 매개 변수:

• 제목: 부분 창 제목 (대소문자 구분 없는 서브스트링)

focus_browser

URL 또는 제목으로 선택적으로 필터링된 브라우저 창(Edge, Chrome 또는 Firefox)에 초점을 맞춥니다.

선택적 매개 변수:

• 패턴: URL 또는 제목 서브스트링을 일치시키기 (브라우저 창은 생략)

창_닫기

유사 항목 제목 일치를 사용하여 창을 정상적으로 닫습니다. 시스템은 중요한 프로세스를 보호하며, 이를 닫을 수 없습니다.

필수 매개 변수:

• 제목: 창 제목의 일부(80% 일치 기준). {matchedTitle, processName, closed}을(를) 반환합니다.

창 크기 조정

제목 유사 일치를 사용하여 창을 이동하거나 크기를 조정하고, 최대화, 최소화 또는 복원합니다.

필수 매개 변수:

• 제목: 일치시킬 창 제목(대소문자를 구분하지 않는 퍼지 일치)
• 작업: 수행할 작업 - Resize, Move, Maximize, Minimize, 또는 Restore

선택적 매개 변수:

• x: 왼쪽 모서리 X 좌표 (또는 Resize함께 Move 사용)
• y: 위쪽 가장자리의 Y 좌표(Resize 또는 Move와 함께 사용)
• width: 픽셀 단위의 너비(와 함께 Resize사용됨)
• 높이: 픽셀 단위의 높이(와 함께 Resize사용됨)

execute_shell_command

샌드박스 환경에서 셸 명령어를 실행합니다. 명령어는 허용 목록에 대조되어 위험한 패턴을 차단합니다.

필수 매개 변수:

• 명령: 실행 명령

선택적 매개 변수:

• cwd: 작업 디렉터리. 앞으로의 슬래시(예: C:/Users/me/project)를 사용하세요.
• 타임아웃Ms: 밀리초 단위 타임아웃 (기본값 30000, 최대 120000)

비고

• 허용 명령어: git, npm, dotnet, python, cargo, node, pip, dir, mkdir, del, copy, move, robocopy, findstr, where, type 및 notepad.
• 차단된 패턴에는 셸 메타캐릭터(|, ;, &, <), >환경 변수 확장 (%VAR%), 인터프리터 평가 플래그(python -c 또는 node -e), git config --global, npm -g, 경로 접두사 실행 파일, rm -rf, , sudo디스크 또는 시스템 명령어가 포함됩니다.
• 명령의 stdout와 stderr는 각각 32KB로 잘립니다. 임의의 계산에는 를 사용 execute_python_code하세요. 이 명령은 {stdout, stderr, exitCode, success, timedOut, resourceLimitsApplied}를 반환합니다.

execute_python_code

자원 제한이 있는 샌드박스 환경에서 Python 코드를 실행합니다. 이 기능은 데이터 처리, 계산, 파일 I/O, 그리고 단순한 셸 명령어를 넘어서는 모든 계산에 이상적입니다.

필수 매개 변수:

• code: Python 코드(최대 262,144자).

선택적 매개 변수:

• cwd: 작업 디렉터리. 정방향 슬래시를 사용합니다.
• 타임아웃Ms: 밀리초 단위의 타임아웃(기본값 30000, 최대 120000).

와 동일한 스키마 execute_shell_command를 반환합니다.

비고

샌드박스는 512MB 메모리 제한과 30초 타임아웃을 강제합니다.

wait_milliseconds

애니메이션이나 전환이 완료될 때까지 실행을 일시정지합니다. 이 함수는 폴링 루프에서 사용하지 마세요. 대신 DOM 폴링에는 browser_wait_for를 사용하세요.

필수 매개 변수:

• ms: 대기 시간 (밀리초 단위) ([0, 5000]로 클램프됨)

클립보드_읽기

시스템 클립보드의 현재 내용을 읽습니다. 이 명령어는 별도의 매개변수가 필요하지 않습니다. 이 도구는 클립보드 형식과 페이로드를 설명하는 JSON 객체를 반환하며, 이는 텍스트 문자열이거나 base64로 인코딩된 이미지일 수 있습니다.

클립보드_쓰기

시스템 클립보드에 텍스트를 작성하여 현재 내용을 대체합니다.

필수 매개 변수:

• 텍스트: 클립보드에 쓸 텍스트

문자 수가 포함된 확인 메시지를 반환합니다.

list_processes

현재 세션에서 실행 중인 프로세스를 나열합니다. 각 항목에는 PID, 프로세스 이름, 메모리 사용량, 창 제목(있는 경우), 그리고 startTimeTicks. 재활용된 PID를 죽이지 않도록 함께 startTimeTickskill_process 사용하세요.

선택적 매개 변수:

• maxCount: 반환할 최대 프로세스 수 (기본값 200)

프로세스 정보 객체의 JSON 배열을 반환합니다.

kill_process

PID로 프로세스를 종료합니다. PID 재사용을 방지하려면 startTime의 list_processes 값을 제공하세요.

필수 매개 변수:

• pid: list_processes에 의해 반환되는 프로세스 ID
• startTime: list_processes가 반환한 프로세스 시작 시간 틱

선택적 매개 변수:

• force: 정상 종료 절차 없이 강제 종료(기본값: false)

결과를 설명하는 JSON 결과를 반환합니다.

애플리케이션 실행

허용되는 디렉터리에서 GUI 애플리케이션을 시작합니다. 대신 CLI 명령에는 execute_shell_command를 사용하세요.

필수 매개 변수:

• path: 실행 파일로 가는 절대 경로. 앞으로의 슬래시(예: C:/Program Files/app.exe)를 사용하세요.

선택적 매개 변수:

• args: 명령줄 인수 배열

{path, pid}을(를) 반환합니다.

get_system_info

OS 버전, CPU, RAM, 사용 가능한 디스크 공간, 디스플레이 해상도를 반환합니다. 매개 변수는 없습니다. 시스템 정보를 담은 JSON 객체를 반환합니다.

브라우저 탐색

URL로 이동해서 페이지가 로드될 때까지 기다립니다.

필수 매개 변수:

• URL: 프로토콜을 포함한 전체 URL (예: https://example.com)

browser_back

브라우저 방문 기록에서 뒤로 이동합니다. 매개 변수는 없습니다.

browser_forward

브라우저 기록에서 앞으로 이동할 수 있습니다. 매개 변수는 없습니다.

브라우저 새로 고침

현재 페이지를 다시 로드합니다. 매개 변수는 없습니다.

browser_get_url

현재 페이지 URL을 일반 문자열로 반환합니다. 매개 변수는 없습니다.

browser_get_title

현재 페이지 제목을 단순한 문자열로 반환합니다. 매개 변수는 없습니다.

browser_get_text

보이는 페이지 텍스트 내용을 일반 문자열로 반환합니다. 매개 변수는 없습니다. 512KB로 축소되었습니다.

browser_get_html

전체 페이지 HTML 소스를 일반 문자열로 반환합니다. 매개 변수는 없습니다. 512KB로 축소되었습니다.

browser_get_page_state

한 번의 호출에서 여러 페이지 상태 필드를 검색합니다. 별도의 툴 호출 없이 여러 신호를 동시에 캡처하는 데 유용합니다.

필수 매개 변수:

• 필드: 반환할 필드 배열. 허용된 값: url, title, dom, screenshot, tabs

요청된 필드만 포함하는 JSON 객체를 반환합니다.

browser_click

CSS 셀렉터로 DOM 요소를 클릭합니다. 좌표 기반 클릭보다 웹 콘텐츠가 더 신뢰할 만합니다.

필수 매개 변수:

• 셀렉터: CSS 셀렉터 (예: #submit-btna.nav-link또는 )

browser_type

CSS 셀렉터를 사용해 텍스트를 폼 요소에 입력합니다.

필수 매개 변수:

• 셀렉터: 입력 요소의 CSS 셀렉터입니다.
• 텍스트: 입력할 텍스트.

browser_query_text

CSS 선택기와 일치하는 첫 번째 요소의 텍스트 내용을 가져옵니다.

필수 매개 변수:

• 셀렉터: CSS 셀렉터.

browser_wait_for

DOM 요소가 나타나기를 기다립니다. 이 기능은 비동기로 로드되는 동적 콘텐츠에 유용합니다.

필수 매개 변수:

• 선택자: 대기할 CSS 선택자.

선택적 매개 변수:

• 타임아웃 MS: 타임아웃 시간은 밀리초 단위입니다. 기본값은 5,000이고 최대 점수는 30,000입니다.

browser_eval_js

페이지 컨텍스트에서 자바스크립트 표현식을 평가하여 결과를 문자열로 반환합니다.

필수 매개 변수:

• 표현식: 문자열을 반환하는 JavaScript 표현식입니다

비고

만약 표현식에서 객체나 숫자를 반환한다면, 그것을 명시적으로 문자열로 변환하세요(예: JSON.stringify(obj).toString()또는 ).

browser_list_tabs

모든 열린 탭과 그 인덱스, 제목, URL을 나열합니다. 매개 변수가 필요하지 않습니다. . 배열 {index, title, url}을 반환합니다.

선택적 매개 변수:

• tabId: 고유 탭 식별자

browser_switch_tab

인덱스에 따라 탭으로 전환됩니다.

필수 매개 변수:

• tabIndex: 0 기반 탭 인덱스

선택적 매개 변수:

• tabId: 고유 탭 식별자

브라우저_새_탭

필요에 따라 URL로 이동하여 새 탭을 엽니다.

선택적 매개 변수:

• URL: 열기 URL (생략 시 빈 탭)

{index, title, url}을(를) 반환합니다.

browser_create_tabs

여러 탭을 한 번에 엽니다. 선택적으로 그 중 하나를 전경으로 끌어올 수도 있습니다.

필수 매개 변수:

• urls: 열 URL의 배열, URL마다 탭 하나씩

선택적 매개 변수:

• foregroundIndex: 탭 생성 후 전경으로 가져오는 인덱스 (현재 탭을 집중 상태로 유지하기 위해 생략)

문자 확인 메시지를 남깁니다.

브라우저 탭 닫기

인덱스별로 탭을 닫습니다.

필수 매개 변수:

• tabIndex: 0 기반 탭 인덱스 선택 매개변수:

• tabId: 고유 탭 식별자

브라우저_스크린샷

브라우저 뷰포트의 PNG 스크린샷만 캡처합니다(전체 화면은 아님). 매개 변수는 없습니다. base64로 인코딩된 PNG를 반환합니다.

browser_select_option

<select> 요소에서 value 속성을 기준으로 하나 이상의 옵션을 선택합니다.

필수 매개 변수:

• 셀렉터: 요소에 대한 <select> CSS 셀렉터
• 값: 선택할 옵션 값 배열입니다

선택된 옵션 수를 확인 응답합니다.

브라우저에서 양식 채우기

한 번의 통화로 여러 양식 필드를 작성하세요. 각 항목은 쌍 {selector, value} 으로 이루어집니다. 첫 실패에서 작업이 중단되고 어떤 필드가 성공했는지 보고합니다.

필수 매개 변수:

• 필드: {selector, value} 쌍의 배열

채워진 필드 수를 확인해 줍니다.

browser_drag

원본 요소를 대상 요소로 끌어옵니다. 두 요소 모두 CSS 선택기로 식별됩니다.

필수 매개 변수:

• sourceSelector: 드래그 소스의 CSS 셀렉터입니다
• targetSelector: 드롭 타겟의 CSS 셀렉터입니다

browser_pdf_save

현재 페이지를 PDF 파일로 저장합니다. 목적지 경로는 %USERPROFILE% 또는 %TEMP%로 제한됩니다.

필수 매개 변수:

• filePath: 또는 %USERPROFILE%. %TEMP% 아래에 있는 목적지 파일 경로. 정방향 슬래시를 사용합니다.

저장된 파일 경로가 포함된 확인 메시지를 반환합니다.

browser_handle_dialog

보류 중인 브라우저 대화 상자(경고, 확인, 프롬프트 또는 beforeunload)를 수락하거나 해제합니다. 활성 대화가 없으면 "대기 중인 대화 없음"을 반환합니다.

필수 매개 변수:

• 행동: accept 또는 dismiss

선택적 매개 변수:

• promptText: 프롬프트 대화 상자에 제공할 텍스트(alert 및 confirm에서는 무시됨)

browser_get_cookies

현재 페이지 또는 지정된 URL 집합에 대한 쿠키를 가져옵니다. 쿠키 값은 보안을 위해 항상 검열됩니다; 이름, 도메인, 경로, 플래그가 반환됩니다.

선택적 매개 변수:

• urls: 쿠키를 받을 수 있는 URL 배열(현재 페이지는 생략)

치하된 값을 가진 쿠키 객체 배열을 반환합니다.

browser_set_cookies

현재 페이지의 도메인에 쿠키를 설정합니다. 이 작업은 쿠키를 추가하거나 덮어쓰지만 기존 쿠키는 지우지 않습니다.

필수 매개 변수:

• 쿠키: 쿠키 객체들의 배열입니다. 각 항목에는 name 및 value이 필요합니다. 선택 필드: domain, path, , securehttpOnly, sameSite.

문자 확인 메시지를 남깁니다.

browser_execute_batch

한 번의 호출로 여러 브라우저 작업을 순차적으로 실행합니다. 이 동작은 첫 번째 실패에서 멈추고 그때까지 수집된 결과를 반환합니다.

필수 매개 변수:

• actions: 객체 배열 {action, params} . 허용된 행동: navigate, snapshot, click_ref, type_refhover_ref, scroll_ref, , keypress_ref, , . wait_foreval_js

실행 액션당 하나의 결과 배열을 반환합니다.

브라우저 스냅샷

안정적인 참조 ID(예: e5)를 사용하여 페이지의 접근성 트리를 캡처하며, 이는 DOM 노드에 매핑됩니다. 참조를 browser_click_ref, browser_type_ref, browser_hover_ref와 함께 사용하세요. 참조는 페이지가 탐색할 때 만료됩니다—탐색 후 다시 스냅샷을 찍으세요.

선택적 매개 변수:

• maxDepth: 최대 나무 깊이, 1-10 (기본 5)
• includeIframes: 교차 출처 iframe 포함(기본값: true)

접근성 스냅샷과 참조 ID가 포함된 JSON 객체를 반환합니다.

browser_click_ref

browser_snapshot의 참조 ID로 요소를 클릭합니다. 히트 테스트는 다른 요소가 목표물 위에 겹치지 않는지 확인합니다. 스냅샷이 만료되면 실패하며, 그럴 경우 다시 스냅샷을 가져가야 합니다.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 스냅샷 노드의 요소 ref(예: e5)

선택적 매개 변수:

• 버튼: 왼쪽, 오른쪽, 또는 가운데 (기본 왼쪽)
• 클릭 횟수: 1 = 싱글 클릭, 2 = 더블 클릭 (기본 1)

클릭하면 좌표가 포함된 확인 메시지를 반환합니다.

browser_type_ref

참조 ID browser_snapshot를 사용하여 텍스트를 요소에 입력합니다. 요소가 먼저 포커스되고, 기존 텍스트는 기본적으로 지워집니다. 스냅샷이 만료되면 연산이 실패합니다.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 스냅샷 노드의 요소 ref(예: e5)
• 텍스트: 입력할 텍스트

선택적 매개 변수:

• clear: 기존 텍스트를 먼저 명확히 해야 합니다 (기본 참)

문자 수가 포함된 확인 메시지를 반환합니다.

browser_hover_ref

참조 ID browser_snapshot를 사용하여 요소 위에 마우스를 올립니다. 즉시 반환합니다. 스냅샷이 만료되면 작업이 실패하므로, 이 경우 다시 스냅샷을 가져가세요.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 스냅샷 노드의 요소 ref(예: e5)

호버 좌표를 포함한 확인 응답을 반환합니다.

get_accessibility_tree

포그라운드 창의 UI 요소 트리를 검색합니다. 각 요소에는 역할, 이름, 가치, 화면 좌표가 포함되어 있습니다.

선택적 매개 변수:

• maxDepth: 최대 나무 횡단 깊이, 1-10 (기본 3)
• maxElements: 반환할 최대 요소, 1-2000 (기본 500)

{role, name, value, x, y, width, height, children[...]}의 계층 트리를 반환합니다.

browser_keypress_ref

browser_snapshot에서 참조 ID를 사용하여 요소의 특정 키를 누릅니다. 요소에 먼저 포커스가 맞춰집니다. 수정자 키를 지원합니다. 스냅샷이 만료되면 실패합니다 — 그럴 경우 다시 스냅샷을 가져와야 합니다.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 스냅샷 노드의 요소 ref(예: e5)
• 키: 키명(keyname — 예: Enter, Escape, Tab, ArrowUpArrowDown, ) F1–F12

선택적 매개 변수:

• 수정자: 누르는 동안 유지할 수 있는 수정자 키 배열 — Ctrl, Shift, Alt, 또는 Meta

문자 확인 메시지를 남깁니다.

browser_scroll_ref

browser_snapshot의 ref ID를 사용하여 요소가 화면에 보이도록 스크롤합니다. 필요에 따라 요소 내의 픽셀 델타로 스크롤합니다. 스냅샷이 만료되면 실패합니다.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 스냅샷 노드의 요소 ref(예: e5)

선택적 매개 변수:

• deltaX: 픽셀 단위의 수평 스크롤 델타(기본값 0)
• deltaY: 수직 스크롤 델타 (픽셀 단위) (기본 0)

문자 확인 메시지를 남깁니다.

browser_set_file_input_ref

browser_snapshot의 ref ID를 사용하여 파일 입력 요소에 파일을 설정합니다. 파일 경로는 사용자의 Documents, , DownloadsDesktop, 또는 %TEMP% 디렉터리로 제한됩니다.

필수 매개 변수:

• snapshotId: 스냅샷 ID 반환 browser_snapshot
• ref: 파일 입력을 위한 요소 참조
• filePaths: 업로드할 파일 경로 배열

문자 확인 메시지를 남깁니다.

find_ui_element

텍스트 콘텐츠, 접근성 역할 또는 이름(대/소문자를 구분하지 않는 부분 문자열)으로 UI 요소를 검색합니다. 클릭 가능한 화면 좌표와 일치하는 요소를 반환합니다.

선택적 매개 변수:

• 텍스트: 검색용 텍스트 (이름이 생략되면 이름으로 사용)
• role: UI 역할 필터 - Button, TextBox, CheckBox, MenuItem, ComboBox 등
• 이름: 접근 가능한 이름(두 이름이 모두 제공될 경우 텍스트보다 우선)
• windowHandle: 대상 윈도우 핸들 (null = 전경 창)

주요 기능

데스크톱 상호 작용

• 클릭, 더블 클릭, 오른쪽 클릭, 그리고 다섯 버튼 마우스 조작.
• 픽셀 단위로 정밀하게 드래그 앤 드롭.
• 노치 기반 스크롤(노치 3번 ≈ 한 페이지).
• 키보드 타이핑과 다중 키 단축키 조합.
• 커서 위치 추적.
• 화면 해상도 감지.

화면 캡처 및 분석

• 전체 화면 또는 잘린 PNG 스크린샷.
• 전체 화면 OCR과 영역별 신뢰도 점수 및 경계 상자
• 웹 콘텐츠용 브라우저 뷰포트 전용 스크린샷.

창 관리

• 위치와 치수를 가진 모든 보이는 창을 열거하세요.
• 창 제목의 유사 일치로 창을 활성화하세요.
• URL 또는 제목으로 선택적으로 필터링하여 브라우저 창(Edge, Chrome, Firefox)에 포커스를 맞춥니다.
• 시스템 중요 프로세스에 대한 보호와 함께 우아하게 닫히는 윈도우.

명령 실행

• 허용 목록(git, npm, dotnet, python, cargo, node, pip, dir, mkdir, del, copy, move, robocopy, findstr, where, type)을 가진 샌드박스 셸 명령어().
• 최대 262,144자 코드의 샌드박스 Python 실행.
• 작업 디렉터리 및 통화당 타임아웃 제어(최대 30초).
• 셸 메타캐릭터, 평가 플래그, 권한 상승, 파괴 작전에 대한 자원 제한과 강화된 차단 목록.

브라우저 자동화

• 내비게이션, 후퇴, 앞으로, 재로드, 그리고 탐색 시 설정 가능한 대기 조건(load, , networkidle0networkidle2).
• 페이지 URL, 제목, 가시 텍스트(512 KB 용량), 전체 HTML(512 KB 용량)을 읽으세요.
• 통합 페이지 상태 검색 — URL, 제목, DOM, 스크린샷, 탭 목록 모두 단일 호출로 가능합니다.
• DOM 수준의 클릭, 타이핑, 폼 채우기, 드래그, <select> CSS 선택기를 통한 옵션 선택.
• 참조 ID에 의한 접근성 스냅샷 기반 상호작용 — 클릭, 타이핑, 호버, 수정어 키누름, 스크롤, 파일 입력 업로드.
• 구성 가능한 타임아웃으로 동적 요소를 기다리며, 필요에 따라 표시 여부 확인을 요구할 수 있습니다.
• 페이지 컨텍스트에서 JavaScript 표현식을 평가하세요.
• 멀티탭 관리: 리스트, 전환, 한꺼번에 하나 또는 여러 개 열고, 닫습니다.
• 쿠키 검사(값 삭제)와 현재 도메인 할당.
• 배치 액션 실행 — 한 번의 호출에서 여러 브라우저 단계를 순서로 연속하여 첫 실패 시 중단.
• 현재 페이지를 PDF %USERPROFILE%%TEMP%로 저장하세요.
• alert, confirm, prompt 및 beforeunload에 대한 대화 상자 처리
• Microsoft Edge에서 실행되며, 첫 사용 시 자동으로 실행됩니다.

UI 접근성

• 전경 창의 Windows UI 자동화 tree를 깊이와 요소 수를 설정할 수 있는 상태로 불러옵니다.
• 텍스트, 역할, 접근 가능한 이름별로 UI 요소를 찾아보세요.
• 버튼, 텍스트 박스, 체크박스, 메뉴 항목, 콤보 박스를 정밀하게 타겟팅할 수 있도록 클릭 가능한 화면 좌표를 반환합니다.

타이밍과 동기화

• 짧은 원샷 정지(최대 5초)에 사용 wait_milliseconds 하세요.
• DOM 수준 폴링(최대 30초)에는 browser_wait_for를 사용합니다.

Notes

• 모든 좌표는 화면 픽셀 단위이며, 왼쪽 상단에 (0,0)가 있습니다. , take_screenshotanalyze_screen, find_ui_element, 의 list_windows 좌표들은 모두 동일한 좌표 공간을 공유한다.
• 커서 페일세이프가 활성화되어 있습니다: 커서가 화면 모서리에서 5픽셀 이내로 이동하면 마우스 작업이 취소됩니다. 화면 가장자리를 노리는 것은 피하세요.
• 셸 파이프 연산자(|), 세미콜론(;), 앰퍼샌드(&), 출력 리디렉션(>, <)은 차단됩니다. 명령 출력 결과를 변환하려면 이를 캡처한 다음 execute_python_code로 처리하세요.
• 인터프리터 평가 플래그가 차단되거나 python -c "..."와 node -e "..."가 거부될 경우, Python 코드에 execute_python_code를 사용하거나 먼저 파일에 코드를 작성할 수 있습니다.
• 명령어 stdout/stderr 는 각각 32KB로 축소됩니다. 플래그를 사용해 장황한 출력(예: git log --oneline -20)을 제한하거나 파일로 리디렉션하여 별도로 읽으세요.
• 와 execute_shell_command 의 execute_python_code 최대 타임아웃은 30초입니다. 시간이 오래 걸리는 작업은 더 작은 단계로 나누거나 Python으로 백그라운드 프로세스를 실행한 뒤 상태를 주기적으로 확인하세요.
• 전용 파일 읽기/쓰기 도구가 없습니다. 명령어 execute_shell_command 를 사용해 type 파일을 읽으세요. Python 내장 파일 I/O를 사용해 execute_python_code 파일을 작성하세요. 셸 출력 리디렉션(>, >>)이 차단됩니다.
• browser_eval_js 항상 문자열을 반환합니다. 객체나 숫자를 명시적으로 변환한 후 반환하세요.
• 브라우저 DOM 도구들(browser_click, browser_type, browser_eval_js 등)은 Microsoft Edge 인스턴스에서만 작동합니다.  focus_browser 크롬이나 파이어폭스 윈도우에 집중할 수 있지만, DOM 도구는 이들을 타겟팅하지 않습니다.
• take_screenshot 전체 화면 캡처를 위해서는 네 가지 자르기 매개변수(X, Y, 너비, 높이)를 모두 필요하며, 또는 아예 없어야 합니다.
• scroll 픽셀이 아닌 노치 유닛([-20, 20]에 클램프됨)을 사용합니다. 세 개의 노치는 대략 한 페이지에 해당합니다.
• find_ui_element 텍스트, 역할 또는 이름 중 적어도 하나가 필요합니다. 텍스트와 이름이 모두 제공될 경우, 이름이 우선권을 가집니다.
• browser_snapshot 참고문헌은 내비게이션에서 만료됩니다. 만약 스냅샷이 오래된 상태라 도구(클릭, 타이핑, 호버링, 키 입력, 스크롤, 파일 입력 설정)가 실패하면 _ref , 다시 스냅샷을 찍고 다시 시도하세요.
• browser_set_file_input_ref사용자의 Documents, Downloads, Desktop%TEMP% , 디렉터리 아래에서만 파일 경로를 허용합니다. 그 위치 외의 파일은 거부됩니다.
• browser_get_cookies 항상 편집된 쿠키 값을 반환합니다. 검사용으로 사용하세요—이름, 도메인, 경로, 플래그는 모두 반환되지만 값은 노출되지 않습니다.
• browser_set_cookies 쿠키만 추가하거나 덮어쓰는 기능입니다. 기존 쿠키를 삭제하지 않습니다. 쿠키를 제거하려면 이 도구를 통해 만료된 expires 값으로 덮어쓰거나, 페이지 자체를 통해 쿠키를 삭제하세요.
• browser_execute_batch 첫 번째 실패한 동작에서 멈추고, 그때까지 수집된 결과만 반환합니다. 배열에서 이후의 동작들은 시도되지 않습니다. 허용되는 배치 작업은 다음으로 제한됩니다: navigate, snapshot, click_ref, type_ref, hover_ref, scroll_ref, keypress_ref, wait_for 및 eval_js.
• browser_create_tabs 제공된 순서대로 탭을 엽니다. 만약 이 설정이 생략되 foregroundIndex 면, 초점은 현재 활성화된 탭에 머무릅니다.
• browser_get_page_state 배열에 fields 나열된 필드만 반환합니다. 필요한 것만 요청하세요 – dom 또는 screenshot를 포함하면 큰 페이로드가 생성될 수 있습니다.

일반적인 사용 사례

웹 양식을 작성하세요

• 타겟 페이지를 열기 위해 전화하세요 browser_navigate .
• 양식이 로드될 때까지 기다리라고 전화하세요 browser_wait_for .
• CSS 셀렉터로 각 필드를 채우기 위해 호출하세요 browser_type .
• 신청서를 제출하려면 전화하세요 browser_click .
• 확인 요소를 기다리려면 browser_wait_for를 호출하세요.
• 결과를 읽고 확인하려면 browser_get_text에 전화하세요.

데스크톱 애플리케이션 자동화

• activate_window를 호출하여 애플리케이션을 전경으로 가져옵니다.
• 현재 상태를 캡처하기 위해 호출하세요 take_screenshot .
• 이름으로 버튼이나 필드를 찾으려면 전화하세요 find_ui_element .
• 요소의 보고된 좌표에서 click를 호출하세요.
• 데이터를 입력하려면 전화하세요 type_text .
• 단축키를 요청하세요 press_keys (예: ["ctrl","s"] 저장).
• 결과를 확인하려면 전화하세요 take_screenshot .

웹페이지에서 데이터 추출하기

• 페이지를 열기 위해 전화하세요 browser_navigate .
• 가시적인 텍스트 내용을 추출하기 위해 호출 browser_get_text 합니다.
• 추출된 데이터를 파싱하고 처리하기 위해 호출합니다 execute_python_code .
• browser_eval_js 텍스트 추출만으로는 부족할 때 JavaScript를 통해 특정 값을 쿼리할 수 있습니다.

개발 작업 실행

• execute_shell_command, git pull, npm install에 대해 dotnet build을(를) 호출합니다.
• 빌드 출력을 캡처하기 위해 호출하세요 take_screenshot .
• 로그 분석이나 테스트 결과를 원하시면 전화하세요 execute_python_code .
• 브라우저에서 로컬 개발 서버를 열기 위해 호출 browser_navigate 하세요.
• 렌더링된 페이지를 캡처하기 위해 호출하세요 browser_screenshot .

파일 읽기 및 쓰기

• 파일을 읽을 때 execute_shell_command와 type C:\path\to\file.txt을 사용합니다.
• execute_python_code를 사용해 Python의 open(...)와 write(...)를 사용해 파일을 작성합니다.
• execute_shell_command와 함께 dir C:\path\to\output.txt를 사용하여 확인하세요.

접근성과 함께 복잡한 UI를 탐색하세요

• 전체 UI 구조를 이해하려면 전화하세요 get_accessibility_tree .
• 특정 컨트롤을 찾기 위해 호출합니다 find_ui_element (예: role: "MenuItem", name: "Settings").
• 원소의 보고된 좌표를 사용해 호출하세요 click .
• 대화 내에서 다음 컨트롤을 찾기 위해 다시 호출하세요 find_ui_element .
• type_text 또는 click을 호출하여 이와 상호 작용하세요.

장시간 실행되는 세션을 유지하세요

• MCP 요청을 최소 30분마다 한 번 보내 무단 퇴거를 방지하세요.
• get_screen_size 가볍고 심장 박동처럼 잘 작동합니다.

더 알아보세요

에이전트용 Windows 365