아키텍처

아키텍처 (Architecture)

OpenAI가 에이전트 harness를 실행하고, 애플리케이션은 작업을 보내고 결과를 받아요. 에이전트가 컴퓨팅이나 파일이 필요할 때는 환경(environment)을 추가할 수 있어요. Agents API의 아키텍처 구성 요소와 환경 선택을 다루는 가이드예요.

출처: 문서

OpenAI가 에이전트 harness를 실행해요. 여러분의 애플리케이션은 작업을 보내고 결과를 받아요. 에이전트가 컴퓨팅이나 파일이 필요할 때는 환경을 추가하세요.

Harness: 모델과 도구 루프를 실행하고 에이전트의 세션을 유지하는 OpenAI 호스팅 Codex 인스턴스.
Environment(환경): 에이전트가 명령을 실행하고 코드를 실행하며 파일을 다루는 곳. 환경은 원격 샌드박스, 여러분의 노트북, Docker 컨테이너, 또는 AWS Lambda 함수일 수 있어요.
Application server(애플리케이션 서버): 에이전트를 제품에 연결하는 여러분의 코드. 작업을 제출하고, 이벤트를 받고, 함수 도구를 처리해요. 환경을 제공할 때 여러분의 코드가 그 수명 주기도 관리해요.

작업에 필요한 구성 요소부터 시작하세요. harness는 환경 없이도 작동할 수 있고, 애플리케이션은 스트리밍이나 웹훅을 통해 진행 상황을 받을 수 있어요.

질문에 답하거나 외부 서비스에 접근하기 위해 도구를 사용하는 에이전트는 자체 컴퓨팅이나 파일이 필요 없을 수 있어요. environment.type을 none으로 설정하세요. 이 조각은 환경 설정을 보여줘요. 세션 생성에는 에이전트와 초기 입력도 필요해요:

{
  "environment": {
    "type": "none"
  }
}

애플리케이션은 세션에 입력을 보내요. harness는 모델을 호출하고 설정된 도구를 사용하며 결과를 반환해요. OpenAI는 나중에 작업하기 위해 세션을 유지해요.

harness는 원격 MCP 도구를 직접 호출할 수 있어요. function tools의 경우 여러분의 코드가 각 호출을 받아 함수를 실행하고 결과를 반환해요.

환경이 없으면 내장 Bash 및 apply-patch 도구, 워크스페이스 파일, executor MCP는 사용할 수 없어요.

여기 보이는 선택적 가상 런타임은 애플리케이션의 함수 도구를 통해 파일과 셸 명령을 제공해요.

에이전트가 스크립트를 실행하거나, 파일을 편집하거나, 아티팩트를 만들어야 할 때 environment.type을 openai_hosted로 설정하세요. OpenAI가 세션을 위해 샌드박스를 만들고 관리해요.

에이전트가 필요한 패키지, 파일, 네트워크 접근을 설정해요. harness는 샌드박스에서 직접 명령을 실행해요. 애플리케이션은 계속해서 작업을 보내고, 이벤트를 받고, 함수 도구를 처리해요.

점선 화살표는 아래에서 설명하는 것처럼 여러분이 환경을 직접 관리할 때만 적용돼요.

설정 옵션은 OpenAI-hosted environments를 참고하세요.

에이전트가 여러분의 인프라, 프라이빗 네트워크, 또는 커스텀 소프트웨어가 필요할 때 environment.type: "self_hosted"를 사용하세요.

여러분의 코드가 환경을 시작하고 executor를 세션에 연결해요. executor는 harness가 요청하는 명령과 도구를 실행해요. 애플리케이션은 각 명령을 전달하지 않고 연결과 수명 주기를 관리해요.

프로비저닝, 재연결, 종료, 보존해야 하는 파일을 여러분이 소유해요. 애플리케이션 서버나 웹훅 핸들러가 이 작업을 관리할 수 있어요.

컴퓨팅을 멈추기 전에 들어오는 작업을 조정하고 실행 중인 것이 없는지 확인하세요.

설정 및 종료 요구 사항은 Connect a sandbox와 Sandbox lifecycle을 참고하세요.

어떤 환경 선택에서든 다음 중 하나 또는 둘 다 사용할 수 있어요:

Streaming(스트리밍): 에이전트가 작업하면서 세부 이벤트를 받아요(예: 제품에 표시할 출력).
Webhooks(웹훅): 스트림을 열어 두지 않고 세션 상태 변경을 받아요. 여러분의 핸들러가 결과를 검색하거나, 함수 도구를 실행하거나, 자체 호스팅 환경을 관리할 수 있어요.

함수 도구에는 호출을 받아 결과를 반환하는 핸들러가 필요해요. 그 핸들러를 사용할 수 없으면 에이전트가 결과를 기다리며 대기 상태로 남을 수 있어요. 이벤트 또는 수명 주기 핸들러의 실패는 진행 업데이트나 환경 관리도 중단시킬 수 있어요.

통합 세부 사항은 Session events와 Webhooks를 참고하세요.