Oracle Cloud Infrastructure (OCI)

Esta guía sigue el ejemplo beta de Oracle en Python y usa el aprovisionamiento administrado por la aplicación: tu aplicación crea y elimina tanto la sesión de la API de agentes como el sandbox de OCI.

Consulta el ejemplo de administración por la aplicación en el OpenAI Cookbook.

Consulta Ciclo de vida del sandbox para conocer los modos de aprovisionamiento y el comportamiento de la conexión.

Antes de comenzar

Crea un proyecto de Generative AI con sandboxes habilitados. Otorga a tu identidad de OCI permiso para administrar proyectos y sandboxes en su compartimento. Reemplaza los marcadores de posición en estas políticas de 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>

Usa un entorno de ejecución de sandbox con Node.js y npm. El ejemplo de Oracle solicita python-3.11 de forma predeterminada; elige un entorno de ejecución personalizado compatible si no incluye npm.

Si tu proyecto restringe el tráfico saliente, permite conexiones HTTPS a registry.npmjs.org para instalar Codex, conexiones HTTPS a api.openai.com y conexiones WebSocket seguras a codex-cloud-environments.chatgpt.com. Consulta acceso a la red del ejecutor.

1. Instala la CLI de OCI y el SDK beta

Crea un entorno virtual e instala la CLI de OCI:

123uv venv --python 3.14
source .venv/bin/activate
uv pip install --upgrade oci-cli

Luego, instala el SDK beta de Python que Oracle proporciona durante la incorporación:

uv pip install "/path/to/oci-<beta-version>-py3-none-any.whl"

Instala el SDK beta después de la CLI. Instalar o actualizar oci-cli posteriormente puede reemplazar el SDK beta por el paquete oci de PyPI; si eso ocurre, vuelve a instalar el archivo wheel de la versión beta. El SDK beta debe incluir oci.generative_ai_sandbox.

2. Configura el entorno de OCI

Autentica un perfil de token de seguridad en la región habilitada para tu cuenta:

oci session authenticate --profile-name Sandbox --region us-chicago-1

Configura el OCID del proyecto y las credenciales de OpenAI sin incluirlos en un commit:

123export OCI_SANDBOX_PROJECT_ID="ocid1.generativeaiproject..."
export OPENAI_API_KEY="..."
export OPENAI_EXECUTOR_API_KEY="..."

Usa OPENAI_API_KEY para las solicitudes de la aplicación. Configura OPENAI_EXECUTOR_API_KEY con una clave de entorno y pasa solo esa clave al sandbox como CODEX_API_KEY.

El ejemplo de Oracle lee el perfil Sandbox y usa us-chicago-1. Para reemplazar sus valores predeterminados:

export OCI_SANDBOX_PROFILE="my-profile"
export OCI_SANDBOX_REGION="us-chicago-1"

El ejemplo también acepta estas opciones de configuración:

Al configurar tu propia aplicación, usa el token de seguridad y la clave privada del perfil con oci.auth.signers.SecurityTokenSigner. Crea un cliente de sandbox con GenerativeAiSandboxClient de oci.generative_ai_sandbox, usando la región y el punto de acceso seleccionados.

3. Ejecuta una sesión administrada por la aplicación

Usa la guía de conexión autoalojada para las solicitudes a la API de agentes y el comando de inicio del ejecutor. Sigue el mismo flujo que el ejemplo de Oracle:

1. Crea una sesión autoalojada de la API de agentes con /workspace como directorio de trabajo. Guarda el ID de la sesión y el ID del entorno.
2. Crea un OCI GenAI Sandbox y espera a que alcance el estado RUNNING.
3. Instala Codex y escribe el archivo /workspace/brief.txt en el sandbox.
4. Inicia codex exec-server con el ID del entorno de la sesión y la clave del entorno.
5. Abre el flujo de eventos de la sesión y luego envía un mensaje para pedirle al agente que convierta brief.txt en un plan de migración. Espera a que termine y lee el archivo /workspace/plan.md generado.
6. Detén y elimina el sandbox de OCI y luego elimina la sesión de la API de agentes. Intenta realizar ambas operaciones de limpieza incluso si una falla.

Mantén ambos recursos activos para los turnos posteriores y recupera los archivos antes de eliminar el sandbox. Usa la versión del SDK beta que especifica Oracle; las versiones preliminares pueden cambiar los nombres de las API de sandbox.

Referencias

• Lee la documentación de OCI Generative AI
• Lee la documentación del SDK de Python de OCI
• Lee la documentación del SDK de TypeScript de OCI
• Lee sobre la autenticación de la CLI de OCI