Codex com Azure OpenAI em modelos de Microsoft Foundry

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

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 Usar este modelo. Se você estiver usando o painel Azure OpenAI Deployments, selecione deploy model.
4. Copie a URL do ponto de extremidade 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, crie e configure um arquivo config.toml.

   Armazene o config.toml arquivo 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 a seguir para usar a API de Respostas v1. Com a API v1 , você não precisa mais passar api-version, 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 que o arquivo de configuração referencia.

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

4. 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 a Interface de Usuário do Terminal (TUI) interativa
   codex "Prompt inicial"	Inicie o 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, instale-o para macOS e Linux.

2. Instale a extensão OpenAI Codex. A extensão usa seu arquivo config.toml que você configurou 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 de 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ê pode 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 instruções e orientações adicionais ao Codex 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 – especificações da subpasta ou recursos.

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, as aspas invertidas no bloco de código do Python são ignoradas para permitir a renderização adequada. Você pode remover os \ caracteres.

Experimentar com 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 repositório de segredos do repositório como AZURE_OPENAI_KEY e adicione uma tarefa como esta para atualizar automaticamente seu changelog 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