컴퓨터 사용

컴퓨터 사용 (Computer use)

Computer use는 모델이 브라우저·데스크톱 인터페이스를 조작하게 해요. 폼을 채우고, 사용자 흐름을 테스트하고, 앱에서 UI를 통해 과업을 완료하는 데 쓰세요.

출처: 문서

본문

여러분이 환경을 제공하고 모델의 요청을 실행해요. 모델은 스크린샷과 다른 도구 결과를 보고 다음에 무엇을 할지 결정해요. 앱에 연결하는 방법을 선택하세요.

코드 실행(Code execution): 모델이 PyAutoGUI나 Playwright 같은 라이브러리로 인터페이스를 조작하는 코드를 작성해요. 한 번의 호출이 액션·루프·조건 로직을 결합할 수 있어요.
computer 도구: 모델이 구조화된 마우스·키보드 액션을 반환하고, 앱이 그걸 브라우저·데스크톱 입력으로 변환해요.

GPT-6 Astra에서는 코드 실행을 권장해요. computer 도구는 대안으로 계속 지원돼요.

이미 함수 호출이나 원격 MCP 도구로 UI 연산을 노출하고 있다면 그 인터페이스를 유지할 수 있어요. 이런 통합이 도구를 실행하고 결과를 반환하는 방식의 차이는 Use your own UI tools를 참고하세요.

코드 실행 사용하기

코드 실행 통합은 모델에 스크립트를 받는 함수 도구를 제공해요. 앱이 그 스크립트를 격리된 브라우저·데스크톱 환경에서 실행하고, 스크린샷을 포함한 출력을 반환해요. 모델이 이전 작업 위에 쌓을 수 있도록 호출 사이에 환경을 유지하세요.

샘플 앱 실행하기

CUA 샘플 앱에는 JavaScript/Playwright와 Python/PyAutoGUI 구현이 있고, 로컬 태스크와 공유 콘솔이 있어요.

선택한 구현의 설정 지시를 격리된 환경에서 따르세요.
내장 시나리오를 고르고 실행을 시작하세요.
액션·스크린샷·최종 상태를 검사해 과업이 성공했는지 평가하세요.

앱의 README로 설치, 데스크톱 권한, 지원 환경을 참고하세요. 실제 사이트·계정에 적용하기 전에 안전하게 실행하기를 검토하세요.

자체 런타임 연결하기

아래 예시는 여러분이 제공하는 런타임의 API 루프를 보여줘요. Python·Ruby는 PyAutoGUI를 쓰는 데스크톱 런타임에 Python 코드를 보내고, JavaScript는 Playwright로 브라우저를 조작해요. 각 클라이언트는 일반 함수 도구를 노출하고 원래 call_id와 함께 텍스트·이미지를 반환해요.

execute_in_sandbox(또는 executeInSandbox) 헬퍼가 코드를 실행 환경에 보내고 관찰 결과를 반환해요. 이 헬퍼는 브라우저·데스크톱 세션을 보존하고, 실행 한도를 적용하며, 권한 규칙을 적용해야 해요. 이것은 샘플 앱을 실행하는 것과는 별개의 통합 예시예요.

import json
import uuid

from openai import OpenAI
from openai.types.responses import FunctionToolParam, ResponseInputParam

def run_computer_use(endpoint, prompt, model="gpt-6-astra"):
    client = OpenAI()
    session_id = str(uuid.uuid4())
    tools: list[FunctionToolParam] = [
        {
            "type": "function",
            "name": "exec_py",
            "description": (
                "Run Python in a persistent desktop. Variables persist across calls. "
                "PyAutoGUI operations are synchronous. Available: pyautogui, time, "
                "log(value), and display(PIL_image). Inspect the screen with "
                "display(pyautogui.screenshot()) before acting. Use screenshot "
                "coordinates and check the screen after a short group of actions. "
                "Keep screenshots in memory and PyAutoGUI's fail-safe enabled."
            ),
            "parameters": {
                "type": "object",
                "properties": {"code": {"type": "string"}},
                "required": ["code"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ]
    next_input: ResponseInputParam = [{"role": "user", "content": prompt}]
    previous_response_id = None

    for turn in range(20):
        response = client.responses.create(
            model=model, tools=tools, input=next_input,
            previous_response_id=previous_response_id,
        )
        if response.status != "completed":
            raise RuntimeError(f"Response stopped with status: {response.status}")

        calls = [item for item in response.output if item.type == "function_call"]
        if not calls and any(
            item.type == "message" and item.phase != "commentary"
            for item in response.output
        ):
            print(response.output_text)
            return
        if turn == 19:
            raise RuntimeError("The task reached the 20-response limit.")

        next_input = []
        for call in calls:
            code = json.loads(call.arguments)["code"]
            output = execute_in_sandbox(code, session_id, endpoint)
            next_input.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": output,
            })
        previous_response_id = response.id

완전한 클라이언트 어댑터와 기대되는 텍스트·이미지 출력 형태는 Connect to your execution service를 참고하세요. 그 예시들의 서비스 인터페이스는 여러분의 앱에 속한 것이고, OpenAI 호스팅 엔드포인트가 아니에요.

상태 보존하고 관찰 결과 반환하기

호출 사이에 브라우저·데스크톱 세션을 유지하세요. 지속적인 Python·JavaScript 네임스페이스도 변수를 보존할 수 있어요. 모델이 무엇을 쓸 수 있는지 알도록 도구 정의에서 사용 가능한 객체·헬퍼를 설명하세요.

UI 상태를 알 수 없을 때 모델에 현재 스크린샷을 주세요. 짧은 액션 그룹 후 또 다른 스크린샷을 반환해 결과를 확인하게 해요. 이미지를 메모리에 유지하고 detail: "original"로 해상도를 보존하세요. 스크린샷을 축소했다면 액션을 실행하기 전에 모델의 좌표를 환경의 좌표 공간으로 다시 매핑하세요. 스크린샷 캡처·해상도를 참고하세요.

API 대화와 실행 환경은 별개 상태예요. 도구 호출과 그 출력을 대화에 보존하고, 대응 환경을 앱에서 사용 가능하게 유지하세요. 응답을 계속해도 브라우저 세션·로그인 상태·런타임 변수는 복원되지 않아요.

computer 도구 사용하기

이 대안은 통합이 생성된 코드 대신 구조화된 액션을 기대할 때 써요. 권장 접근은 코드 실행에서 시작하세요. 이 경로를 시도하려면 같은 샘플 앱 설정을 따르고 Native 모드를 선택해 내장 시나리오를 실행하세요. computer 도구를 지원하는 모델을 사용하세요.

API 교환은 세 단계예요. 과업 보내기, 반환된 액션 실행하기, 스크린샷 반환하기. 여기 스니펫은 Show filters 컨트롤과 검색 필드가 있는 페이지를 사용해요. 도구를 통합할 때 이 과업을 자신의 인터페이스에 맞게 조정하세요. 환경 설정과 액션 핸들러는 통합 레시피를 사용해요.

과업 보내기

tools 배열에서 computer를 활성화하고 원하는 결과를 설명해요.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-sol",
    tools=[{"type": "computer"}],
    input="Check whether the Filters panel is open. If it is not open, click Show filters. Then type penguin in the search box. Use the computer tool for UI interaction.",
)

print(response.output)

요청된 액션 실행하기

computer_call에는 순서가 정해진 actions 배열이 들어 있어요. 예를 들어 검색 필드를 선택하고 penguin을 입력하는 호출:

{
  "output": [
    {
      "type": "computer_call",
      "call_id": "call_002",
      "actions": [
        { "type": "click", "button": "left", "x": 405, "y": 157 },
        { "type": "type", "text": "penguin" }
      ],
      "status": "completed"
    }
  ]
}

액션 핸들러가 이 요청을 브라우저·운영체제 입력으로 변환해요. 허용된 액션을 순서대로 실행한 뒤 갱신된 화면을 캡처해요. 모델은 click, double_click, drag, move, scroll, keypress, type, wait, screenshot을 요청할 수 있어요. 첫 호출은 screenshot 액션만 포함할 수 있어요. 그 경우 UI를 바꾸지 않고 현재 화면을 캡처해 반환해요. 호출의 status: "completed"는 모델이 그 호출 생성을 끝냈다는 뜻이고, 앱이 여전히 실행해야 해요. 키 매핑·드래그 경로·수정자 키는 액션 핸들러 예시를 참고하세요.

스크린샷 반환하기

처리한 호출과 일치하는 call_id의 computer_call_output을 반환해요. previous_response_id로 모델 대화를 계속해요.

from openai import OpenAI

client = OpenAI()


def send_computer_screenshot(response, call_id, screenshot_base64):
    return client.responses.create(
        model="gpt-5.6-sol",
        tools=[{"type": "computer"}],
        previous_response_id=response.id,
        input=[
            {
                "type": "computer_call_output",
                "call_id": call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot_base64}",
                    "detail": "original",
                },
            }
        ],
    )

이 루프에도 스크린샷·상태 지침이 적용돼요. previous_response_id가 모델 대화를 계속하는 동안 환경을 사용 가능하게 유지하세요.

계속하고 결과 확인하기

모델이 computer_call 항목을 반환하지 않을 때까지 계속해요. 남은 출력에서 답·도움 요청·다른 도구 호출을 검사하고 앱에서 결과를 확인해요. 이 예시에서는 Filters 패널이 열리고 검색 필드에 penguin이 있어야 해요. 루프 스켈레톤(필수 액션·스크린샷 헬퍼 포함)은 Repeat the computer-use loop를 참고하세요.

안전하게 실행하기

컴퓨터 사용은 실제 계정과 데이터에 영향을 줄 수 있어요. 앱·실행 환경·모델 지시 모두에 이 제어를 적용하세요.

환경을 제한하세요. 격리된 브라우저·VM과 사이트·액션 허용 목록을 사용해요. 과업이 필요한 것까지만 접근을 유지해요.
화면 콘텐츠를 신뢰하지 않음으로 취급하세요. 페이지·문서·도구 결과의 텍스트는 권한을 부여하거나 사용자 지시를 덮어쓸 수 없어요.
결과가 중대한 액션을 확인하세요. 구매, 데이터 전송, 파괴적 변경, 되돌리기 어려운 다른 액션에 사용자를 계속 통제하게 해요. 폼에 민감 정보를 입력하는 것도 전송으로 간주돼요.
실행을 경계 짓고 검증하세요. 단계·시간·비용 한도를 설정하고, 취소를 지원하고, 모델의 최종 답변만 신뢰하지 말고 실제 결과를 확인해요.

구체적인 승인 요구사항, 인간 핸드오프, 프롬프트 예시는 확인·동의 지침을 참고하세요.

컴퓨터 사용