OpenAI Agents API와 Computer use 사용법 승인과 복구 가이드
브라우저를 조작하는 AI를 제품에 넣을 때 중요한 것은 클릭 능력만이 아니다. 어떤 환경에서 실행하는지, 언제 사용자 결정을 받아야 하는지, 연결이 끊겼을 때 같은 작업을 어떻게 이어갈지가 함께 설계되어야 한다. Agents API와 Computer use는 이 실행 흐름을 이해하기 좋은 주제다.
이 글은 2026년 9월 30일 확인한 공식 개발 문서를 기준으로 구조와 도입 순서를 설명한다. 실제 서비스에 적용한 성능 시험이나 완성된 운영 코드를 제시하는 글은 아니다. 아래 업무 예시는 이해를 돕기 위해 만든 제안이며, 공개 전에는 계정의 사용 가능 범위와 최신 문서를 다시 확인해야 한다.
Agents API가 담당하는 실행 구조
Agents API는 Codex의 실행 체계를 관리형 서비스로 제공한다. 애플리케이션이 모델에 질문을 보내는 데서 끝나는 대신, 작업을 이어갈 세션과 실행 흐름을 관리할 수 있다. 문맥 정리와 작업 복구 같은 실행 기반을 OpenAI가 담당하고, 개발자는 업무 도구와 환경을 구성한다.
구조는 세 부분으로 생각하면 쉽다. Agent는 모델과 지시 및 도구 설정이고, Environment는 파일과 명령을 다룰 실행 공간이며, Session은 특정 작업의 상태를 이어가는 단위다. 이벤트는 입력과 진행 및 결과를 애플리케이션에 연결한다.
예를 들어 공개 도움말 3개를 비교하는 기능이라면, 사용자가 요청한 비교 기준과 허용된 사이트를 작업에 전달하고 결과를 받는 화면을 만든다. 이 예시는 도입 구상이지 문서가 자동으로 모든 사이트의 이용 허락을 부여한다는 뜻은 아니다.
Computer use와 내 컴퓨터 접근을 구분하기
여기서 Computer use는 OpenAI가 호스팅하는 브라우저에서 웹 화면을 다루는 기능이다. 사용자의 개인 브라우저를 그대로 원격 조종하거나 로컬 파일 전체에 접근하는 기능으로 설명하면 안 된다.
개발 설정에는 computer_use 도구와 openai_hosted 환경, desktop 활성화가 등장한다. 브라우저에 필요한 네트워크 범위를 구성해야 하며, 세션을 만들었다는 사실만으로 업무가 시작되었다고 판단하지 않는다. 별도로 입력을 보내고 진행 이벤트를 확인한다.
공개 사이트의 탐색, 웹 화면의 동작 점검, 허용된 계정에서의 정보 확인처럼 화면 상호작용이 필요한 업무를 검토할 수 있다. 같은 자료를 안정적인 API로 받을 수 있다면 더 좁은 권한의 전용 도구가 적합한지도 비교하는 편이 좋다.
처음에는 읽기 전용 업무로 시작하기
도입 예시로는 지정한 도움말 페이지에서 제목과 갱신일을 읽고 출처 주소를 정리하는 작업을 제안한다. 로그인, 게시, 결제, 데이터 변경을 제외하고 결과와 근거를 사람이 확인하도록 범위를 정한다.
이때 시험 항목은 3개면 충분하다. 대상 사이트만 방문했는지, 페이지의 내용과 결과가 일치하는지, 승인 대기나 오류가 발생했을 때 사용자가 상황을 이해할 수 있는지다. 클릭 성공률 하나만으로 운영 준비를 판단하지 않는다.
실제 변경 작업을 추가하기 전에는 읽기 전용 테스트 계정이나 별도 시험 환경으로 위험 범위를 제한한다. 요청 문장에 금지사항을 적는 것과 실행 환경에서 변경을 막는 것은 강도가 다르므로 각각 점검해야 한다.
사이트 접근 승인과 행동 승인은 다르다
브라우저는 새로운 사이트 origin에 접근할 때 사용자 승인을 요구한다. 공개 사이트도 대상이며, 네트워크를 허용했다고 이 승인까지 자동으로 끝나는 것은 아니다. 애플리케이션은 목적지와 요청 이유를 보여 주고 사용자가 허용하거나 거절할 수 있게 해야 한다.
특히 사이트 접근 승인만으로 결제나 삭제 같은 개별 행동의 확인이 보장되지는 않는다. 승인받은 사이트에서 위험한 조작을 할 수 있다면, 접근 승인을 전체 작업의 포괄적인 허가처럼 취급해서는 안 된다.
확인을 반드시 보장해야 하는 서비스는 해당 행동이 불가능한 자료와 계정으로 브라우저를 제한하거나, 개발자가 제어하는 실행 환경과 승인 장치를 사용해야 한다. 모델이 승인 도구를 호출하도록 지시하는 것만으로 서버가 강제하는 승인 절차와 같다고 주장할 수 없다.
웹페이지에 적힌 지시는 신뢰할 수 없는 외부 입력으로 다룬다. 페이지가 추가 권한을 요구하거나 사용자의 원래 지시를 바꾸려 해도, 그 내용이 사용자 승인을 대신하지 않는다.
로그인 요청을 별도 화면으로 처리하기
로그인이 필요한 경우에는 일반 대화에 비밀번호를 적게 하지 말고, 요청된 목적지와 입력 항목을 확인하는 별도 인증 화면을 구성한다. 어떤 계정으로 어디에 인증하는지 사용자가 확인할 수 있어야 하며, 목적지가 불명확하면 진행하지 않는다.
현재 흐름은 이메일과 비밀번호 및 인증 코드를 지원하지만 패스키나 QR 로그인은 지원하지 않는다. 인증 요청은 주 에이전트가 담당하며 하위 에이전트가 직접 요청할 수 없다. 따라서 어떤 웹서비스든 로그인할 수 있다고 설명해서는 안 된다.
로그인을 취소하는 것과 실행 중인 작업을 중지하는 것은 별개다. 사용자가 인증을 거절했을 때 작업 전체도 끝낼지, 공개 자료만 계속 읽을지에 대한 화면과 동작을 구분해 설계한다.
연결이 끊겨도 새 작업부터 만들지 않기
애플리케이션은 세션 ID와 대기 중인 요청 ID를 보관해야 한다. 연결이 끊기거나 응답을 받지 못했다고 새로운 세션에서 같은 일을 다시 시작하면, 이미 실행된 조작을 중복할 수 있다.
먼저 기존 세션 상태와 현재 필요한 사용자 행동을 조회한다. 특히 로그인 응답이 접수되었는지 불분명하면 성공이나 실패를 추정하지 말고 상태를 확인한다. 인증 요청은 5분 후 만료될 수 있으므로 오래된 입력 화면을 그대로 복구하지 않는다.
개별 브라우저 도구의 완료는 전체 작업의 완료와도 다르다. 주 에이전트의 실행이 끝났는지와 최종 결과를 확인한 뒤 사용자에게 완료를 표시한다. 네트워크 오류 처리와 결과 검증은 별도 시험 항목으로 남겨야 한다.
화면 기록과 비용을 함께 관리하기
애플리케이션에서 진행 화면을 보여 주려면 도구의 include_screenshots 설정을 검토한다. API 출력에는 기본적으로 스크린샷이 빠지지만, 에이전트의 화면 관찰까지 없어지는 것은 아니다. 화면에는 계정과 고객 자료가 들어갈 수 있으므로 기록 보관과 열람 권한을 제한한다.
비용도 모델 토큰만으로 계산하지 않는다. 모델 사용료, 제공되는 도구 비용, OpenAI 호스팅 실행 환경의 비용을 해당 API 가격표에서 각각 확인한다. ChatGPT 개인 구독을 이 API의 정액 이용권으로 간주하지 않는다.
작업이 끝나면 필요한 결과를 회수하고 세션 삭제를 통해 환경 정리를 요청한다. 세션을 지우는 것은 이미 외부 사이트에서 수행한 변경을 취소하는 기능이 아니므로, 삭제 전에 결과와 상태를 검토해야 한다.
운영 도입의 기준 세우기
도입 판단은 클릭을 잘했는지가 아니라 허용 범위를 지켰는지, 승인 요청이 제대로 보였는지, 오류 뒤에 중복 실행 없이 복구했는지로 내려야 한다. 처음에는 공개 자료의 읽기부터 시험하고, 위험한 행동은 별도 통제 근거를 갖춘 뒤 추가한다.
Agents API는 지속 작업을 연결할 실행 기반이고 Computer use는 그 안에서 브라우저 화면을 다룰 수 있는 도구다. 이 구분을 유지하면 사용자 화면, 승인 장치, 기록 보관, 비용 관리의 책임을 더 구체적으로 설계할 수 있다.
출처와 편집 안내
이 글은 OpenAI와 제휴하지 않은 독립적인 기능 해설이다. 제품명은 해당 권리자의 상표이며 식별 목적으로 사용했다. 그림은 설명용 일러스트와 개념도이며 실제 제품 화면이나 OpenAI 공식 이미지가 아니다.
출처: OpenAI Developers — Agents API overview · Computer use · Environment configuration · API pricing
