Oracle Cloud Infrastructure (OCI)

Este guia segue o exemplo beta da Oracle em Python e usa provisionamento gerenciado pela aplicação: sua aplicação cria e exclui tanto a sessão da API de Agentes quanto o sandbox da OCI.

Veja o exemplo de gerenciamento pela aplicação no OpenAI Cookbook.

Consulte Ciclo de vida do sandbox para saber mais sobre os modos de provisionamento e o comportamento da conexão.

Antes de começar

Crie um projeto do Generative AI com suporte a sandbox habilitado. Conceda à sua identidade da OCI permissão para gerenciar projetos e sandboxes no compartimento do projeto. Substitua os placeholders nestas 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>

Use um ambiente de execução de sandbox com Node.js e npm. O exemplo da Oracle solicita python-3.11 por padrão; escolha um ambiente de execução personalizado compatível se ele não incluir npm.

Se o seu projeto restringir o tráfego de saída, permita HTTPS para registry.npmjs.org para instalar o Codex, HTTPS para api.openai.com e conexões WebSocket seguras para codex-cloud-environments.chatgpt.com. Consulte acesso à rede do executor.

1. Instale a CLI da OCI e o SDK beta

Crie um ambiente virtual e instale a CLI da OCI:

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

Em seguida, instale o SDK beta para Python fornecido pela Oracle durante a integração inicial:

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

Instale o SDK beta depois da CLI. Instalar ou atualizar oci-cli depois disso pode substituir o SDK pelo pacote oci do PyPI; reinstale o wheel beta se isso acontecer. O SDK beta deve incluir oci.generative_ai_sandbox.

2. Configure o ambiente da OCI

Autentique um perfil que usa token de segurança na região habilitada para sua conta:

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

Defina o OCID do projeto e as credenciais da OpenAI sem incluí-los em commits:

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

Use OPENAI_API_KEY para as requisições do aplicativo. Defina OPENAI_EXECUTOR_API_KEY como uma chave de ambiente e passe apenas essa chave para o sandbox como CODEX_API_KEY.

O exemplo da Oracle lê o perfil Sandbox e usa us-chicago-1. Para substituir os valores padrão:

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

O exemplo também aceita estas configurações opcionais:

Ao configurar sua própria aplicação, use o token de segurança e a chave privada do perfil com oci.auth.signers.SecurityTokenSigner. Crie um cliente de sandbox com GenerativeAiSandboxClient de oci.generative_ai_sandbox, usando a região e o endpoint selecionados.

3. Execute uma sessão gerenciada pela aplicação

Use o guia de conexão com hospedagem própria para consultar as solicitações à API de Agentes e o comando de inicialização do executor. Siga o mesmo fluxo do exemplo da Oracle:

1. Crie uma sessão da API de Agentes com hospedagem própria e /workspace como diretório de trabalho. Salve o ID da sessão e o ID do ambiente.
2. Crie um OCI GenAI Sandbox e aguarde até que ele atinja o estado RUNNING.
3. Instale o Codex e grave /workspace/brief.txt no sandbox.
4. Inicie codex exec-server usando o ID do ambiente da sessão e a chave do ambiente.
5. Abra o fluxo de eventos da sessão e envie uma entrada pedindo ao agente que transforme brief.txt em um plano de migração. Aguarde a conclusão e leia o arquivo /workspace/plan.md gerado.
6. Pare e exclua o sandbox da OCI e, em seguida, exclua a sessão da API de Agentes. Tente realizar as duas operações de limpeza mesmo que uma delas falhe.

Mantenha ambos os recursos ativos para os próximos turnos e recupere os arquivos antes de excluir o sandbox. Use a versão do SDK beta especificada pela Oracle; versões de prévia podem alterar os nomes das APIs de sandbox.

Referências

• Leia a documentação do OCI Generative AI
• Leia a documentação do SDK da OCI para Python
• Leia a documentação do SDK da OCI para TypeScript
• Leia sobre autenticação da CLI da OCI