Codex con Azure OpenAI en Microsoft Foundry Models

La CLI del Codex de OpenAI es el mismo agente de codificación que impulsa el Codex de ChatGPT. Puede ejecutar este agente de programación íntegramente en la infraestructura de Azure, manteniendo sus datos dentro de su perímetro de cumplimiento. Obtiene las ventajas agregadas de la seguridad de nivel empresarial, las redes privadas, el control de acceso basado en rol y la administración predecible de costos. El Codex es más que un chat con el agente de código: es un agente de codificación asincrónico que se puede desencadenar desde el terminal, VS Code o desde un ejecutor de Acciones de GitHub. Codex le permite abrir automáticamente solicitudes de incorporación de cambios, refactorizar archivos y escribir pruebas utilizando las credenciales de su proyecto de Foundry y de sus implementaciones de Azure OpenAI.

Requisitos previos

• Una suscripción Azure: Crear una gratuita
• Permisos de colaborador en Microsoft Foundry.
• homebrew (macOS) o Node.js con npm para instalar la CLI del Codex. Consulte Descarga e instalación de Node.js y npm.
• Para Windows, instale y configure WSL2. Consulte Instalación de WSL.

Implementación de un modelo en Foundry

1. Vaya a Foundry y cree un nuevo proyecto.
2. En el catálogo de modelos, seleccione un modelo de razonamiento como gpt-5.3-codex, , gpt-5.2-codexgpt-5.1-codex-maxgpt-5.1-codexgpt-5.1-codex-minigpt-5-codexgpt-5, o . gpt-5-minigpt-5-nano
3. Para implementar el modelo desde el catálogo de modelos, seleccione Usar este modelo. Si usa el panel Azure OpenAI Deployments, seleccione deploy model.
4. Copie la dirección URL del punto de conexión y la clave de API.

Instalación de la CLI de Codex

Desde el terminal, ejecute los siguientes comandos para instalar la CLI de Codex.

npm install -g @openai/codex
codex --version # verify installation

brew install --cask codex
codex --version # verify installation

Creación y configuración de config.toml

1. Para usar la CLI de Codex con Azure, cree y configure un archivo config.toml.

   Almacene el config.toml archivo en el ~/.codex directorio. Cree un config.toml archivo dentro de este directorio o edite el archivo existente si ya existe:

   cd ~/.codex
   nano config.toml
   

2. Copie el texto siguiente para usar la API de respuestas v1. Con la API v1 ya no es necesario proporcionar api-version, pero es obligatorio incluir /v1 en la ruta base_url. No se puede pasar la clave de API como una cadena directamente a env_key. env_key debe apuntar a una variable de entorno. Actualice su base_url con el nombre de su recurso:

   model = "gpt-5-codex"  # Replace with your actual Azure model deployment name
   model_provider = "azure"
   model_reasoning_effort = "medium"
   
   [model_providers.azure]
   name = "Azure OpenAI"
   base_url = "https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1"
   env_key = "AZURE_OPENAI_API_KEY"
   wire_api = "responses"
   

3. Después de guardar las actualizaciones en config.toml el archivo, vuelva al terminal y cree una instancia de la variable de entorno a la que hace referencia el archivo de configuración.

   # Linux, macOS, or WSL 
   export AZURE_OPENAI_API_KEY="<your-api-key>"
   

4. Ejecute uno de los siguientes comandos en el terminal para probar si la configuración de la CLI de Codex se realizó correctamente:

   Comando	Propósito
   codex	Iniciar la interfaz de usuario interactiva del terminal (TUI)
   códice "Indicación inicial"	Iniciar TUI con un mensaje inicial
   codex exec "Solicitud inicial"	Inicio de TUI en "modo de automatización" no interactivo

Uso del Codex en Visual Studio Code

También puede usar el Codex directamente dentro de Visual Studio Code al usar la extensión OpenAI Codex.

1. Si aún no tiene Visual Studio Code, instálelo para macOS y Linux.

2. Instale la extensión OpenAI Codex. La extensión se basa en el config.toml archivo que configuró para la CLI de Codex.

3. Si está en una nueva sesión de terminal, configure la variable de entorno para AZURE_OPENAI_API_KEY:

   export OPENAI_API_KEY="<your-azure-api-key-here>"
   

   Nota

   Si usa WSL, establezca también la misma variable de entorno en el host de Windows para que la extensión pueda leerla cuando sea necesario.

4. Inicie VS Code desde la misma sesión de terminal. (El inicio desde un iniciador de aplicaciones puede dar lugar a que la variable de entorno clave de API no esté disponible para la extensión de Codex).

   code .
   

5. Ahora puede usar El Codex en Visual Studio Code para chatear, editar y obtener una vista previa de los cambios mientras alterna entre tres modos de aprobación.

Modos de aprobación

Los modos de aprobación determinan la autonomía y la interacción que desea tener con Codex.

Orientación persistente con AGENTS.md

Puede dar a Codex instrucciones y orientación adicional mediante archivos AGENTS.md. El Codex busca AGENTS.md archivos en los siguientes lugares y los combina de arriba abajo, dándole contexto sobre sus preferencias personales, detalles específicos del proyecto y la tarea actual:

• ~/.codex/AGENTS.md – orientación personal global.
• AGENTS.md en la raíz del repositorio: notas del proyecto compartidas.
• AGENTS.md en el directorio de trabajo actual: subcarpetas o características específicas.

Por ejemplo, para ayudar a Codex a comprender cómo escribir código para Los agentes de Foundry, podría crear una AGENTS.md en la raíz del proyecto con el siguiente contenido, derivado de la documentación del SDK de agentes de IA de Azure:

# Instructions for working with Foundry Agents

You are an expert in the Azure AI Agents client library for Python.

## Key Concepts

- **Client Initialization**: Always start by creating an `AIProjectClient` or `AgentsClient`. The recommended way is via `AIProjectClient`.
- **Authentication**: Use `DefaultAzureCredential` from `azure.identity`.
- **Agent Creation**: Use `agents_client.create_agent()`. Key parameters are `model`, `name`, and `instructions`.
- **Tools**: Agents use tools to perform actions like file search, code interpretation, or function calls.
  - To use tools, they must be passed to `create_agent` via the `tools` and `tool_resources` parameters or a `toolset`.
  - Example: `file_search_tool = FileSearchTool(vector_store_ids=[...])`
  - Example: `code_interpreter = CodeInterpreterTool(file_ids=[...])`
  - Example: `functions = FunctionTool(user_functions)`

## Example: Creating a basic agent

\`\`\`python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# 1. Create Project Client
project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# 2. Get Agents Client
with project_client:
    agents_client = project_client.agents

    # 3. Create Agent
    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-helpful-agent",
        instructions="You are a helpful agent that can answer questions.",
    )
    print(f"Created agent with ID: {agent.id}")
\`\`\`

En el ejemplo anterior, los acentos graves en el bloque de código de Python se escapan para permitir una representación adecuada. Puede quitar los \ caracteres.

Experimento con la CLI de Codex

Inicie el código con el siguiente prompt inicial:

codex "write a python script to create an Azure AI Agent with file search capabilities"

Otras pruebas sugeridas:

# generate a unit test for src/utils/date.ts

# refactor this agent to use the Code Interpreter tool instead

Codex en Acciones de GitHub

Codex puede ejecutarse como parte del pipeline de integración continua (CI). Almacene la clave de API en el almacén de secretos del repositorio como AZURE_OPENAI_KEY y agregue un trabajo similar al siguiente para actualizar automáticamente el registro de cambios antes de una versión:

jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update changelog via Codex
        run: |
          npm install -g @openai/codex
          export AZURE_OPENAI_API_KEY="${{ secrets.AZURE_OPENAI_KEY }}" 
          codex -p azure exec --full-auto "update CHANGELOG for next release"

Solución de problemas