本指南依循 Oracle 的 Beta 版 Python 範例，採用 由應用程式管理的佈建方式：由你的應用程式建立及刪除 Agents API 工作階段和 OCI 沙盒。
請參閱 OpenAI Cookbook 中由應用程式管理的範例。
如需了解佈建模式和連線行為，請參閱沙盒生命週期。
OCI GenAI 沙盒目前處於 Beta 測試階段。請聯絡你的 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，請選擇相容的自訂執行環境。
如果你的專案限制對外流量，請允許連往 registry.npmjs.org 的 HTTPS 連線以安裝 Codex、連往 api.openai.com 的 HTTPS 連線，以及連往 codex-cloud-environments.chatgpt.com 的安全 WebSocket 連線。請參閱執行器網路存取。
1. 安裝 OCI CLI 和 Beta 版 SDK
建立虛擬環境並安裝 OCI CLI：
uv venv --python 3.14
source .venv/bin/activate
uv pip install --upgrade oci-cli接著安裝 Oracle 在導入過程中提供的 Beta 版 Python SDK：
uv pip install "/path/to/oci-<beta-version>-py3-none-any.whl"請在安裝 CLI 之後 再安裝 Beta 版 SDK。如果之後安裝或升級 oci-cli，可能會將 Beta 版 SDK 替換成 PyPI 上的 oci 套件；若發生這種情況，請重新安裝 Beta 版 wheel。Beta 版 SDK 必須包含 oci.generative_ai_sandbox。
2. 設定 OCI 環境
在已為你的帳戶啟用的區域中，為安全 Token 設定檔進行身分驗證：
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 分鐘） |
設定自己的應用程式時，請將設定檔中的安全 Token 和私密金鑰搭配 oci.auth.signers.SecurityTokenSigner 使用。使用 oci.generative_ai_sandbox 中的 GenerativeAiSandboxClient，依所選區域和端點建立沙盒用戶端。
3. 執行由應用程式管理的工作階段
請依照自行託管連線指南，使用其中的 Agents API 請求和執行器啟動指令。依循與 Oracle 範例相同的流程：
- 建立自行託管的 Agents API 工作階段，並以
/workspace作為工作目錄。儲存工作階段 ID 和環境 ID。 - 建立 OCI GenAI 沙盒，並等待其進入
RUNNING狀態。 - 安裝 Codex，並將
/workspace/brief.txt寫入沙盒。 - 使用工作階段的環境 ID 和環境金鑰啟動
codex exec-server。 - 開啟工作階段事件串流，然後傳送輸入，要求智慧體將
brief.txt轉換成遷移計畫。等待完成後，讀取產生的/workspace/plan.md。 - 停止並刪除 OCI 沙盒，然後刪除 Agents API 工作階段。即使其中一項清理作業失敗，仍應嘗試執行另一項。
保留這兩項資源，以便繼續後續回合，並在刪除沙盒前取回檔案。請使用 Oracle 指定的 Beta 版 SDK；預覽版本可能會變更沙盒 API 的名稱。