OpenAI는 에이전트 하네스를 운영합니다. 애플리케이션은 하네스에 작업을 보내고 결과를 받습니다. 에이전트에 컴퓨팅 리소스나 파일이 필요하면 환경을 추가하세요.
구성 요소
- 하네스: OpenAI가 호스팅하는 Codex 인스턴스입니다. 모델 호출과 도구 실행을 반복하며 에이전트의 세션을 유지합니다.
- 환경: 에이전트가 명령어와 코드를 실행하고 파일을 다루는 곳입니다. 원격 샌드박스, 노트북, Docker 컨테이너 또는 AWS Lambda 함수를 환경으로 사용할 수 있습니다.
- 애플리케이션 서버: 에이전트를 제품에 연결하는 코드입니다. 작업을 제출하고 이벤트를 수신하며 함수 도구 호출을 처리합니다. 환경을 직접 제공하는 경우에는 이 코드가 환경의 수명 주기도 관리합니다.
작업에 필요한 구성 요소부터 선택하세요. 하네스는 환경 없이도 동작하며, 애플리케이션은 스트리밍이나 웹훅으로 진행 상황을 받아볼 수 있습니다.
환경 없이 시작하기
질문에 답하거나 도구로 외부 서비스에 접근하는 에이전트에는 별도의 컴퓨팅 리소스나 파일이 필요하지 않을 수 있습니다. environment.type을 none으로 설정하세요. 다음 예시는 환경 설정 부분입니다. 세션을 생성하려면 에이전트와 초기 입력도 필요합니다.
{
"environment": {
"type": "none"
}
}애플리케이션이 세션에 입력을 보내면 하네스가 모델을 호출하고 설정된 도구를 사용해 결과를 반환합니다. OpenAI는 이후 작업에서도 같은 세션을 사용할 수 있도록 세션을 유지합니다.
하네스는 원격 MCP 도구를 직접 호출할 수 있습니다. 함수 도구를 사용할 때는 애플리케이션 코드가 각 호출을 받아 함수를 실행하고 결과를 반환합니다.
환경이 없으면 기본 제공 Bash 및 apply-patch 도구, 워크스페이스 파일, 실행기 MCP를 사용할 수 없습니다.
그림에 표시된 가상 런타임은 선택 사항이며, 애플리케이션의 함수 도구를 통해 파일과 셸 명령어를 제공합니다.
OpenAI 호스팅 환경 추가하기
에이전트가 스크립트를 실행하거나 파일을 편집하거나 아티팩트를 생성해야 한다면 environment.type을 openai_hosted로 설정하세요. OpenAI가 해당 세션의 샌드박스를 생성하고 관리합니다.
에이전트에 필요한 패키지, 파일, 네트워크 접근 권한을 설정하세요. 하네스는 샌드박스에서 직접 명령어를 실행합니다. 애플리케이션은 계속해서 작업을 보내고 이벤트를 수신하며 함수 도구 호출을 처리합니다.
점선 화살표는 아래 설명처럼 환경을 직접 관리할 때만 해당합니다.
설정 옵션은 OpenAI 호스팅 환경을 참고하세요.
자체 환경 연결하기
에이전트에 자체 인프라, 사설 네트워크 또는 맞춤형 소프트웨어가 필요하면 environment.type: "self_hosted"를 사용하세요.
애플리케이션 코드가 환경을 시작하고 실행기를 세션에 연결합니다. 실행기는 하네스가 요청한 명령어와 도구를 실행합니다. 애플리케이션은 각 명령어를 일일이 전달할 필요 없이 연결과 환경의 수명 주기를 관리합니다.
리소스 프로비저닝, 재연결, 종료, 필요한 파일 보존은 직접 담당합니다. 애플리케이션 서버나 웹훅 핸들러에서 이 작업을 관리할 수 있습니다.
컴퓨팅 리소스를 중지하기 전에 새로 들어오는 작업의 처리를 조율하고 실행 대기 중인 작업이 없는지 확인하세요.
설정 및 종료 요건은 샌드박스 연결과 샌드박스 수명 주기를 참고하세요.
진행 상황과 결과 받기
어떤 환경 구성을 선택하든 다음 두 방식 중 하나를 사용하거나 둘을 함께 사용할 수 있습니다.
- 스트리밍: 에이전트가 작업하는 동안 제품에 표시할 출력 등 세부 이벤트를 받습니다.
- 웹훅: 스트림을 열어 두지 않아도 세션 상태 변경을 수신합니다. 웹훅 핸들러는 결과를 가져오거나 함수 도구를 실행하거나 자체 호스팅 환경을 관리할 수 있습니다.
함수 도구에는 호출을 받아 결과를 반환하는 핸들러가 필요합니다. 핸들러를 사용할 수 없으면 에이전트가 결과를 계속 기다릴 수 있습니다. 이벤트 핸들러나 수명 주기 핸들러에 장애가 발생하면 진행 상황 업데이트나 환경 관리가 중단될 수도 있습니다.