Codex com Azure OpenAI nos Modelos da Fundição da Microsoft

A CLI Codex da OpenAI é o mesmo agente de programação que alimenta o Codex do ChatGPT. Pode correr este agente de codificação inteiramente na infraestrutura Azure, mantendo os seus dados dentro do limite de conformidade. Obtém as vantagens adicionais da segurança de nível empresarial, redes privadas, controlo de acesso baseado em funções e gestão de custos previsível. O Codex é mais do que uma conversa com o teu agente de código – é um agente de codificação assíncrono que podes ativar a partir do teu terminal, VS Code ou de um runner do GitHub Actions. O Codex permite-lhe abrir automaticamente pull requests, ficheiros de refatoração e escrever testes usando as credenciais do seu projeto Foundry e das implementações do Azure OpenAI.

Pré-requisitos

• Uma subscrição Azure - Crie uma gratuitamente
• Permissões dos colaboradores em Microsoft Foundry.
• homebrew (macOS) ou Node.js com npm para instalar o CLI do Codex. Veja Descarregar e instalar Node.js e npm.
• Para Windows, instale e configure o WSL2. Ver Instalar WSL.

Implementar um modelo no Foundry

1. Vai à Foundry e cria um novo projeto.
2. Do catálogo de modelos, selecione um modelo de raciocínio como gpt-5.3-codex, gpt-5.2-codex,gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5-codexgpt-5, , gpt-5-mini, , ou .gpt-5-nano
3. Para implementar o modelo a partir do catálogo de modelos, selecione Usar este modelo. Se estiver a usar o painel Azure OpenAI Deployments, selecione deploy model.
4. Copie a URL e a Chave da API do endpoint.

Instalar a CLI do Codex

A partir do terminal, execute os seguintes comandos para instalar o Codex CLI

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

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

Criar e configurar o config.toml

1. Para usar o Codex CLI com Azure, crie e configure um ficheiro config.toml.

   Guarda o config.toml ficheiro no ~/.codex diretório. Crie um config.toml ficheiro dentro deste diretório ou edite o ficheiro existente se este já existir:

   cd ~/.codex
   nano config.toml
   

2. Copie o texto seguinte para usar a API v1 Responses. Com a API v1 já não precisas de passar api-version, mas tens de incluir /v1 no base_url caminho. Não pode passar a sua chave API como uma string diretamente para env_key. env_key deve apontar para uma variável de ambiente. Atualize o 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 guardares as atualizações no teu config.toml ficheiro, volta ao terminal e cria uma instância da variável de ambiente que o ficheiro 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 do seu Codex CLI foi bem-sucedida:

   Comando	Finalidade
   Códice	Iniciar a Interface Interativa de Utilizador do Terminal (TUI)
   códice "Prompt inicial"	Lançar TUI com um prompt inicial
   Codex exec "Prompt inicial"	Lançar o TUI em modo "automação" não interativo

Use o Codex no Visual Studio Code

Também pode usar o Codex diretamente dentro de Visual Studio Code ao usar a extensão OpenAI Codex.

1. Se ainda não tiveres Visual Studio Code, instala-o para macOS e Linux.

2. Instala a extensão OpenAI Codex. A extensão depende do ficheiro config.toml que configurou para o Codex CLI.

3. Se estiver numa 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 usares WSL, define também a mesma variável de ambiente no host do Windows para que a extensão possa lê-la quando necessário.

4. Iniciar o VS Code a partir da mesma sessão de terminal. (O lançamento a partir de um iniciador de aplicações pode resultar na variável de ambiente da chave API não estar acessível para a extensão Codex.)

   code .
   

5. Agora pode usar o Codex no Visual Studio Code para conversar, editar e pré-visualizar alterações enquanto alterna entre três modos de aprovação.

Modos de aprovação

Os modos de aprovação determinam quanta autonomia e interação queres ter com o Codex.

Orientação persistente com AGENTS.md

Podes dar instruções e orientações extra ao Codex usando AGENTS.md ficheiros. O Codex procura AGENTS.md ficheiros nos seguintes locais e funde-os de cima para baixo, dando-lhe contexto sobre as suas preferências pessoais, detalhes específicos do projeto e a tarefa atual:

• ~/.codex/AGENTS.md – orientação global personalizada.
• AGENTS.md Na raiz do seu repositório – Notas de Projeto Partilhadas.
• AGENTS.md no diretório de trabalho atual – subpasta ou características específicas.

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

# 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 uma renderização adequada. Pode remover os caracteres \.

Experimentar com o Codex CLI

Código de lançamento 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 seu pipeline de integração contínua (CI). Guarda a tua chave API no armazenamento secreto do repositório como AZURE_OPENAI_KEY e depois adiciona uma tarefa como esta para atualizar automaticamente o teu registo 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"

Resolução de problemas