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 executar este agente de codificação inteiramente na infraestrutura Azure, mantendo os seus dados dentro dos limites de conformidade com as vantagens adicionais de 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 seu agente de código – é um agente de codificação assíncrono que pode ser ativado a partir do seu terminal, VS Code ou de um executor GitHub Actions. O Codex permite-lhe abrir automaticamente pull requests, ficheiros refatorizados e escrever testes com 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 Use este modelo, ou, se estiver a usar o Azure OpenAI Deployments selecione o painel deploy modelo.
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, é necessário criar e configurar um ficheiro config.toml.

   O ficheiro config.toml precisa de ser armazenado 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 abaixo para usar a API v1 Responses. Com a API v1 já não precisa fornecer a versão da API, mas deve incluir /v1 no caminho base_url. 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 do teu config.toml ficheiro, volta ao terminal e cria uma instância da variável ambiente que está referenciada no teu ficheiro 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 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

Usar 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, podes instalá-lo para macOS e Linux.

2. Instala a extensão OpenAI Codex. A extensão depende do teu config.toml ficheiro que foi configurado para 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. Lançar o VS Code a partir da mesma sessão do 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 poderá 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 pessoal global.
• AGENTS.md Na raiz do seu repositório – Notas de Projeto Partilhadas.
• AGENTS.md no diretório de trabalho atual – subpastas/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. Os \'s podem ser removidos.

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