Codex com Azure OpenAI em modelos de Microsoft Foundry

O Codex CLI da OpenAI é o mesmo agente de codificação que dá suporte ao Codex do ChatGPT. Você pode executar esse agente de codificação inteiramente na infraestrutura do Azure, mantendo seus dados dentro de seu limite de conformidade, com as vantagens adicionais de segurança de nível empresarial, rede privada, controle de acesso baseado em papéis e gerenciamento de custos previsível. Codex é mais do que um chat com seu agente de código – é um agente de codificação assíncrono que pode ser disparado de seu terminal, VS Code ou de um GitHub Actions executor. O Codex permite que você abra automaticamente pull requests, refatore arquivos e realize testes com as credenciais de seu projeto do Foundry e implantações do OpenAI na Azure.

Pré-requisitos

• Uma assinatura Azure – Criar uma gratuitamente
• Permissões de colaborador no Microsoft Foundry.
• homebrew (macOS) ou Node.js com npm para instalar o CLI do Codex. Consulte Baixar e instalar Node.js e npm.
• Para Windows, instale e configure o WSL2. Consulte Instalação do WSL.

Implantar um modelo no Foundry

1. Vá para o Foundry e crie um novo projeto.
2. No catálogo de modelos, selecione um modelo de raciocínio, como gpt-5.3-codex, ,gpt-5.2-codexgpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1-codex-mini, , gpt-5-codex, gpt-5, gpt-5-miniou .gpt-5-nano
3. Para implantar o modelo no catálogo de modelos, selecione Utilize este modelo ou se estiver usando o painel Azure OpenAI Deployments selecione deploy model.
4. Copie o URL do endpoint e a chave de API.

Instalar a CLI do Codex

No terminal, execute os comandos a seguir para instalar a CLI do Codex

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

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

Criar e configurar config.toml

1. Para usar a CLI do Codex com Azure, você precisa criar e configurar um arquivo config.toml.

   O arquivo config.toml precisa ser armazenado no ~/.codex diretório. Crie um config.toml arquivo dentro desse diretório ou edite o arquivo existente se ele já existir:

   cd ~/.codex
   nano config.toml
   

2. Copie o texto abaixo para usar a API de Respostas v1. Com a API v1 , você não precisa mais passar a versão da API, mas deve incluir /v1 no base_url caminho. Você não pode passar sua chave de API como uma cadeia de caracteres diretamente para env_key. env_key deve apontar para uma variável de ambiente. Atualize seu base_url com o nome do seu 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. Depois de salvar as atualizações no config.toml arquivo, retorne ao terminal e crie uma instância da variável de ambiente referenciada no arquivo de configuração.

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

4. Agora, execute um dos seguintes comandos no terminal para testar se a configuração da CLI do Codex foi bem-sucedida:

   Comando	Propósito
   Codex	Iniciar TUI (Interface do Usuário do Terminal) interativa
   codex "Prompt inicial"	Iniciar a TUI com um prompt inicial
   codex exec "Prompt inicial"	Iniciar TUI no "modo de automação" não interativo

Usar codex no Visual Studio Code

Você também pode usar o Codex diretamente dentro de Visual Studio Code ao usar a extensão codex OpenAI

1. Se você ainda não tiver Visual Studio Code, poderá instalá-lo para macOS e Linux.

2. Instale a extensão OpenAI Codex. A extensão depende do seu arquivo config.toml que foi configurado para a CLI do Codex.

3. Se você estiver em uma nova sessão de terminal, configure a variável de ambiente para AZURE_OPENAI_API_KEY:

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

   Nota

   Se você usar o WSL, defina também a mesma variável de ambiente no host Windows para que a extensão possa lê-la quando necessário.

4. Inicie o VS Code na mesma sessão do Terminal. (O lançamento a partir de um lançador de aplicativos pode fazer com que sua variável de ambiente de chave de API não esteja disponível para a extensão Codex.)

   code .
   

5. Agora você poderá usar o Codex em Visual Studio Code para conversar, editar e visualizar alterações ao alternar entre três modos de aprovação.

Modos de aprovação

Os modos de aprovação determinam a quantidade de autonomia e interação que você deseja ter com o Codex.

Orientação persistente com AGENTS.md

Você pode fornecer ao Codex instruções e orientações extras usando arquivos AGENTS.md. O Codex procura por arquivos nos seguintes locais e os mescla de cima para baixo, conferindo-lhe contexto sobre suas preferências pessoais, detalhes específicos do projeto e a tarefa atual.

• ~/.codex/AGENTS.md– diretrizes globais pessoais.
• AGENTS.md na raiz do repositório – notas de projeto compartilhadas.
• AGENTS.md no diretório de trabalho atual – subpasta/especificações de recurso.

Por exemplo, para ajudar o Codex a entender como escrever código para o Foundry Agents, você pode criar um AGENTS.md na raiz do projeto com o seguinte conteúdo, derivado da documentação do SDK do Azure AI Agents:

# 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}")
\`\`\`

No exemplo anterior, os backticks no bloco de código Python são escapados para permitir a renderização adequada. Os \'s podem ser removidos.

Experimentar a CLI do Codex

Inicie o codex com o seguinte prompt inicial:

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

Outros testes sugeridos:

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

# refactor this agent to use the Code Interpreter tool instead

Codex no GitHub Actions

O Codex pode ser executado como parte do pipeline de integração contínua (CI). Armazene sua chave de API no armazenamento de segredos do repositório AZURE_OPENAI_KEY e adicione um trabalho semelhante a este para atualizar automaticamente o seu registro de alterações antes de um lançamento:

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"

Solucionando problemas