Qwen 3.7 Plus는 스크린샷을 보고 클릭할 정확한 픽셀 좌표를 반환하는 벤치마크인 ScreenSpot Pro에서 79.0점을 기록했습니다. 이 단 하나의 기술이 채팅 모델을 컴퓨터 사용 에이전트(화면을 보고 무엇을 할지 결정한 후 실행하는 소프트웨어)로 변화시킵니다. 이 가이드에서는 Python으로 작동하는 에이전트를 처음부터 끝까지 구축하는 방법을 다룹니다.
이 가이드에서는 에이전트 루프, 모델에서 신뢰할 수 있는 작업을 이끌어내는 프롬프트, Playwright를 사용한 실행 가능한 브라우저 예시, 그리고 실제 상황에 적용하기 전에 필요한 비용 및 안전 가이드라인에 대해 설명합니다. 모델에 대한 배경 지식이 먼저 필요하다면, Qwen 3.7 Plus 개요를 참조하세요. 원시 요청 형식에 대해서는 Qwen 3.7 Plus API 가이드에서 멀티모달 페이로드를 다룹니다. 진행하면서 Apidog에서 에이전트 호출을 테스트할 것입니다.
요약
컴퓨터 사용 에이전트는 루프를 실행합니다: 화면을 스크린샷하고, 목표와 함께 Qwen 3.7 Plus로 전송하고, `click (x, y)`와 같은 구조화된 작업을 반환받아 Playwright와 같은 드라이버로 해당 작업을 실행한 다음, 목표가 달성될 때까지 반복합니다. Qwen 3.7 Plus는 GUI 기반 기능과 저렴한 멀티모달 가격 덕분에 이 작업에 매우 적합합니다. 어려운 부분은 모델 자체가 아니라 루프 제한, 좌표 스케일링, 토큰 비용 제어, 그리고 잘못된 클릭이 손상을 일으키지 않도록 작업을 샌드박스 처리하는 것입니다.
컴퓨터 사용 에이전트가 실제로 하는 일
과장된 설명을 걷어내면, 반복되는 네 가지 단계로 이루어집니다:
- 인식: 현재 화면이나 페이지의 스크린샷을 캡처합니다.
- 결정: 스크린샷과 목표를 모델에 보내고 다음 작업을 얻습니다.
- 실행: 자동화 드라이버를 통해 해당 작업(클릭, 입력, 스크롤)을 실행합니다.
- 확인: 새 스크린샷을 찍고 목표가 완료되었는지 결정합니다.
모델은 "결정" 단계입니다. 나머지는 모두 사용자가 제어하는 파이프라인입니다.
Qwen 3.7 Plus가 적합한 이유
세 가지 이유가 있습니다. Qwen 3.7 Plus의 GUI 기반 기능은 최고 수준이어서 모호한 설명 대신 사용 가능한 좌표를 반환합니다. 또한 하이브리드 GUI 및 CLI 워크플로를 처리할 수 있으므로 동일한 에이전트가 버튼을 클릭하고 셸 명령을 실행할 수 있습니다. 그리고 백만 입력 토큰당 0.40달러로, 에이전트 루프에 필요한 많은 비전 호출을 실행하기에 충분히 저렴합니다. 텍스트 전용 플래그십 모델과의 비교는 Qwen 3.7 Plus vs Max 비교에서 확인하세요.
결정 단계: 깔끔한 작업 얻기
핵심은 모델을 작은 작업 어휘로 제한하고 JSON 출력을 강제하는 것입니다. 느슨한 산문은 실행하기 어렵지만, 엄격한 스키마는 그렇지 않습니다.
import os, json, base64
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
SYSTEM = """당신은 GUI 에이전트입니다. 스크린샷과 목표를 보게 됩니다.
단 하나의 JSON 작업으로만 응답하세요:
{"action": "click", "x": <정수>, "y": <정수>}
{"action": "type", "text": "<문자열>"}
{"action": "scroll", "dy": <정수>}
{"action": "done", "reason": "<문자열>"}
좌표는 주어진 스크린샷의 픽셀 단위입니다."""
def next_action(goal, png_bytes):
b64 = base64.b64encode(png_bytes).decode()
resp = client.chat.completions.create(
model="qwen3.7-plus",
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": [
{"type": "text", "text": f"Goal: {goal}"},
{"type": "image_url",
"image_url": {"url": f"data:image/png;base64,{b64}"}},
]},
],
)
return json.loads(resp.choices[0].message.content)
식별자는 변경될 수 있으므로 배포 전에 Model Studio 문서에서 정확한 모델 ID를 확인하세요.
Playwright를 사용한 전체 루프
Playwright는 실제 브라우저를 구동하므로 에이전트는 실제 페이지에서 작동합니다. 한 가지 중요한 세부 사항으로 많은 번거로움을 덜 수 있습니다: 스크린샷 해상도를 뷰포트와 일치시켜 모델이 반환하는 좌표가 일대일로 매핑되고 스케일링 계산을 건너뛸 수 있도록 합니다.
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=False)
page = browser.new_page(viewport={"width": 1280, "height": 800})
page.goto("https://example.com")
goal = "Open the pricing page and find the cheapest plan"
for step in range(15): # 단계의 상한선
shot = page.screenshot() # 1280x800 PNG, 뷰포트와 일치
action = next_action(goal, shot)
print(step, action)
if action["action"] == "done":
break
if action["action"] == "click":
page.mouse.click(action["x"], action["y"])
elif action["action"] == "type":
page.keyboard.type(action["text"])
elif action["action"] == "scroll":
page.mouse.wheel(0, action["dy"])
page.wait_for_timeout(800) # UI가 안정될 때까지 기다림
browser.close()
이것이 실제 에이전트입니다. 목표를 향해 한 번에 하나의 기본 작업을 수행하며 사이트를 탐색할 것입니다. Playwright를 데스크톱 드라이버로 바꾸고 OS 창을 스크린샷하면 데스크톱 앱에서도 동일한 패턴이 작동합니다.
비용 및 신뢰성
스크린샷은 비용이 많이 드는 부분입니다. 각 스크린샷은 토큰으로 변환되며, 1280픽셀 너비의 이미지는 수천 개의 토큰에 달할 수 있으므로, 15단계 루프는 API를 통해 상당한 비용을 발생시킵니다. 비용을 줄이려면:
- 축소 및 자르기. 모델이 여전히 읽을 수 있는 가장 작은 이미지를 전송하세요. 가능하다면 관련 패널로 자르세요.
- 루프 제한. 예시에서처럼 항상 단계 수를 제한하여 혼란스러운 에이전트가 무한히 실행되지 않도록 합니다.
- 실행 후 확인. 각 작업을 가설로 간주합니다. 다음 스크린샷은 작업이 성공했는지 확인하고, 루프는 스스로 수정합니다.
에이전트 토큰 비용 절감에 대한 저희 가이드에서 더 자세히 다루며, 에이전트 워크플로 연결에 대한 저희 노트는 실제로 이러한 루프가 어디에서 실패하는지 설명합니다.
에이전트가 멈췄을 때
세 가지 실패가 끊임없이 나타나며, 각각 저렴한 해결책이 있습니다:
- 모델이 JSON 대신 산문을 반환하는 경우. 짧은 "JSON으로만 응답하세요"라는 알림과 함께 다시 프롬프트를 보내고, 포기하기 전에 한 번 더 재시도하세요. 엄격한 스키마와 복구 단계가 거의 모든 문제를 해결합니다.
- 클릭이 대상을 놓치는 경우. 다음 스크린샷에 아무런 변화가 없다면, 동일한 좌표를 맹목적으로 반복하는 대신 새로운 스크린샷으로 재시도하는 규칙을 추가하세요.
- 루프가 진행 없이 회전하는 경우. 마지막 몇 가지 작업을 추적합니다. 작업이 반복되면 중지하고 스크린샷을 사람에게 보여줍니다. 단계 제한은 최후의 방어선입니다.
안전
컴퓨터 사용 에이전트는 실제로 작업을 클릭합니다. 중요한 것에 영향을 미치기 전에:
- 샌드박스 또는 일회용 브라우저 프로필에서 실행하고, 로그인된 프로덕션 세션에서는 절대 실행하지 마세요.
- 삭제, 전송 또는 결제와 같은 파괴적인 작업에는 사람의 확인을 요구하세요.
- 에이전트가 무엇을 했고 왜 했는지 감사할 수 있도록 모든 작업을 스크린샷과 함께 기록하세요.
Apidog로 에이전트 호출 테스트하기
대부분의 에이전트 실패는 하나의 질문으로 귀결됩니다: 모델이 유효한 작업을 반환했는가? Playwright를 연결하기 전에 이 문제를 확실히 해결하세요. Apidog를 사용하여 Qwen 3.7 Plus에 샘플 스크린샷을 보내고, 반환된 원시 JSON을 검사하며, 작업 스키마가 매번 깔끔하게 반환될 때까지 시스템 프롬프트를 조정하세요. 환경별로 Model Studio 키를 저장하고, 테스트 실행 시마다 토큰을 소모하지 않고 루프를 구축할 수 있도록 엔드포인트를 모의(mock)하세요. 전체 루프가 호출을 연결할 때, Apidog의 AI 에이전트 디버거는 시퀀스를 보여주어 어떤 단계에서 문제가 발생했는지 파악할 수 있도록 돕습니다.
디자인에서 UI 코드를 생성하는 방법에 대해서는 Qwen 3.7 Plus를 사용한 스크린샷-투-코드 동반 가이드를 참조하세요.
에이전트 뒤의 모델 호출을 테스트하고 디버그하려면 Apidog를 다운로드하세요.
자주 묻는 질문
컴퓨터 사용 에이전트란 무엇인가요? 스크린샷을 통해 화면을 인식하고, 모델로 작업을 결정하며, 자동화 드라이버를 통해 실행하여 목표가 달성될 때까지 반복하는 소프트웨어입니다.
Qwen 3.7 Plus가 제 데스크톱을 제어할 수 있나요? 모델은 작업만 반환합니다. 이 작업을 드라이버로 실행합니다. 브라우저의 경우 Playwright와, 네이티브 앱의 경우 데스크톱 자동화 라이브러리와 함께 사용하세요.
각 단계의 비용은 얼마인가요? 주로 스크린샷이 비용의 대부분을 차지합니다. 단일 화면 이미지는 백만 토큰당 0.40달러로 수천 개의 입력 토큰에 이를 수 있으므로, 축소 및 루프 제한이 주요 비용 절감 수단입니다.
운영 환경에서 사용할 만큼 신뢰할 수 있나요? 각 단계 후 검증이 있는 제한적이고 잘 정의된 작업의 경우 그렇습니다. 중요한 시스템의 개방형 제어의 경우, 인간을 루프에 포함하고 모든 것을 샌드박스 처리해야 합니다.
좌표를 스케일링해야 하나요? 스크린샷 해상도가 뷰포트와 일치한다면 그럴 필요가 없습니다. 다르다면, 반환된 좌표를 그 비율에 따라 스케일링해야 합니다.
결론
컴퓨터 사용 에이전트는 하나의 유능한 모델을 중심으로 하는 짧은 루프이며, Qwen 3.7 Plus는 이를 실행할 수 있는 기반과 가격을 제공합니다. 루프를 구축하고, 제한하고, 샌드박스 처리하고, 각 단계를 검증하세요. 그런 다음 에이전트가 클릭을 시작하기 전에 "결정" 단계가 견고한지 Apidog에서 모델 호출을 테스트하세요.