이 가이드에서는 Oracle의 베타 Python 예제에 따라 애플리케이션 관리형 프로비저닝 방식을 사용합니다. 애플리케이션이 Agents API 세션과 OCI 샌드박스를 모두 직접 생성하고 삭제합니다.
OpenAI Cookbook의 애플리케이션 관리형 예제를 참고하세요.
프로비저닝 모드와 연결 방식은 샌드박스 수명 주기에서 확인하세요.
OCI GenAI 샌드박스는 베타 버전입니다. 계정에서 샌드박스를 사용하려면 Oracle 계정 담당자에게 액세스 권한을 요청하세요.
시작하기 전에
샌드박스 기능이 활성화된 Generative AI 프로젝트를 생성하세요. 프로젝트가 속한 컴파트먼트에서 프로젝트와 샌드박스를 관리할 수 있도록 OCI 자격 주체에 권한을 부여하세요. 다음 IAM 정책의 자리표시자를 실제 값으로 바꾸세요.
allow group <group-name> to manage generative-ai-sandbox in compartment <compartment-name>
allow group <group-name> to manage generative-ai-project in compartment <compartment-name>Node.js와 npm이 포함된 샌드박스 런타임을 사용하세요. Oracle 예제는 기본적으로 python-3.11을 요청합니다. 이 런타임에 npm이 없으면 호환되는 사용자 지정 런타임을 선택하세요.
프로젝트에서 아웃바운드 트래픽을 제한하는 경우, Codex를 설치할 수 있도록 registry.npmjs.org에 대한 HTTPS 연결을 허용하세요. api.openai.com에 대한 HTTPS 연결과 codex-cloud-environments.chatgpt.com에 대한 보안 WebSocket 연결도 허용하세요. 자세한 내용은 실행기의 네트워크 액세스를 참고하세요.
1. OCI CLI와 베타 SDK 설치
가상 환경을 생성하고 OCI CLI를 설치하세요.
uv venv --python 3.14
source .venv/bin/activate
uv pip install --upgrade oci-cli그런 다음 Oracle이 온보딩 과정에서 제공한 베타 Python SDK를 설치하세요.
uv pip install "/path/to/oci-<beta-version>-py3-none-any.whl"베타 SDK는 CLI를 설치한 후에 설치하세요. 베타 SDK를 설치한 뒤 oci-cli를 설치하거나 업그레이드하면 PyPI의 oci 패키지가 베타 SDK를 대체할 수 있습니다. 이 경우 베타 wheel 파일을 다시 설치하세요. 베타 SDK에는 oci.generative_ai_sandbox가 포함되어 있어야 합니다.
2. OCI 환경 구성
계정에서 사용하도록 활성화된 리전에서 보안 토큰 프로필을 인증하세요.
oci session authenticate --profile-name Sandbox --region us-chicago-1프로젝트 OCID와 OpenAI 자격 증명을 환경 변수로 설정하세요. 이 값들은 커밋하지 마세요.
export OCI_SANDBOX_PROJECT_ID="ocid1.generativeaiproject..."
export OPENAI_API_KEY="..."
export OPENAI_EXECUTOR_API_KEY="..."애플리케이션 요청에는 OPENAI_API_KEY를 사용하세요. OPENAI_EXECUTOR_API_KEY에는 환경 키를 설정하고, 샌드박스에는 이 키만 CODEX_API_KEY로 전달하세요.
Oracle 예제는 Sandbox 프로필을 읽고 us-chicago-1 리전을 사용합니다. 기본값을 변경하려면 다음과 같이 설정하세요.
export OCI_SANDBOX_PROFILE="my-profile"
export OCI_SANDBOX_REGION="us-chicago-1"예제에서는 다음 항목도 선택적으로 설정할 수 있습니다.
| 설정 | 기본값 |
|---|---|
OCI_SANDBOX_ENDPOINT |
https://inference.generativeai.<region>.oci.oraclecloud.com |
OCI_SANDBOX_RUNTIME |
python-3.11 |
OCI_SANDBOX_SHAPE |
SMALL |
OCI_SANDBOX_EXPIRATION |
PT30M (30분) |
자체 애플리케이션을 구성할 때는 프로필의 보안 토큰과 개인 키를 oci.auth.signers.SecurityTokenSigner에 전달하세요. 샌드박스 클라이언트를 생성할 때는 GenerativeAiSandboxClient를 oci.generative_ai_sandbox에서 가져와 선택한 리전과 엔드포인트를 지정하세요.
3. 애플리케이션 관리형 세션 실행
Agents API 요청과 실행기 시작 명령어는 자체 호스팅 연결 가이드를 참고하세요. Oracle 예제와 동일한 플로우로 진행하세요.
- 자체 호스팅 Agents API 세션을 생성할 때
/workspace를 작업 디렉터리로 지정하세요. 세션 ID와 환경 ID를 저장하세요. - OCI GenAI 샌드박스를 생성하고 상태가
RUNNING이 될 때까지 기다리세요. - Codex를 설치하고 샌드박스에
/workspace/brief.txt파일을 작성하세요. codex exec-server를 시작할 때 세션의 환경 ID와 환경 키를 사용하세요.- 세션 이벤트 스트림을 연 다음,
brief.txt를 바탕으로 마이그레이션 계획을 작성해 달라는 요청을 에이전트에 보내세요. 작업이 완료되면 생성된/workspace/plan.md를 읽으세요. - OCI 샌드박스를 중지하고 삭제한 다음 Agents API 세션을 삭제하세요. 한 리소스를 정리하는 데 실패하더라도 다른 리소스의 정리도 시도하세요.
후속 요청을 처리하려면 두 리소스를 모두 유지하고, 샌드박스를 삭제하기 전에 파일을 가져오세요. 프리뷰 릴리스에서는 샌드박스 API 이름이 바뀔 수 있으므로 Oracle이 지정한 베타 SDK 버전을 사용하세요.