브라우저 및 데스크톱 드라이버

드라이버는 허용된 도구 호출을 직접 제어하는 브라우저나 데스크톱에서 수행할 동작으로 변환합니다. 애플리케이션이 페이지 텍스트, 컨트롤, 탭 정보를 제공할 수 있다면 브라우저 드라이버를 사용하세요. 모델이 스크린샷과 좌표를 바탕으로 작업해야 한다면 컴퓨터 드라이버를 사용하세요. SDK는 요청을 보내고 호출을 전달하며, 애플리케이션은 세션과 권한을 관리하고 리소스를 정리합니다.

공통 제어 설정

Python 또는 Node 브라우저 예제부터 살펴보세요. 전체 드라이버 구현, 승인 정책, 요청 횟수가 제한된 Responses 실행을 보여 줍니다. 실행이 끝날 때까지 세션을 열어 두세요. Python은 동기 드라이버용으로 동기 클래스 BrowserToolset과 ResponsesToolRunner도 제공합니다.

동작 승인 및 세션 관리

신뢰할 수 있는 애플리케이션 코드에서 드라이버와 승인 콜백을 만드세요. 실행 가능한 설정은 신뢰할 수 없는 페이지 데이터와 분리하고, 페이지 데이터는 드라이버에 선언된 보고 필드로 반환하세요.

선택한 브라우저 메서드가 상태를 변경하거나 진단 정보를 읽는다면 confirm이 필요합니다. Node에서는 정확히 true, Python에서는 정확히 True를 반환해야 동작이 승인됩니다. navigate와 new_tab에는 urlPolicy(Node) 또는 url_policy(Python)도 필요합니다. 두 콜백 모두 member, 검증된 arguments, 이전 state, call_id가 담긴 별도의 객체를 받습니다. URL 정책 콜백에는 요청된 URL도 전달됩니다. 이 객체를 수정해도 검증된 동작은 바뀌지 않습니다.

confirm은 확정된 동작 인수를 승인합니다. 이때 state는 이전에 관찰한 상태이며 문서나 포커스된 컨트롤을 잠그지 않습니다. 사람이 승인 여부를 결정하는 동안 페이지가 이동하거나 포커스가 바뀔 수 있습니다. 특정 페이지나 컨트롤에 대한 동의가 필요하다면 드라이버가 실행 시점에 원래 대상을 확인해야 합니다. 이 플로우에서는 key를 비활성화하고 대상이 null인 type을 거부하세요. 둘 다 현재 포커스를 사용합니다. 현재 브라우저 상태에 의존하는 다른 동작도 같은 방식으로 대상에 연결하세요.

비공개 페이지를 읽기 전에 승인을 요청하려면 confirmReads(Node) 또는 confirm_reads(Python)에 읽기 멤버를 나열하세요. 드라이버가 상태나 콘텐츠를 읽기 전에 동일한 confirm 콜백이 실행됩니다. 이때 컨텍스트에는 phase: "before_read"가 있으며 상태는 Node에서 state: null, Python에서 None입니다. 이 경우 페이지 메타데이터를 읽지 않고 처리하세요. 거부하면 페이지 콘텐츠나 상태가 반환되지 않습니다. 이 옵션을 지정하지 않으면 기존 읽기 동작이 유지되며 필수 동작 승인도 계속 적용됩니다.

컴퓨터 호출에서는 헬퍼가 동작을 하나라도 실행하기 전에 대기 중인 안전 점검을 모두 승인해야 합니다. Node의 approveSafetyChecks와 Python의 approve_safety_checks는 불리언 참값을 반환해야 합니다. 콜백이 없거나 승인을 거부하면 실행이 중단됩니다. 선택 사항인 beforeAction 또는 before_action은 마지막 스크린샷을 포함해 각 동작을 실행하기 직전에 검사합니다. 이 콜백을 제공한 경우에도 명시적으로 승인해야 합니다. 모델의 선택이나 완료 메시지로 승인을 대신할 수 없습니다. 컴퓨터 사용 안전 지침을 참고하세요.

Node는 두 컴퓨터 승인 콜백의 마지막 인수로 { signal }을 전달합니다. Python은 콜백이 선택적 키워드 인수 cancelled를 받으면 이를 전달합니다. 인수가 더 적은 기존 콜백도 계속 지원됩니다. 실행이 중단되면 이 컨텍스트를 사용해 대기 중인 승인 창을 닫으세요. 헬퍼는 콜백 처리가 끝난 뒤 세션을 해제합니다.

컴퓨터 동작 승인은 확정된 인수에 적용됩니다. 사람이 결정하는 동안 화면이나 포커스가 고정되지는 않습니다. 동의가 특정 대상에만 유효하다면 드라이버가 동작을 해당 대상에 연결하거나 상태 변경 후 동작을 거부해야 합니다. 컴퓨터 동작은 네트워크 접근이 제한된 격리 환경에서 실행하세요.

URL 제한

작업에 필요한 경우에만 navigate 또는 new_tab을 활성화하세요. Node에서는 confirm과 urlPolicy를, Python에서는 confirm과 url_policy를 모두 제공하세요. URL 콜백은 (context, url)을 받으며, Node에서는 선택적 실행 컨텍스트를, Python에서는 cancelled 키워드 인수를 추가로 받을 수 있습니다. SDK가 confirm으로 진행하려면 URL 콜백이 불리언 참값을 반환해야 합니다. URL이 null인 새 빈 탭도 승인이 필요하지만 검사할 URL은 없습니다.

요청된 URL을 파싱하세요. 프로토콜, 호스트 이름, 포트를 작업에서 허용하는 목적지와 비교하세요. 문자열 접두사만 비교하면 안 됩니다. https://example.com.evil.test를 https://example.com으로 간주해서는 안 됩니다. 탐색을 지원하지 않는 브라우저 드라이버에는 URL 콜백이 필요하지 않습니다. 브라우저 예제에서는 이러한 메서드를 비활성화한 상태로 둡니다.

브라우저나 실행 환경에도 네트워크 정책을 적용하세요. 콜백은 요청된 탐색을 검사하지만 리디렉션, 팝업, 페이지 스크립트, 삽입된 리소스를 제한할 수 없습니다. 요청 간에는 하나의 격리된 세션을 유지하고 애플리케이션이 생성한 리소스는 닫으세요. 빌려 쓴 리소스는 소유자가 관리하도록 두세요.

사용량 및 소요 시간 확인

ResponsesToolRunner를 사용할 때 Node에서는 onDiagnostic, Python에서는 on_diagnostic을 run에 전달하세요. Responses 요청이 완료될 때마다 콜백은 api: "responses", stage: "request", reason: "completed", usage가 포함된 기록을 받습니다. API가 사용량을 제공하면 input_tokens, output_tokens, total_tokens가 포함됩니다. 제공하지 않으면 사용량 값은 Node에서 null, Python에서 None입니다. 완료된 요청 전체에서 각 토큰 필드의 값을 합산해 실행 사용량을 측정하세요. 사용량이 없는 요청이 하나라도 있으면 합계는 불완전합니다.

ComputerToolset.run은 진단 콜백으로 요청 사용량을 보고하지 않습니다. 반환된 응답에는 마지막 요청의 사용량만 포함될 수 있습니다. 요청별 사용량이 필요하면 ResponsesToolRunner와 ComputerToolset을 함께 사용하세요.

진단 기록에는 API, 단계, 사유, 호출 ID, 멤버, 측정된 소요 시간도 표시됩니다. 원본 오류, 페이지 텍스트, 인수, 이미지는 포함되지 않습니다. 관찰자에서 오류가 발생해도 동작이 승인되거나 결과가 바뀌지 않습니다. 애플리케이션이 호출 ID나 멤버 이름에 비공개 데이터를 넣는다면 공개 로그에서 제외하세요.

동기 관찰자를 사용하세요. 러너는 진단 작업이 끝날 때까지 기다리지 않으므로 비동기 저장은 애플리케이션에서 별도로 예약하세요.

조기 실행에서는 스트림 수신 시간에 동작 시간이 포함될 수 있어 단계별 측정 시간이 겹칠 수 있습니다. 전체 실행 시간을 계산할 때 이 값들을 더하지 마세요.

작업 종료 및 취소

헬퍼는 호출이 겹치면 사용 중 오류를 반환합니다. 러너도 같은 인스턴스에서 실행이 진행 중이면 두 번째 실행을 거부합니다. 각 브라우저 또는 데스크톱 세션은 한 소유자가 관리하도록 하세요.

새 작업을 거부하려면 헬퍼의 close()를 호출하세요. 활성 호출이 없으면 status는 closed이고, 이전 호출에서 사이드 이펙트가 여전히 발생할 수 있으면 draining입니다. 상태가 draining이면 원래 실행 호출이 끝날 때까지 기다린 다음 드라이버를 닫거나 세션을 다른 소유자에게 넘기세요. 헬퍼가 브라우저나 데스크톱을 닫아 주지는 않습니다. 드라이버 콜백 안에서 close()를 호출해도 해당 콜백 자체가 끝나기를 기다리지는 않습니다.

취소 요청을 처리하는 Node 드라이버 메서드와 일반 함수는 signal이 담긴 컨텍스트를 두 번째 인수로 받을 수 있습니다. Python 메서드는 cancelled 키워드 인수를 받을 수 있습니다. 탐색이나 스크린샷 캡처처럼 오래 걸리는 작업 중에는 취소 여부를 확인하세요. 인수가 하나인 기존 콜백도 유효하지만 SDK가 강제로 중단시키거나 이미 발생한 사이드 이펙트를 되돌릴 수는 없습니다.

브라우저 드라이버 구현 규약

state()와 노출하려는 연산만 구현하세요. Node 메서드는 값이나 프로미스를 반환할 수 있습니다. Python은 동기 클래스와 비동기 클래스를 별도로 제공합니다. 각 연산은 검증된 인수 객체 또는 딕셔너리 하나를 받습니다. 값이 없어도 되는 탭 ID와 대상에는 Node에서 null, Python에서 None을 명시하세요.

Python은 헬퍼를 생성할 때 식별 가능한 동기·비동기 불일치를 거부합니다. async def 메서드를 AsyncBrowserToolset과 함께 사용하세요. 래퍼에는 데코레이터 메타데이터나 반환 타입 어노테이션을 보존하세요. 내부 동작을 식별할 수 없는 래퍼는 호출 시 검사합니다. BrowserReadDriver와 AsyncBrowserReadDriver 같은 선택적 프로토콜을 사용하면 모든 연산을 구현하지 않고도 일부 기능만 제공하는 드라이버에 타입을 지정할 수 있습니다. Node는 해당 입력 및 출력 타입으로 BrowserArguments<Member>와 BrowserResult<Member>를 내보냅니다.

state()는 tabs를 보고합니다. 이 배열의 각 객체에는 id, title, url, active가 있습니다. 탭마다 일관된 ID를 사용하고 실제 활성 탭을 표시하세요. 제목과 URL에서 자격 증명과 비공개 정보를 제외하세요. SDK는 일반 연산 후에는 실패한 경우에도 현재 상태를 반환합니다. 승인이 필요한 읽기가 거부되면 상태를 읽거나 노출하지 않고 정해진 거부 응답을 반환합니다. 필수 상태 읽기가 실패하면 실행이 중단됩니다. Node의 상태 읽기 메서드는 { signal }을 받으며 Python에서는 cancelled 키워드 인수를 받을 수 있습니다. 호출자가 실행을 중단하면 이 컨텍스트로 대기 중인 상태 읽기를 종료하세요. 인수가 없는 기존 상태 읽기 메서드도 계속 지원됩니다.

탭 상태에는 https://example.com:8443과 같은 HTTP 및 HTTPS 오리진이 보고되며 자격 증명, 경로, 쿼리, 프래그먼트는 제외됩니다. 관찰 메타데이터가 없는 레거시 상태에서는 about:blank를 그대로 유지하고 다른 URL은 data: 또는 file:처럼 스킴만 보고합니다. UTF-8 기준 2,048바이트 제한은 보고되는 값에 적용되므로 페이지 경로가 길어도 상태 읽기가 차단되지 않습니다. V1 관찰 메타데이터가 있는 상태에서는 제목을 문자 경계에서 UTF-8 기준 1,024바이트 이내로 자르고 필요하면 title_truncated를 설정합니다. 제목과 페이지 콘텐츠에는 여전히 애플리케이션의 개인정보 보호 규칙을 적용해야 합니다.

메서드 선택

기본적으로 SDK는 다음 18개 메서드 중 구현된 메서드를 노출하며, list_tabs는 state()에서 파생합니다. list_tabs를 구현하지 마세요. members 목록으로 노출할 메서드를 줄이거나 범위 지정 및 마우스 포인터 메서드 또는 진단, 스크립트 및 파일 메서드를 명시적으로 활성화할 수 있습니다. 이름은 중복 없이 지정해야 하며, 드라이버가 구현한 정해진 멤버만 사용할 수 있습니다. list_tabs만 state() 외에 별도 메서드가 필요하지 않습니다. 목록이 비어 있으면 아무 메서드도 노출하지 않습니다. SDK는 생성 시 선택 목록을 복사하고 자체 도구 순서를 유지합니다. 비활성화된 호출은 상태를 읽거나 동의를 요청하기 전에 거부합니다.

구현된 기본 메서드를 유지하면서 선택적 메서드를 추가하려면 Node에서는 additionalMembers, Python에서는 additional_members를 사용하세요. members와 함께 사용하지 마세요. 추가하려는 메서드는 드라이버에 있어야 합니다. BROWSER_MEMBERS와 DEFAULT_BROWSER_MEMBERS는 드라이버를 검사하지 않고 정해진 이름 목록을 제공합니다.

list_tabs를 비활성화해도 다른 연산이 성공한 뒤 반환하는 상태는 숨겨지지 않습니다. Python과 Node에서 members는 브라우저 헬퍼가 노출할 메서드를 제한합니다. 일반 함수 이름은 browser_로 시작해도 되지만 활성화된 브라우저 도구와 이름이 같으면 안 됩니다.

switch_tab과 close_tab을 제외하면 표의 tab_id는 null일 수 있습니다. 방향은 up, down, left, right 중 하나입니다. Node의 BrowserArguments<Member>는 각 인수 객체를 정의합니다. Python은 TabInput, ReadPageInput, ClickInput처럼 이름이 지정된 입력 타입을 제공합니다.

read_page, find, get_page_text에서 갱신된 브라우저 상태만 제공하려면 Node에서는 null을 반환하거나 값을 반환하지 말고, Python에서는 None을 반환하세요. 읽기는 완료됐지만 텍스트가 없으면 빈 문자열을 반환하세요.

표의 Node 연산 중 list_tabs를 제외한 모든 연산은 { signal }을 두 번째 인수로 받습니다. list_tabs는 앞서 설명한 상태 읽기 메서드를 사용합니다. Python은 메서드가 cancelled를 받으면 키워드 인수로 전달합니다. 이 컨텍스트를 사용해 탐색과 입력을 포함한 대기 중 작업을 중단하세요. 인수가 하나인 기존 메서드도 계속 지원됩니다.

wait_for에는 공백을 정규화한 뒤 비어 있지 않고 UTF-8 기준 256바이트 이하인 텍스트를 사용하세요. 제한 시간은 1~30,000밀리초여야 합니다. scroll_to 실행 후에는 컨트롤을 조작하기 전에 현재 페이지를 다시 읽으세요.

구조화된 읽기 결과 보고

read_page, find, get_page_text는 BrowserReadV1을 반환할 수 있습니다. 여기에는 version: 1, 화면에 보이는 text, elements 배열, omitted 배열이 포함됩니다. 각 요소에는 고유한 ref, 비어 있지 않은 label, 그리고 button, textbox, combobox, checkbox, radio, slider, listbox 중 하나의 역할이 있습니다.

애플리케이션이 모델에 공개하도록 허용한 경우에만 필드의 value나 options(label과 value 쌍)를 보고하세요. 체크박스나 라디오 버튼은 불리언 checked를, listbox의 옵션은 불리언 selected를 보고할 수 있습니다. SDK는 다른 역할에서 이 필드를 생략합니다. Node는 undefined로 설정된 선택적 필드를 생략하고 해당 필드의 null 값은 거부합니다. get_page_text는 빈 elements 배열을 반환해야 합니다. SDK는 일반 문자열을 파싱해 구조화된 읽기 결과로 변환하지 않습니다.

SDK는 요소나 옵션 개수, 페이지 텍스트 크기, 전체 보고서 크기를 제한하지 않습니다. 참조와 레이블은 각각 256바이트, 값은 512바이트까지 허용됩니다. 유효한 유니코드 스칼라 값을 사용하세요. 드라이버는 중복 없는 omitted 코드로 일부만 보고했음을 표시할 수 있습니다. 가능한 코드는 report_limit, text_limit, target_limit, work_limit, frame_limit, unsupported_root, unsupported_control, remote_action, private, value, name_limit입니다.

드라이버는 요소의 표시 여부, 필드의 공개 범위, 참조의 유효성을 관리합니다. 승인 후 동작을 수행하기 전에 현재 페이지에서 참조를 다시 확인하세요. 컨트롤의 레이블이 공개되어 있어도 그 값을 읽을 권한까지 부여되지는 않습니다. 크기를 제한하는 것만으로 페이지 콘텐츠의 안전성이 보장되지는 않습니다.

브라우저 이미지 반환

screenshot과 zoom은 네이티브 input_image를 반환하며, 비어 있지 않은 image_url 또는 file_id가 하나 이상 있어야 합니다. 두 소스 필드가 모두 있어도 됩니다. null이 아닌 각 소스는 비어 있지 않은 문자열이어야 합니다. 지원 필드는 type, image_url, file_id, detail, prompt_cache_breakpoint입니다. 캐시 중단점은 { mode: "explicit" }이어야 하며, 네이티브 콘텐츠 타입이 허용하는 경우 null도 가능합니다. SDK는 이미지를 반환하기 전에 이 필드를 검증하고 복사합니다. 두 Node 메서드는 모두 ResponseInputImageContent를 반환하며 detail은 생략하거나 null로 설정할 수 있습니다. 값을 지정하려면 auto, low, high, original 중 하나를 사용하세요.

zoom에서 region은 [left, top, right, bottom]입니다. 좌표는 0 이상의 안전한 정수여야 하고 너비와 높이는 양수여야 합니다. 드라이버가 이미지 자르기와 경계 검사를 담당합니다. 이후의 모든 좌표도 화면에 보이는 전체 영역을 기준으로 합니다.

범위 지정 및 마우스 포인터 메서드 활성화

다음 브라우저 메서드 6개는 드라이버에 구현되어 있어도 기본적으로 비활성화됩니다. members로 선택하거나 Node에서는 additionalMembers, Python에서는 additional_members로 추가하세요. 기존 기본 메서드 18개의 이름, 인수, 결과 타입은 그대로 유지됩니다. members를 사용한다면 screenshot이나 read_page처럼 계속 필요한 기본 메서드도 포함하세요.

Node는 BrowserArguments<Member>를 사용합니다. Python은 ReadPageScopedInput, ClickAtInput, DragPathInput, HoldKeysInput, HoverAtInput, SetCheckedInput을 내보냅니다. 모든 필드는 필수이며 활성 탭을 지정할 때 tab_id는 null 또는 None일 수 있습니다. 경로의 점에 추가된 필드를 포함해 정의되지 않은 필드는 거부됩니다. 숫자는 유한한 안전 정수여야 합니다. Python은 숫자가 필요한 위치에서 True와 False를 거부합니다.

click_at은 0 이상인 x와 y를 받습니다. button에는 left, right, middle 중 하나를, click_count에는 1, 2, 3 중 하나를 지정합니다. drag_path는 좌표가 0 이상이고 정확히 {x, y} 형식인 점을 2~100개 받습니다. 두 메서드 모두 확대 후에도 페이지에서 보이는 전체 영역의 CSS 픽셀을 기준으로 합니다. 드라이버가 현재 경계를 확인해야 합니다. 각 메서드의 keys 필드에는 Control, Alt, Meta, Shift 보조 키를 중복 없이 나열합니다. 목록은 비어 있어도 됩니다.

hover_at은 버튼을 누르지 않고 마우스 포인터를 현재 CSS 좌표로 이동합니다. set_checked는 체크박스를 요청된 불리언 상태로 설정합니다. true로 두 번 설정해도 체크된 상태로 유지되어야 합니다. 상태가 바뀌지 않는 동작도 원래 대상이 여전히 유효한지 확인하고 승인을 받아야 합니다. 오래되었거나 교체된 컨트롤을 받아들이면 안 됩니다.

hold_keys는 중복되지 않는 비어 있지 않은 키 이름을 1개에서 8개까지 받습니다. 각 이름은 유효한 유니코드 스칼라 값으로 이루어져야 하며 UTF-8 기준 64바이트 이하여야 합니다. duration_ms는 1 이상 3000 이하여야 합니다. 상태를 변경하는 메서드는 confirm이 불리언 참값을 반환해야 합니다. 취소 요청을 처리하는 메서드에는 호출별 취소 컨텍스트가 전달됩니다. Node는 두 번째 인수로 { signal }을 전달하고 Python은 메서드가 cancelled를 받으면 키워드 인수로 전달합니다. 인수가 하나인 기존 메서드도 유효합니다.

섹션 내에서 읽기

범위를 지정해 읽는 read_page_scoped에서 root가 null이면 화면에 보이는 섹션을 찾습니다. null이 아닌 루트에는 선택자 대신 드라이버가 발급한 범위 참조를 사용해야 합니다. 참조는 비어 있지 않은 유효한 유니코드 문자열이어야 하며 UTF-8 기준 256바이트 이하여야 합니다. depth는 1~32로, filter는 all 또는 interactive로 설정하세요. 깊이는 해당 루트 내에서 DOM을 탐색하는 깊이로 계산하며 프레임이나 섀도 DOM의 제한과는 별개입니다.

결과로 BrowserScopedReadV1을 반환하세요. 이 타입은 기존 읽기 결과에 scopes: [{ref, label}]을 추가합니다. 범위 참조와 레이블은 비어 있지 않은 유효한 유니코드 문자열이어야 하며 UTF-8 기준 256바이트 이하여야 합니다. 범위 참조는 고유해야 하며 요소 참조와도 겹치면 안 됩니다. 이 메서드는 문자열 및 null 결과를 거부합니다. SDK는 최종 상태를 요청하기 전에 알려진 필드를 복사합니다.

범위 참조는 다음 읽기의 루트를 선택할 때만 사용하세요. 요소를 변경하는 연산은 범위 참조를 거부해야 합니다. 탭, 문서, 세대 또는 표시 여부가 바뀌면 범위 참조와 요소 참조를 함께 무효화하세요. 기존 필드 공개 규칙과 총 작업량 및 읽기 제한을 유지하세요.

진단, 스크립트 및 파일 전송 활성화

다음 네 메서드도 기본적으로 비활성화됩니다. 각 메서드를 members에서 선택하거나 additionalMembers 또는 additional_members로 추가하세요. 진단 읽기를 포함해 모두 confirm을 제공해야 합니다. 드라이버에 구현하는 것만으로는 모델에 노출되지 않습니다.

진단 정보를 읽는 read_diagnostics의 소스로 console 또는 network를 선택하고 한도는 1~100으로 지정하세요. 빈 elements 배열이 포함된 구조화된 읽기 결과를 반환하세요. Node에서는 BrowserTextReadV1 결과 타입을 사용하세요. 드라이버는 비공개 데이터를 걸러 내고 보관하는 이력의 범위를 제한해야 합니다. 원본 헤더, 쿠키, 자격 증명, 필터링하지 않은 콘솔 메시지를 반환하지 마세요.

run_script는 비어 있지 않은 유효한 유니코드 소스와 1~30,000밀리초의 제한 시간을 받습니다. SDK는 소스 전체를 보존합니다. 유효한 유니코드 텍스트를 반환하세요. 빈 문자열은 유효하지만 null 결과는 허용되지 않습니다. SDK는 큰 결과도 그대로 유지합니다. 스크립트는 페이지의 권한으로 실행됩니다. 자격 증명이 없는 새 세션을 사용하고 네트워크 접근을 제한하세요. 실행 상태가 불확실해지면 세션을 폐기하세요. 로컬에서 대기를 중단했다고 해서 페이지 스크립트도 중단되었다고 단정할 수는 없습니다.

파일 메서드는 호출자가 발급한 grant_id만 받습니다. 이 값은 비어 있지 않은 유효한 유니코드 문자열이어야 하며 UTF-8 기준 256바이트 이하여야 합니다. 이 권한 ID는 해당 작업에 대해 승인된 파일 하나를 식별하며 경로나 URL이 아닙니다. 파일 소유자는 파일에 대해 별도로 승인을 받아야 합니다. 만료 여부와 소유권을 다시 확인하고 크기 제한을 적용하며 권한은 한 번만 사용하도록 해야 합니다. 브라우저 동작 승인으로 파일 승인을 대신할 수 없습니다.

정확히 version, status, effect, cleanup만 반환하세요. version은 1로 설정하세요. cleanup은 not_started, pending, completed 중 하나입니다. 유효한 상태와 사이드 이펙트의 조합은 다음과 같습니다.

SDK는 최종 브라우저 상태를 요청하기 전에 이 결과를 복사하고 검증합니다. completed일 때만 도구 출력의 ok가 true로 설정됩니다. 다른 경우에는 구조화된 결과가 유지되고 ok가 false이므로 러너는 해당 응답에서 이 결과에 의존하는 브라우저 호출을 건너뜁니다. 결과가 불확실한 전송을 재시도하기 전에 실제 파일과 애플리케이션 상태를 확인하세요. 파일 결과만으로 이후의 양식 제출이나 업무 처리가 성공했다고 판단할 수는 없습니다.

run_script, upload_file, download_file에는 호출별 취소 정보가 전달됩니다. Node는 두 번째 인수로 { signal }을, Python은 cancelled 키워드 인수를 전달합니다. Python은 ReadDiagnosticsInput, RunScriptInput, BrowserFileInput을 내보냅니다.

컴퓨터 드라이버 구현 규약

컴퓨터 드라이버는 네이티브 컴퓨터 동작을 받아 스크린샷을 반환하며 다음 메서드를 구현해야 합니다. Node에서는 ComputerDriver를 openai에서 가져오세요. Python에서는 ComputerDriver 또는 AsyncComputerDriver를 openai에서 가져오세요. 드라이버에 맞는 ComputerToolset 또는 Python의 AsyncComputerToolset도 openai에서 가져오세요.

동작 메서드는 스네이크 케이스 필드가 있는 기존의 자동 생성 컴퓨터 동작 객체를 받으며 값을 반환하지 않습니다. 동작을 실행할 수 없다면 오류를 발생시켜야 합니다. 지원하지 않는 입력을 조용히 무시하지 마세요. Node는 동기 결과와 프로미스를 모두 지원합니다. Python 비동기 메서드는 await로 완료를 기다리세요.

Python에서는 ComputerToolset에 동기 메서드를 사용하고, async def 메서드는 AsyncComputerToolset과 함께 사용하세요. 헬퍼는 생성 시 식별 가능한 불일치를 거부합니다. 메서드를 래핑할 때는 데코레이터 메타데이터나 반환 타입 어노테이션을 보존하세요. 내부 동작을 식별할 수 없는 래퍼는 호출 시 검사하므로 헬퍼가 불일치를 감지하기 전에 래퍼 자체의 코드가 실행될 수 있습니다.

Node에서는 ComputerCallInput을 ComputerToolset.execute()에 전달할 호출의 타입으로 사용하세요. 이 타입은 네이티브 호출과 actions 배열이 있고 pending_safety_checks를 생략한 최신 형식의 호출을 받습니다. 이처럼 점검 필드를 생략할 수 있는 경우 승인 콜백은 점검 목록이 비어 있는 별도의 호출 객체를 받습니다. 재전달되는 호출은 원래 필드를 유지합니다.

screenshot()은 computer_screenshot을 반환하며 image_url(데이터 URL 포함) 또는 file_id가 있어야 합니다. 컴퓨터 헬퍼에는 이미지 소스가 하나 이상 필요하며 두 소스 필드가 모두 있어도 됩니다. 헬퍼는 로컬 파일을 읽지 않습니다. 동작은 순서대로 한 번씩 실행되며, 이후 헬퍼가 최종 스크린샷을 캡처합니다. 드라이버 동작을 재시도하지 않습니다.

컴퓨터 도구만 사용하는 Responses 루프에는 ComputerToolset.run 또는 Python의 AsyncComputerToolset.run을 사용하세요. 프로젝트에서 사용 가능하고 컴퓨터 도구를 지원하는 모델을 선택하세요. 다른 도구와 함께 실행할 때는 컴퓨터 헬퍼를 Responses 러너의 computer 옵션으로 전달하세요. Node는 실행 옵션 computerOptions로 컴퓨터 콜백을 받고 Python은 approve_safety_checks와 before_action을 실행 메서드의 키워드 인수로 직접 받습니다. 브라우저 예제는 브라우저만 제어하며 네이티브 데스크톱을 구현하거나 검증하지 않습니다.

컴퓨터 헬퍼와 ResponsesToolRunner는 모두 Responses의 context_management를 통한 컨텍스트 압축을 지원합니다. 필수 항목 필드를 검사하고 암호화된 콘텐츠를 변경 없이 재전달합니다. ResponsesToolRunner에서는 이 네이티브 옵션이나 로컬 옵션 contextBudget 또는 context_budget 중 하나를 선택하세요. 두 방식을 함께 사용하지 마세요.

스크린샷 기반 작업 실행

첫 작업 실행에는 Python과 Node의 전체 예제가 있습니다. Responses 컴퓨터 도구로 로컬 브라우저에서 픽업 세부 정보를 표시합니다.

격리된 데스크톱 사용

운영체제 데스크톱을 제어하려면 Python 또는 Node의 전체 데스크톱 예제를 참고하세요. 두 예제 모두 격리된 Linux 게스트를 사용합니다. Apple silicon이 탑재된 Mac에서는 Linux 게스트가 가상 머신에서 실행되고, x86-64 Linux에서는 Docker에서 실행됩니다. 각 예제에는 API 키 없이 실행할 수 있는 로컬 실습이 포함되어 있습니다. 실제 API를 사용하는 작업에서는 브라우저 기록과 저장된 파일을 모두 확인합니다. 자체 환경에 적용하려면 Docker 구성 예시부터 살펴보고 앞서 설명한 드라이버 규약을 환경에 맞게 적용하세요.

브라우저 동작과 다른 도구 함께 사용

Responses 러너에서는 브라우저 및 컴퓨터 헬퍼를 일반 함수, 웹 검색, 파일 검색, 코드 인터프리터, 이미지 생성, 원격 MCP 도구와 함께 사용할 수 있습니다. 다음 요청에서 응답을 재전달할 때 서버 도구 결과의 네이티브 콘텐츠와 컨테이너 ID가 유지됩니다. 서버 결과가 실패했거나 불완전하거나 아직 완료되지 않았으면 로컬 동작 전에 턴이 중단됩니다.

실행에 서버 도구가 선언되어 있으면 eager가 활성화되어 있어도 로컬 호출은 전체 응답이 도착할 때까지 기다립니다. 러너가 안전하게 동작하려면 뒤이어 도착하는 서버 결과와 승인 요청을 검사해야 합니다.

해당 턴이 완료되면 Node의 supplyOutputs 또는 Python의 supply_outputs로 아직 실행을 시도하지 않은 일반 함수의 결과를 대체할 수 있습니다. 단, 함수 등록 시 재정의를 허용해야 합니다. 명시적인 조기 실행 정책이 없어도 사용할 수 있습니다. 대체 결과로 브라우저 호출, 컴퓨터 호출, MCP 승인 요청에 응답할 수는 없습니다.

이 러너가 이미지 생성 후 실행을 계속하려면 응답이 저장되어 있어야 합니다. Node의 store: false나 Python의 store=False는 image_generation을 선언한 경우 거부됩니다. 적절한 경우 저장 옵션을 true로 설정하거나 client.responses.create로 상태를 유지하지 않는 요청을 한 번만 보내세요. 러너가 자동으로 저장을 활성화하지는 않습니다.

검증 로직을 반복해서 작성하지 말고 타입이 지정된 함수 도구를 재사용하세요. Node에서는 zodResponsesFunction 또는 standardResponsesFunction을 runnerFunction으로 래핑하세요. 이 래퍼는 openai/helpers/responses-tool-runner에서 가져옵니다. 도구에 콜백이 포함되어 있어야 합니다. Python에서는 RegisteredFunction.from_tool 또는 AsyncRegisteredFunction.from_tool에 기존 pydantic_responses_function_tool과 타입이 명시된 실행기를 전달하세요. 인수가 유효하지 않으면 실행기가 호출되기 전에 중단됩니다. 콜백 출력이 유효하지 않으면 이미 발생한 사이드 이펙트를 반복하지 않고 실행을 중단합니다. RunnerFunction과 RegisteredFunction을 직접 등록하면 기존 인수 처리 방식이 유지됩니다.

MCP에는 Node의 approveMcp 또는 Python의 approve_mcp를 제공하세요. 콜백은 실제 승인 요청의 별도 사본을 받아 true 또는 false를 반환합니다. 러너는 응답을 해당 요청의 ID 및 선언된 서버에 연결합니다. 임의로 승인을 생성하거나 최종 메시지를 동의로 처리할 수 없습니다.

MCP 도구를 선언한 요청에서는 원장 사용 여부와 관계없이 SDK의 자동 재시도가 비활성화됩니다. 요청에 실패하면 다른 실행을 시작하기 전에 MCP 서버에서 실제로 어떤 작업이 수행되었는지 확인하세요.

실패 처리

오래된 참조처럼 복구할 수 있는 문제가 발생하면 모델에 공개해도 안전한 텍스트만 담아 BrowserError를 발생시키세요. 브라우저 연산에서 발생한 다른 오류에는 일반적인 실패 메시지가 표시됩니다. 이런 연산 실패가 발생하면 러너는 각 브라우저 호출의 출력을 제공하고 해당 응답의 나머지 브라우저 연산은 건너뜁니다. 모델은 다음 턴에서 다시 선택할 수 있습니다. 반환 결과나 상태가 유효하지 않으면 실행이 중단됩니다. 상태 보고 실패, 일반 함수 실패, 네이티브 컴퓨터 안전 점검 미승인 시에도 실행이 중단됩니다.

요청 한도는 maxSteps 또는 max_steps로 설정하세요. 기본값은 API 요청 20회입니다. 마지막으로 허용된 요청에서는 새로운 사이드 이펙트를 일으키는 작업을 시작할 수 없습니다. SDK가 HTTP 요청을 재시도해도 드라이버 동작은 다시 시도하지 않습니다. 연산 사이에 중단하려면 Node에서 signal, Python에서 cancelled를 사용하세요. 이미 진행 중인 드라이버 호출은 되돌릴 수 없는 경우가 있습니다.

ResponsesToolRunner는 모든 요청에서 tool_choice를 유지합니다. 항상 로컬 도구를 요구하는 선택 방식으로는 실행을 끝낼 수 없으므로 러너는 작업을 시작하기 전에 이를 거부합니다. 루프에는 auto를 사용하고 특정 도구 사용을 강제하는 단일 요청에는 responses.create를 사용하세요. 도구 사용이 필수여도 선언된 서버 도구를 선택할 수 있다면 유효합니다.

실행 문제 해결

클릭 위치가 어긋날 때

새 스크린샷을 캡처해 의도한 창이 표시되는지 확인하세요. 스크린샷과 동작에 같은 좌표계를 사용하세요. 800 × 600 스크린샷을 1600 × 1200 디스플레이에서 캡처해 보냈다면 클릭하기 전에 반환된 두 좌표를 각각 두 배로 늘리세요. 컴퓨터 드라이버가 잘라낸 스크린샷을 보내면 좌표의 배율을 조정한 뒤 잘라낸 영역의 오프셋을 더하세요. 브라우저 드라이버의 마우스 포인터 메서드는 확대 후에도 화면에 보이는 전체 페이지 영역의 CSS 픽셀을 사용합니다. 디스플레이 픽셀과 혼동하지 마세요.

스크린샷 크기는 입력 토큰 수와 비용에 영향을 줍니다. 이미지 크기와 모델 제한은 스크린샷 캡처를 참고하세요.

스트리밍 및 실행 재개

Responses 실행은 기본적으로 스트리밍을 사용하지 않습니다. stream과 onEvent(Node) 또는 on_event(Python)를 사용하면 러너가 별도로 복사한 스트림 이벤트를 제공하고 응답이 완료된 뒤 동작을 실행합니다. eager를 사용하면 완료된 출력 항목을 순서대로 조기에 실행할 수 있습니다. 인수의 증분 데이터는 실행하지 않습니다.

러너가 전체 응답을 검증하기 전에도 완료된 항목을 안전하게 실행할 수 있을 때만 조기 실행을 활성화하세요. 이후 이벤트에서 해당 항목을 변경하거나 제거하면 러너는 중단되고 실행 기록은 유지됩니다. 이미 수행한 동작은 되돌릴 수 없습니다. 모든 동작이 전체 응답 검증을 통과할 때까지 기다려야 한다면 조기 실행을 끄거나 빈 조기 실행 정책을 사용하세요.

완료된 항목이 순서대로 도착하지 않거나 인덱스가 중간에 빠져 있으면 러너는 전체 응답이 도착한 뒤 해당 구간을 실행합니다. 스트림에 오류가 발생해도 이미 발생한 사이드 이펙트는 기록에 남습니다.

earlyExecution 또는 early_execution으로 조기 실행을 프로토콜에 지정된 일부 함수 이름으로 제한하고, 별도 불리언 값으로 네이티브 컴퓨터 호출 디스패처를 제어할 수 있습니다. 빈 객체를 지정하면 모든 로컬 도구 실행을 보류합니다. 옵션을 생략하면 기존처럼 조기 실행이 전반적으로 적용됩니다. 순서를 보존하기 위해 처음으로 보류된 도구 이후의 모든 도구도 보류됩니다. iterate()를 사용할 때는 다음으로 진행하기 전에 완료된 턴을 검사하세요. 이 경계에서 종료하면 보류된 도구는 실행되지 않습니다. 이 옵션은 실행 시점만 바꾸며 승인 방식은 그대로 유지됩니다.

완료된 개별 호출에 대해 beforeEarlyCall 또는 before_early_call이 호출 전달 전에 defer를 반환할 수 있습니다. 조기 실행 허용 목록에 없는 호출을 조기에 실행하도록 할 수는 없습니다. 다른 동작에 의존하지 않고 실행할 수 있는 일반 함수에만 independent: true를 지정하세요. 원장이 없으면 스트림 수신이 계속되는 동안 독립 함수를 실행할 수 있습니다. 영속 실행, 브라우저 동작, 컴퓨터 동작은 순서대로 처리됩니다. 다른 호출이 실패해도 이미 시작한 작업의 실행 기록은 유지됩니다.

기본적으로 독립적인 조기 호출은 최대 두 개까지 동시에 실행됩니다. 한도를 변경하려면 Node에서 maxConcurrentCalls, Python에서 max_concurrent_calls를 양의 정수로 설정하세요. 러너는 현재 그룹이 끝나야 스트림에서 다음 호출을 읽습니다. 이 옵션은 원장을 사용하지 않는 독립적인 조기 실행에만 적용됩니다. 각 함수가 자체적으로 시작하는 작업은 해당 함수가 직접 제한해야 합니다.

조기 실행이 중단되면 Node에서는 ResponsesToolRunnerError.attemptedCallIds와 completedCallIds를, Python에서는 attempted_call_ids와 completed_call_ids를 확인하세요. 여기에는 호출 ID만 있으며 결과, 인수, 드라이버 메시지는 없습니다. 사이드 이펙트가 이미 발생했을 수 있습니다. 시도한 동작이나 결과가 불확실한 동작을 재시도하기 전에 애플리케이션에서 실제 상태를 확인하세요.

영속 저장소 사용 여부와 관계없이 contextBudget 또는 context_budget으로 다음 요청의 입력 바이트 수와 이미지 수를 제한할 수 있습니다. 요청에 포함할 데이터를 추릴 때 현재 관찰 결과와 필수 도구 관계는 유지합니다. 메모리 내 한도만 설정하면 프로세스 종료 후 실행을 복구할 수 없습니다.

턴이 완료된 시점에 appendUserText 또는 append_user_text로 사용자의 지시를 대기열에 넣을 수 있습니다. 러너는 대기 중인 출력을 기록한 뒤 지시를 추가합니다. 이 메서드는 텍스트만 받으며 임의의 도구 출력이나 승인 객체를 받지 않습니다. 요청 한도도 초기화하지 않습니다.

에이전트에 다른 날짜를 확인하도록 요청하는 등 현재 작업을 구체화할 때 이 메서드를 사용하세요. 사용자가 작업을 교체하면 현재 실행을 중단하고 종료될 때까지 기다린 다음 새 실행을 시작하세요. 애플리케이션 상태를 다시 읽고 새 동작에 대한 승인을 새로 받으세요. 이전 실행 기록을 보존하세요. 지시를 변경해도 이미 발생한 사이드 이펙트는 되돌아가지 않습니다.

프로세스가 종료된 후에도 실행을 복구하려면 하나의 소유자가 실행을 독점 관리하면서 각 체크포인트를 저장하는 ledger를 제공하세요. 완료된 턴 경계에서만 재개하세요. 대기 중이거나 결과가 불확실한 동작은 먼저 실제 상태와 기록을 대조해야 합니다. 재개 후에도 남은 요청 한도와 완료 이력이 유지됩니다. 로컬 컨텍스트 예산에 따른 컨텍스트 압축은 전체 근거 자료를 원장에 보관하고 현재 관찰 결과, 안전 점검, 메시지, 추론을 고정해 유지합니다. 컨텍스트 압축으로 승인이 부여되지는 않습니다.

로컬 사이드 이펙트 발생 전후를 포함해 저장할 때마다 완전한 체크포인트의 별도 사본이 전달됩니다. 체크포인트에는 배치 전체와 누적 이력이 들어 있습니다. 배치가 크면 이 기록을 복사하고 저장하는 총 작업량이 배치 크기의 제곱에 비례해 늘어날 수 있습니다. 이 규모에 맞는 저장소를 선택하세요. contextBudget과 context_budget은 요청 입력을 제한하며 원장 저장 용량은 제한하지 않습니다.

실행이 중단되었을 때 대기 상태의 체크포인트에는 마지막 저장 시점까지의 기록이 들어 있습니다. 이후 텍스트나 아직 시도하지 않은 제안이 빠져 있을 수 있으며, 이 체크포인트가 재실행을 허가하는 일은 없습니다. 사이드 이펙트 발생 전후에 저장한 체크포인트에는 해당 시점까지 관찰한 전체 내용과 실행 기록이 포함됩니다.

MCP 도구가 포함된 실행은 각 요청 전에 대기 상태의 체크포인트를 저장합니다. 연결이 끊기면 다른 실행을 시작하기 전에 MCP 서버에서 실제로 어떤 작업이 수행되었는지 확인하세요. 대기 상태의 체크포인트에서는 자동으로 재개할 수 없습니다.

저장된 MCP 선언에서는 인증 정보와 사용자 지정 헤더를 생략하고 서버 URL을 SHA-256 지문으로 대체합니다. 네이티브 요청은 원래 URL을 계속 사용합니다. 주기적으로 교체해야 하는 자격 증명은 인증 정보나 헤더에 넣으세요. URL 경로나 인식되지 않는 쿼리 값을 변경하면 서버 식별값이 달라지므로 새 실행이 필요합니다. 원본 MCP URL이 들어 있는 체크포인트에서는 재개할 수 없습니다. Node에서 MCP URL을 저장하려면 crypto.subtle.digest가 필요합니다. 그 밖의 체크포인트 입력 및 출력도 애플리케이션의 비공개 데이터입니다.

재개할 때는 현재 유효한 자격 증명을 제공하고 의도한 서버와 계정에 연결되는지 확인하세요.

저장된 코드 인터프리터 선언에는 자격 증명 이름과 도메인이 유지되지만 비밀 값은 지워집니다. 재개할 때 도구 설정에 현재 값을 제공하세요. MCP 승인에서 빈 always: {} 또는 never: {} 필터는 모든 도구에 적용됩니다.

초기 입력이나 저장된 원장에 승인된 MCP 요청이 있으면 Node에서는 approveMcp, Python에서는 approve_mcp를 제공하세요. 러너는 처음 저장하거나 API 요청을 보내기 전에, 일치하는 완료된 MCP 호출이 없는 승인 건마다 다시 승인을 요청합니다. 원장이나 컨텍스트 예산 사용 여부와 관계없이 적용됩니다. 완료된 호출과 이전 거부는 그대로 유지됩니다. 새 승인이 필요한데 콜백이 없으면 실행이 중단됩니다.

커스텀 드라이버 로컬 점검

먼저 예약 데모 또는 격리된 데스크톱 예제의 로컬 실습을 실행한 다음 환경에 맞게 수정하세요. 드라이버에서 실제 페이지 상태, 입력이 미친 영향, 리소스 정리를 확인하는 검사를 추가하세요. SDK 검증만으로 환경이 동작을 올바르게 수행했다고 판단할 수는 없습니다.

실제로 동작하는 SDK 워크플로우는 첫 작업 실행을, 환경 설정은 통합 구성 예시를 참고하세요. 변경 후에는 성공을 보고하기 전에 저장된 양식, 파일 또는 다른 애플리케이션 기록을 확인하세요.