모델에서 에이전트까지: 응답 API에 컴퓨터 환경 제공

현재 특정 작업에 탁월한 모델을 사용하는 방식에서 복잡한 워크플로를 처리할 수 있는 에이전트를 사용하는 방식으로 전환하는 중입니다. 모델을 프롬프트하면 학습된 인텔리전스에만 액세스할 수 있습니다. 하지만 모델에 컴퓨터 환경을 제공하면 서비스 실행, API에서 데이터 요청 또는 스프레드시트나 보고서와 같은 더 유용한 아티팩트 생성 등 훨씬 더 다양한 사용 사례를 구현할 수 있습니다.

에이전트를 구축하려고 시도할 때 중간 파일을 어디에 넣을지, 프롬프트에 큰 표를 붙여넣지 않는 방법, 보안 문제를 일으키지 않고 워크플로 네트워크에 액세스 권한을 부여하는 방법, 워크플로 시스템을 직접 구축하지 않고 시간 초과 및 재시도를 처리하는 방법 등 몇 가지 실질적인 문제가 생깁니다.

개발자가 직접 실행 환경을 구축하지 않아도 되도록, 응답 API⁠(새 창에서 열기)가 실제 작업을 안정적으로 실행할 수 있는 컴퓨터 환경을 갖추는 데 필요한 구성 요소를 구축했습니다.

셸 도구와 호스팅된 컨테이너 워크스페이스와 함께 OpenAI의 응답 API는 이러한 실질적인 문제를 해결하도록 설계되었습니다. 이 모델은 단계와 명령을 제안하며, 플랫폼은 입력 및 출력을 위한 파일 시스템, 선택 항목인 구조화된 스토리지(예: SQLite), 제한된 네트워크 액세스를 갖춘 격리된 환경에서 이를 실행합니다. 

이 게시물에서는 에이전트를 위한 컴퓨터 환경 구축 방법 방법을 자세히 살펴보고, 더 빠르고 반복 가능하며 안전한 프로덕션 워크플로를 위해 이를 활용하는 방법에 대한 몇 가지 기본적인 내용을 공유해 드립니다.

좋은 에이전트 워크플로는 긴밀한 실행 루프에서 시작됩니다. 모델이 파일 읽기나 API를 통한 데이터 가져오기 등의 작업을 제안하고 플랫폼이 이를 실행하며 그 결과가 다음 단계로 전달되는 방식입니다. 먼저 이 루프가 실제로 작동하는 모습을 확인하는 가장 간단한 방법인 셸 도구를 살펴본 다음 컨테이너 워크스페이스, 네트워킹, 재사용 가능한 스킬, 컨텍스트 컴팩션을 다루겠습니다.

셸 도구를 이해하려면 먼저 언어 모델이 일반적으로 함수를 호출하거나 컴퓨터와 상호작용하는 등의 작업을 수행하기 위해 툴을 사용하는 방식을 이해하는 것이 유용합니다. 모델 학습 중에는 도구 사용 방법과 그에 따른 효과를 단계별로 보여주는 예시가 제공됩니다. 이를 통해 모델은 도구를 사용할 시기와 사용 방법을 결정하는 방법을 배울 수 있습니다. “도구를 사용”한다는 것은 모델이 실제로는 도구 호출만 제안한다는 의미입니다. 모델이 호출을 직접 실행할 수는 없습니다.

셸 도구는 명령줄을 통해 컴퓨터와 상호작용하여 컴퓨터에서 텍스트 검색부터 API 요청 전송까지 다양한 작업을 수행할 수 있도록 모델을 훨씬 더 강력하게 만들어 줍니다. 익숙한 Unix 도구를 기반으로 구축된 당사의 셸 도구는 grep, curl, awk와 같은 유틸리티를 바로 사용할 수 있어 사용자가 기대하는 모든 작업을 수행할 수 있습니다.

Python만 실행하는 기존의 코드 인터프리터에 비해 셸 도구는 Go 또는 Java 프로그램을 실행하거나 NodeJS 서버를 시작하는 등 훨씬 더 다양한 사용 사례를 지원합니다. 이러한 유연성 덕분에 모델은 복잡한 에이전트 작업을 수행할 수 있습니다.

모델은 자체적으로 셸 명령만 제안할 수 있는데 그렇다면 이러한 명령은 어떻게 실행될까요? 작업이 완료될 때까지 모델 출력을 가져오고, 도구를 호출하고, 도구 응답을 다시 모델에 반복적으로 전달하려면 오케스트레이터가 필요합니다.

응답 API는 개발자가 OpenAI 모델과 상호작용하는 방식입니다. 사용자 지정 도구와 함께 사용할 경우 응답 API는 클라이언트에 제어권을 돌려주며, 클라이언트는 도구를 실행하기 위해 자체 하네스가 필요합니다. 하지만 이 API는 모델과 호스팅된 도구 간에 즉시 오케스트레이션할 수도 있습니다. 

응답 API는 프롬프트를 수신하면 사용자 프롬프트, 이전 대화 상태, 도구 지침 등 모델 컨텍스트를 어셈블합니다. 셸 실행이 작동하려면 프롬프트에 셸 도구 사용이 언급되어야 하며 선택한 모델이 셸 명령을 제안하도록 학습되어 있어야 합니다. GPT‑5.2 이상 모델은 이에 대해 학습되어 있습니다. 이 모든 컨텍스트를 바탕으로 모델은 다음 작업을 결정합니다. 셸 실행을 선택하면 하나 이상의 셸 명령을 응답 API 서비스에 반환합니다. API 서비스는 이러한 명령을 컨테이너 런타임에 전달하고 셸 출력을 다시 스트리밍하여 다음 요청의 컨텍스트에서 모델에 제공합니다. 그런 다음 모델은 결과를 검사하고 후속 명령을 지시하거나 최종 답변을 생성할 수 있습니다. 응답 API는 모델이 추가적인 셸 명령 없이 완료를 반환할 때까지 이 루프를 반복합니다.

응답 API가 셸 명령을 실행하면 컨테이너 서비스와 스트리밍 연결을 유지합니다. 출력이 생성되면 API는 거의 실시간으로 이를 모델에 전달하여 모델이 추가 출력을 기다릴지, 다른 명령을 실행할지, 아니면 최종 응답으로 넘어갈지 결정할 수 있도록 합니다.

모델은 한 번에 여러 개의 셸 명령을 제안할 수 있으며, 응답 API는 별도의 컨테이너 세션을 사용하여 동시에 이를 실행할 수 있습니다. 각 세션은 독립적으로 출력을 스트리밍하고, API는 이러한 스트림을 구조화된 도구 출력에 멀티플렉싱하여 컨텍스트로 제공합니다. 즉, 에이전트 루프는 파일 검색, 데이터 가져오기, 중간 결과 유효성 검사 등의 작업을 병렬화할 수 있습니다.

명령에 파일 작업이나 데이터 처리가 포함되면 셸 출력이 매우 커져 유용한 신호를 추가하지 않으면서도 컨텍스트 예산을 소모할 수 있습니다. 이를 제어하기 위해 모델은 명령당 출력 한도를 지정합니다. 응답 API는 이 한도를 적용하여 출력의 시작과 끝을 모두 유지하면서 생략된 콘텐츠를 표시하는 제한된 결과를 반환합니다. 예를 들어, 시작과 끝은 유지하면서 출력을 1,000자로 제한할 수 있습니다.

시작 부분의 텍스트 ... 1,000자에서 잘림 ... 끝 부분의 텍스트

동시 실행과 제한된 출력을 함께 사용하면 에이전트 루프를 빠르고 컨텍스트 효율적으로 만들어 모델이 원시 터미널 로그에 압도당하지 않고 관련 결과를 계속 추론할 수 있습니다.

에이전트 루프의 잠재적인 문제 중 하나는 작업이 장시간 실행될 수 있다는 점입니다. 장시간 실행되는 작업은 컨텍스트 윈도우의 공간을 소모하며 이는 여러 턴과 여러 에이전트에 걸쳐 컨텍스트를 제공하는 데 중요합니다. 에이전트가 스킬을 호출하고 응답을 받은 뒤 도구 호출과 추론 요약을 추가하는 상황을 상상해 보세요. 그러면 제한된 컨텍스트 윈도우는 금세 가득 찹니다. 에이전트가 계속 실행되는 동안 중요한 컨텍스트를 잃지 않으려면 핵심 세부 정보를 유지하고 불필요한 것은 제거할 수 있는 방법이 필요합니다. 개발자가 사용자 지정 요약 또는 상태 전달 시스템을 설계하고 유지 관리할 필요가 없도록 하기 위해, 모델의 동작 방식과 학습 방식에 맞게 설계된 기본 컴팩션 기능을 응답 API에 추가했습니다.

최신 모델은 이전 대화 상태를 분석하여 주요 상태를 보존하는 암호화된 토큰 효율적 형식의 컴팩션 항목을 생성하도록 훈련되었습니다. 컴팩션 후에, 다음 컨텍스트 윈도우는 이 컴팩션 항목과 이전 윈도우의 중요도가 높은 부분으로 구성됩니다. 이를 통해 확장된 다단계 및 도구 중심 세션에서도 윈도우 경계를 넘어 워크플로의 일관성을 계속 유지할 수 있습니다. Codex는 이 메커니즘을 활용하여 품질 저하 없이 장시간 실행되는 코딩 작업과 반복적인 도구 실행을 지속할 수 있습니다.

컴팩션 기능은 서버에 기본 제공되거나 독립형 `/compact` 엔드포인트를 통해 사용할 수 있습니다. 서버 측 컴팩션을 사용하면 임계값을 구성할 수 있으며, 시스템이 컴팩션 타이밍을 자동으로 처리하므로 복잡한 클라이언트 측 로직이 필요하지 않습니다. 컴팩션 직전의 소폭 초과를 허용하기 위해 유효한 입력 컨텍스트 윈도우를 약간 더 크게 제공하므로 한도에 근접한 요청도 거부되지 않고 계속 처리된 뒤 컴팩션될 수 있습니다. 모델 학습이 발전함에 따라 기본 컴팩션 솔루션도 OpenAI 모델이 출시될 때마다 함께 발전합니다.

Codex는 컴팩션 시스템의 초기 사용자 역할을 하여, OpenAI가 컴팩션 시스템을 구축하는 데 도움을 주었습니다. Codex 인스턴스 중 하나에서 컴팩션 오류가 발생하면 두 번째 인스턴스를 가동하여 조사합니다. 그 결과 Codex는 문제를 해결하는 과정을 통해 효율적인 기본 컴팩션 시스템을 갖추게 되었습니다. Codex가 스스로 점검하고 개선할 수 있는 이러한 능력은 OpenAI와 함께 작업하면서 특히 흥미로운 부분이 되었습니다. 대부분의 도구는 사용자가 사용법을 익히기만 하면 되지만 Codex는 OpenAI와 함께 학습합니다.

이제 상태와 리소스를 살펴보겠습니다. 컨테이너는 단순히 명령을 실행하는 장소일 뿐만 아니라 모델의 작업 환경이기도 합니다. 컨테이너 내부에서 모델은 네트워크 정책 제어에 따라 파일을 읽고, 데이터베이스를 쿼리하며, 외부 시스템에 액세스할 수 있습니다.

컨테이너 컨텍스트의 첫 번째 부분은 리소스를 업로드하고, 정리하며, 관리하기 위한 파일 시스템입니다. 우리는 컨테이너 및 파일⁠(새 창에서 열기) API를 구축하여 모델에 사용 가능한 데이터의 지도를 제공하고, 광범위하고 불필요한 스캔을 수행하는 대신 대상 파일 작업을 선택하도록 도왔습니다.

일반적인 안티패턴 중 하나는 모든 입력을 프롬프트 컨텍스트에 직접 넣는 것입니다. 입력이 늘어날수록 프롬프트가 과도하게 채워지면 비용이 많이 들고 모델이 처리하기도 어려워집니다. 더 나은 패턴은 리소스를 컨테이너 파일 시스템에 스테이징하고, 모델이 셸 명령으로 무엇을 열고, 파싱하고, 변환할지 결정하도록 하는 것입니다. 인간과 마찬가지로, 모델은 정리된 정보가 있을 때 더 잘 작동합니다.

컨테이너 컨텍스트의 두 번째 부분은 데이터베이스입니다. 대부분의 경우, 개발자는 구조화된 데이터를 SQLite로 데이터베이스에 저장하고 이를 쿼리하는 것이 좋습니다. 예를 들어, 전체 스프레드시트를 프롬프트에 복사하는 대신 모델에 표에 대한 설명(존재하는 열 및 각 열의 의미)을 제공하여 필요한 행을 가져오도록 할 수 있습니다.

예를 들어, “이번 분기에 매출이 감소한 제품은 무엇인가요?”라고 질문하면 모델은 전체 스프레드시트를 스캔하는 대신 관련 행만 쿼리할 수 있습니다. 더 크고, 빠르고, 저렴한 데이터세트로 쉽게 확장할 수 있습니다.

컨테이너 컨텍스트의 세 번째 부분은 네트워크 액세스이며, 이는 에이전트 워크로드의 필수 요소입니다. 에이전트 워크플로는 실시간 데이터를 가져오거나, 외부 API를 호출하거나, 패키지를 설치해야 할 수 있습니다. 이때, 컨테이너에 무제한 인터넷 액세스 권한을 허용하는 것은 위험할 수 있습니다. 외부 웹사이트에 정보가 노출되거나, 민감한 내부 시스템이나 서드파티 시스템에 의도치 않게 접속하게 되거나, 자격 증명 유출 및 데이터 유출을 방지하기가 더 어려워질 수 있기 때문입니다.

이러한 우려를 해소하면서도 에이전트의 유용성을 제한하지 않기 위해, 사이드카 이그레스 프록시를 사용하도록 호스팅된 컨테이너를 구축했습니다. 모든 아웃바운드 네트워크 요청은 중앙화된 정책 계층을 통과하며, 이 계층은 허용 목록과 액세스 제어를 시행하는 동시에 트래픽의 관측 가능성을 유지합니다. 자격 증명의 경우, 외부 전송 시 도메인 범위의 시크릿 인젝션을 사용합니다. 모델과 컨테이너에는 플레이스홀더만 표시되며, 원시 시크릿 값은 모델에 표시되는 컨텍스트 외부에 유지되고 승인된 대상에 대해서만 적용됩니다. 이렇게 하면 유출 위험을 줄이면서도 여전히 인증된 외부 호출을 수행할 수 있습니다.

셸 명령은 강력하지만 많은 작업이 동일한 여러 단계의 패턴을 반복합니다. 에이전트는 실행할 때마다 다시 계획하고, 명령을 다시 지시하고, 규칙을 다시 학습하는 등 워크플로를 다시 파악해야 하므로 일관성 없는 결과와 실행 낭비를 초래할 수 있습니다. 에이전트 스킬⁠(새 창에서 열기)은 이러한 패턴을 재사용 가능하고 구성 가능한 빌딩 블록으로 패키징합니다. 구체적으로, 스킬은 ‘SKILL.md⁠(새 창에서 열기)’(메타데이터와 지침 포함)과 API 사양 및 UI 자산과 같은 지원 리소스를 포함하는 폴더 번들입니다.

이 구조는 앞서 설명한 런타임 아키텍처에 자연스럽게 부합합니다. 컨테이너는 영구 유지 파일과 실행 컨텍스트를 제공하며 셸 도구는 실행 인터페이스를 제공합니다. 이 두 가지가 모두 갖춰지면 모델은 필요할 때 `ls`, `cat` 등의 셸 명령을 사용해 스킬 파일을 찾아내고, 지침을 해석하며, 스킬 스크립트를 모두 동일한 에이전트 루프 내에서 실행할 수 있습니다.

OpenAI 플랫폼에서 스킬을 관리할 수 있는 API⁠(새 창에서 열기)를 제공해 드립니다. 개발자는 스킬 폴더를 버전 지정된 번들로 업로드하고 저장하여 나중에 스킬 ID별로 검색할 수 있습니다. 프롬프트를 모델에 전송하기 전에 Responses API는 스킬을 로드하고 이를 모델 컨텍스트에 포함합니다. 이 시퀀스는 결정론적입니다.

1. 이름과 설명을 포함한 스킬 메타데이터를 가져옵니다.
2. 스킬 번들을 가져와 컨테이너에 복사한 다음 압축을 풉니다.
3. 스킬 메타데이터 및 컨테이너 경로로 모델 컨텍스트를 업데이트합니다.

스킬이 관련이 있는지 판단할 때 모델은 순차적으로 지침을 탐색하고 컨테이너에서 셸 명령을 통해 스크립트를 실행합니다.

모든 요소를 종합하면 응답 API는 오케스트레이션을 제공하고, 셸 도구 는 실행 가능한 작업을 제공하며, 호스팅된 컨테이너는 지속적인 런타임 컨텍스트를 제공하고, 스킬은 재사용 가능한 워크플로 로직을 계층화하며, 컴팩션은 에이전트가 필요한 컨텍스트를 유지한 채 오랫동안 실행될 수 있도록 합니다.

이러한 기본 구성 요소를 사용하면 단일 프롬프트가 엔드투엔드 워크플로로 확장될 수 있습니다. 즉, 적절한 스킬을 찾고, 데이터를 가져오고, 이를 로컬에서 구조화된 상태로 변환하고, 이를 효율적으로 쿼리하며, 오래 지속되는 아티팩트를 생성할 수 있습니다. 

아래 다이어그램은 이 시스템이 실시간 데이터를 사용하여 스프레드시트를 생성하는 방식을 보여줍니다.

셸 도구와 컴퓨터 환경을 결합해 엔드투엔드 워크플로를 구현하는 자세한 예시는 스킬을 패키징하여 응답 API를 통해 실행하는 방법을 단계별로 설명하는 개발자 블로그 게시물⁠(새 창에서 열기)과 쿡북⁠(새 창에서 열기)을 참조하세요.

앞으로 개발자 여러분이 이러한 일련의 기본 구성 요소를 사용하여 보여 주실 멋진 성과를 기대합니다. 언어 모델은 텍스트, 이미지, 오디오 생성 이상의 기능을 수행합니다. 당사는 복잡한 실제 작업을 대규모로 처리할 수 있도록 플랫폼을 지속적으로 발전시켜 나갈 것입니다.