Códice con Azure OpenAI en modelos de Microsoft Foundry

La CLI del Codex de OpenAI es el mismo agente de codificación que impulsa el Codex de ChatGPT. Puede ejecutar este agente de codificación completamente en la infraestructura de Azure, al tiempo que mantiene los datos dentro de los límites de cumplimiento con las ventajas agregadas de seguridad de nivel empresarial, redes privadas, control de acceso basado en rol y administración de costos predecibles. 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. El Codex permite abrir automáticamente solicitudes de incorporación de cambios, refactorizar archivos y escribir pruebas con las credenciales del proyecto Foundry y las implementaciones de Azure OpenAI.

Prerrequisitos

Una suscripción de Azure: cree una gratuitamente.
Permisos de colaborador en Microsoft Foundry.
homebrew o npm para instalar la CLI del Codex o VS Code con la extensión del Codex.

Requisitos	Detalles
Sistemas operativos	macOS 12+, Ubuntu 20.04+/Debian 10+, o Windows 11 a través de WSL2
Git (opcional, recomendado)	2.23+ para asistentes integrados de solicitudes de incorporación de cambios
RAM	4 GB como mínimo (se recomienda 8 GB)

Implementación de un modelo en Foundry

Vaya a Foundry y cree un nuevo proyecto.
En el catálogo de modelos, seleccione un modelo de razonamiento como gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1-codex-minigpt-5-codex, gpt-5, , gpt-5-minio .gpt-5-nano
Para implementar el modelo desde el catálogo de modelos, seleccione Usar este modelo o, si usa el panel Implementaciones de Azure OpenAI, seleccione Implementar modelo.
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
brew

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

brew install codex
codex --version # verify installation

Creación y configuración de config.toml

Para usar la CLI de Codex con Azure, debe crear y configurar un config.toml archivo.

El archivo config.toml debe almacenarse 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
```
Copie el texto siguiente para usar la API de respuestas v1. Con la API v1 ya no es necesario pasar la versión de la API, pero debe 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"
```
Una vez que haya guardado las actualizaciones en config.toml el archivo, vuelva al terminal y cree una instancia de la variable de entorno a la que se hace referencia en el archivo de configuración.
```
# Linux, macOS, or WSL 
export AZURE_OPENAI_API_KEY="<your-api-key>"
```

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

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

Usar Codex en Visual Studio Code

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

Si aún no tiene Visual Studio Code, puede instalarlo para macOS y Linux.
Instale la extensión OpenAI Codex. La extensión se basa en tu archivo config.toml que se configuró para la CLI de Codex.
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"
```
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 .
```
Ahora podrá 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.

Modo de aprobación	Description
Chat	Para chatear y planear con el modelo.
Agente	El Codex puede leer archivos, realizar modificaciones y ejecutar comandos en el directorio de trabajo automáticamente. El Codex necesitará aprobación para las actividades fuera del directorio de trabajo o para acceder a Internet.
Agente (acceso total)	Todas las funcionalidades del modo Agente sin necesidad de aprobación paso a paso. El modo de acceso completo no debe usarse sin comprender plenamente los posibles riesgos, así como implementar medidas de protección adicionales, como ejecutarlo en un entorno de pruebas de espacio aislado controlado.

Importante

Se recomienda revisar las instrucciones de OpenAI sobre la seguridad del Codex.

Orientación continua con AGENTS.md

Puede proporcionar instrucciones y orientación adicional al Codex mediante los 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– guía global personal.
AGENTS.md en la raíz de tu repositorio: notas compartidas del proyecto.
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 Foundry Agents, podría crear un AGENTS.md elemento en la raíz del proyecto con el siguiente contenido, derivado de la documentación del SDK de Agentes de Azure AI:

# 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. Se pueden quitar los \.

Experimento con la CLI de Codex

Inicie Codex con la siguiente solicitud 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

Códice en las Acciones de GitHub

El Codex puede ejecutarse como parte de tu canalización 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

Síntoma	Solución
`401 Unauthorized` o `403 Forbidden`	Exporte correctamente la variable de entorno AZURE_OPENAI_API_KEY. Confirme que la clave tiene acceso de proyecto y/o implementación. Asegúrese de no pasar la clave de API como una cadena directamente a `env_key` en el `config.toml` archivo . Debe pasar una variable de entorno válida.
`ENOTFOUND`, `DNS error` o `404 Not Found`	Compruebe que `base_url` en `config.toml` use el nombre del recurso, el dominio correcto y que contenga `/v1`. Por ejemplo: `base_url = "https://<your-resource>.openai.azure.com/openai/v1"`.
La CLI omite la configuración de Azure	Abra `~/.codex/config.toml` y asegúrese de que: - `model_provider = "azure"` está establecido. - La `[model_providers.azure]` sección existe. - `env_key = "AZURE_OPENAI_API_KEY"` coincide con el nombre de la variable de entorno.
Compatibilidad con ID de Entra	La compatibilidad con Entra ID no está disponible actualmente para El Codex.
`401 Unauthorized` solo con la extensión WSL + VS Code Codex	Cuando se ejecuta VS Code desde dentro de WSL con la extensión Codex, la extensión puede comprobar la variable de entorno de clave de API en el host de Windows local en vez de en el shell de terminal que inició VS Code. Para mitigar este problema, establezca también la variable de entorno en el host de Windows local y, a continuación, inicie un nuevo terminal desde WSL e inicie VS Code con `code .`.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-12-04