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 aprovisionamiento administrado por la aplicación en OpenAI Cookbook.

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

Antes de comenzar

Crea un proyecto de IA generativa con los sandboxes habilitados. Otorga a tu identidad de OCI permisos para administrar proyectos y sandboxes en el compartimento del proyecto. 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 que incluya Node.js y npm. El ejemplo de Oracle solicita python-3.11 de forma predeterminada. Si ese entorno no incluye npm, elige un entorno de ejecución personalizado compatible.

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 del ejecutor a la red.

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 te proporcionó durante la incorporación:

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

Instala el SDK beta después de instalar la CLI. Si luego instalas o actualizas oci-cli, es posible que el paquete oci de PyPI reemplace el SDK beta. 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 con un 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 ningún 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 la región us-chicago-1. Para cambiar esos valores predeterminados, configura estas variables:

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

El ejemplo también admite estos ajustes opcionales:

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 y usa la región y el punto de acceso seleccionados.

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

Consulta la guía de conexión para entornos autoalojados para ver las solicitudes a la API de agentes y el comando de inicio del ejecutor. Sigue los mismos pasos que en 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 sandbox de OCI GenAI y espera a que pase al 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 de entorno.
5. Abre el flujo de eventos de la sesión y luego pídele al agente en un mensaje que convierta brief.txt en un plan de migración. Espera a que termine y lee el archivo generado /workspace/plan.md.
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 aunque una falle.

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 indique Oracle. Los nombres de las API de sandbox pueden cambiar en las versiones preliminares.

Referencias

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