Azure Openai To Responses

Migrar Aplicativos Python de Azure OpenAI Chat Completions para Responses API

ORIENTAÇÃO AUTORITATIVA — SIGA EXATAMENTE

Esta habilidade migra bases de código Python que usam Azure OpenAI Chat Completions para a Responses API unificada. Siga estas instruções com precisão. Não improvise mapeamentos de parâmetros nem invente formatos de API.

Gatilhos

Ative esta habilidade quando o usuário quiser:

• Migrar um app Python de Azure OpenAI Chat Completions para Responses API
• Atualizar o uso do SDK Python OpenAI para o formato mais recente da API contra Azure OpenAI
• Preparar código Python para modelos GPT-5 ou mais recentes que requerem Responses na Azure
• Mudar de AzureOpenAI/AsyncAzureOpenAI para o cliente padrão OpenAI/AsyncOpenAI com o endpoint v1
• Corrigir avisos de depreciação relacionados a construtores AzureOpenAI ou api_version

⚠️ Compatibilidade de Modelo — VERIFIQUE PRIMEIRO

Antes de migrar, verifique se sua implantação Azure OpenAI suporta a Responses API.

1. Teste simples da implantação (mais rápido)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)

try:
    resp = client.responses.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        input="ping",
        max_output_tokens=50,
        store=False,
    )
    print(f"✅ Deployment supports Responses API: {resp.output_text}")
except Exception as e:
    print(f"❌ Deployment does NOT support Responses API: {e}")

Nota: max_output_tokens tem um mínimo de 16 na Azure OpenAI. Valores abaixo de 16 retornam erro 400. Use 50+ para testes simples.

Se isto retornar 404, o modelo da implantação ainda não suporta Responses — consulte a referência abaixo ou reimplemente com um modelo suportado.

2. Verifique os modelos disponíveis na sua região (recomendado)

Execute a ferramenta embutida de compatibilidade de modelos para ver o que está disponível com suporte à Responses API em sua região específica:

python migrate.py models --subscription YOUR_SUB_ID --location YOUR_REGION

Esta consulta à Azure ARM ao vivo mostra uma matriz de compatibilidade — quais modelos suportam Responses, saída estruturada, ferramentas, etc. Use --filter gpt-5.1,gpt-5.2 para filtrar resultados ou --json para script.

3. Referência completa de suporte a modelos

• Consulta ao vivo: python migrate.py models (veja acima — específico por região, sempre atualizado)
• Navegue disponibilidade: Tabela resumo de modelos e disponibilidade regional
• Início rápido e orientações: https://aka.ms/openai/start

⚠️ Limitações de modelos antigos

AVISO: Modelos antigos (anteriores a gpt-4.1) podem não suportar totalmente todos os recursos da Responses API.

Limitações conhecidas com modelos antigos:

• Parâmetro reasoning: Não suportado em muitos modelos sem raciocínio. Migrar reasoning só se já estiver presente no código original.
• Parâmetro seed: Não suportado na Responses API — remova de todas as requisições.
• Saída estruturada via text.format: Modelos antigos podem não aplicar esquemas JSON strict: true de forma confiável.
• Orquestração de ferramentas: GPT-5+ orquestra chamadas de ferramentas como parte do raciocínio interno. Modelos antigos no Responses funcionam, mas sem essa integração profunda.
• Restrições de temperatura: Ao migrar para gpt-5, a temperatura deve ser omitida ou definida como 1. Modelos antigos não têm essa restrição.

Modelos de raciocínio da série O (o1, o3-mini, o3, o4-mini)

Modelos da série O têm restrições exclusivas de parâmetros. Ao migrar apps que usam modelos da série O:

• temperature: Deve ser 1 (ou omitido). Modelos da série O não aceitam outros valores.
• max_completion_tokens → max_output_tokens: Apps usando o específico max_completion_tokens do Azure devem mudar para max_output_tokens. Defina valores altos (4096+) pois tokens de raciocínio contam no limite.
• reasoning_effort: Se o app usa reasoning_effort (baixo/médio/alto), mantenha — a Responses API suporta esse parâmetro para modelos da série O.
• Comportamento de streaming: Modelos da série O podem armazenar saída até o raciocínio finalizar antes de emitir eventos de delta de texto. Streaming ainda funciona, mas o primeiro response.output_text.delta pode chegar com delay maior que em modelos GPT.
• top_p: Não suportado na série O — remova se presente.
• Uso de ferramentas: Modelos da série O suportam ferramentas pela Responses API igual aos modelos GPT, mas a qualidade da orquestração varia com o modelo.

Ação — aviso proativo de modelo: Durante a fase de análise, verifique qual modelo o app usa (nomes de implantação, variáveis de ambiente, config). Se o modelo for anterior a gpt-4.1 (não gpt-4.1+), informe proativamente ao usuário:

• A migração funcionará para texto básico, chat, streaming e ferramentas no modelo atual.
• Modelos mais novos (gpt-5.1, gpt-5.2) oferecem melhor orquestração de ferramentas, aplicação de saída estruturada, raciocínio e disponibilidade cross-region.
• Ele deve considerar atualizar a implantação quando quiser — não bloqueia a migração.

Não bloqueie nem recuse a migração por versão do modelo. O aviso é informativo.

GitHub Models NÃO suporta a Responses API

GitHub Models (models.github.ai, models.inference.ai.azure.com) não suporta a Responses API.

Se a base de código tiver um caminho de código GitHub Models (procure base_url apontando para models.github.ai ou models.inference.ai.azure.com), remova completamente durante a migração. A Responses API requer Azure OpenAI, OpenAI, ou endpoint local compatível (ex: Ollama com suporte a Responses).

Ação durante a análise:

• Identifique qualquer caminho de código GitHub Models para remoção.

Migração de Framework

Muitos apps usam frameworks de nível superior sobre OpenAI. Ao migrar, alteram-se também as APIs do framework — não apenas as chamadas subjacentes OpenAI.

Microsoft Agent Framework (MAF)

Verifique sua versão do MAF primeiro — a migração depende se você está no MAF 1.0.0+ ou numa beta/rc pré-1.0.0.

MAF 1.0.0+ (agent-framework-openai >= 1.0.0)

OpenAIChatClient já usa Responses API — não precisa migrar. Se o código usa o legado OpenAIChatCompletionClient (que usa chat.completions.create), substitua por OpenAIChatClient.

Para checar sua versão: python -c "import agent_framework_openai; print(agent_framework_openai.__version__)"

MAF pré-1.0.0 (lançamentos beta/rc)

No MAF pré-1.0.0, OpenAIChatClient usava Chat Completions. Atualize para agent-framework-openai>=1.0.0 onde OpenAIChatClient usa Responses API por padrão.

Nenhuma outra mudança necessária — as APIs Agent e de ferramentas permanecem iguais.

LangChain (langchain-openai)

Adicione use_responses_api=True a ChatOpenAI(). Também atualize o acesso à resposta de .content para .text.

Para exemplos completos de código antes/depois, veja cheat-sheet.md.

Orientação para Migração do Frontend

A Responses API é uma preocupação do lado servidor. Migre seu backend Python; o contrato HTTP do frontend deve permanecer inalterado, a menos que seu backend seja uma passagem fina — nesse caso, considere adotar o formato Requests Responses para eliminar uma camada de tradução. Se o frontend chama OpenAI diretamente com chave no cliente, mova essas chamadas para o backend primeiro.

Depreciação do @microsoft/ai-chat-protocol

O pacote npm @microsoft/ai-chat-protocol está depreciado e deve ser substituído por ndjson-readablestream. Se encontrá-lo em um frontend:

1. Substitua a tag script CDN:

   <!-- Before -->
   <script src="https://cdn.jsdelivr.net/npm/@microsoft/ai-chat-protocol@.../dist/iife/index.js"></script>
   <!-- After -->
   <script src="https://cdn.jsdelivr.net/npm/ndjson-readablestream@1.0.7/dist/ndjson-readablestream.umd.js"></script>
   

2. Remova a instanciação AIChatProtocolClient (new ChatProtocol.AIChatProtocolClient("/chat")).
3. Substitua client.getStreamedCompletion(messages) por uma chamada fetch() direta ao endpoint de streaming do backend.
4. Substitua for await (const response of result) por for await (const chunk of readNDJSONStream(response.body)).
5. Atualize o acesso a propriedades de response.delta.content / response.error para chunk.delta.content / chunk.error.

Objetivos

• Enumerar todos os pontos de chamadas Python que usam Chat Completions ou Completions legadas contra Azure OpenAI.
• Propor um plano de migração e sequenciamento para a base de código Python.
• Aplicar edições seguras e mínimas para mudar à Responses API.
• Atualizar chamadores para consumir o esquema de saída do Responses; sem wrappers de retrocompatibilidade.
• Rodar testes/lints; corrigir quebras triviais causadas pela migração.
• Preparar pequenos conjuntos de mudanças revisáveis e fornecer um resumo final com diffs (não commite).

Limites de Segurança

• Modifique apenas arquivos dentro da workspace git. Nunca escreva fora.
• Não preserve shims de retrocompatibilidade; migre código para o novo formato da API.
• Não deixe comentários de transição/tombstone ou arquivos de backup.
• Preserve semântica de streaming se usada antes; senão use não streaming.
• Peça aprovação antes de executar comandos ou chamadas de rede se estiver em modo de aprovação.
• Não execute git add/git commit/git push; produza apenas edições na working tree.

Passo 0: Migração do Cliente Azure OpenAI (Pré-requisito)

Se a base de código usar construtores AzureOpenAI ou AsyncAzureOpenAI, migre primeiro para os construtores padrão OpenAI / AsyncOpenAI. Os construtores específicos Azure estão depreciados em openai>=1.108.1.

Por que o caminho v1 da API?

O novo endpoint /openai/v1 usa o cliente padrão OpenAI() em vez de AzureOpenAI(), não requer parâmetro api_version, e funciona exatamente igual em OpenAI e Azure OpenAI. O mesmo código cliente é à prova de futuro — não precisa gerenciar versões.

Mudanças principais

Checklist de limpeza

• Remova argumento api_version da construção do cliente.
• Remova variáveis de ambiente AZURE_OPENAI_VERSION / AZURE_OPENAI_API_VERSION de .env, configurações do app e arquivos Bicep/infra.
• Renomeie AZURE_OPENAI_CLIENT_ID → AZURE_CLIENT_ID em .env, configurações do app, Bicep/infra, e fixtures de teste (convenção padrão SDK Azure Identity).
• Garanta openai>=1.108.1 em requirements.txt ou pyproject.toml.

Migração de variáveis de ambiente

Para exemplos de configuração de cliente (sync, async, EntraID, chave API, multi-tenant), veja cheat-sheet.md.

Passo 1: Detectar Pontos de Chamadas Legadas

Execute o script detect_legacy.py para encontrar todos os pontos de chamada que precisam migrar:

python skills/azure-openai-to-responses/scripts/detect_legacy.py .

Ou faça buscas manuais — cada correspondência é um alvo de migração:

# Chamadas de API legadas (precisa reescrever)
rg "chat\.completions\.create"
rg "ChatCompletion\.create"
rg "Completion\.create"

# Construtores de cliente Azure obsoletos (precisa substituir)
rg "AzureOpenAI\("
rg "AsyncAzureOpenAI\("

# Padrões de acesso à forma da resposta (precisa atualizar)
rg "choices\[0\]\.message\.content"
rg "choices\[0\]\.delta\.content"
rg "choices\[0\]\.message\.function_call"
rg "choices\[0\]\.message\.tool_calls"

# Definições de ferramentas em formato antigo aninhado (precisa achatar)
rg '"function":\s*{\s*"name"'
rg "pydantic_function_tool"

# Resultados da ferramenta em formato antigo (precisa converter para function_call_output)
rg '"role":\s*"tool"'
rg '"tool_call_id"'

# Parâmetros obsoletos (precisa remover ou renomear)
rg "response_format"
rg "max_tokens\b"        # renomear para max_output_tokens
rg "['\"]seed['\"]"      # remove entirely

# Variáveis de ambiente obsoletas (limpar)
rg "AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION"
rg "AZURE_OPENAI_CLIENT_ID"  # deveria ser AZURE_CLIENT_ID

# Endpoints de Modelos do GitHub (precisa remover — API de Respostas não suportada)
rg "models\.github\.ai|models\.inference\.ai\.azure"

# Padrões legados no nível do framework (precisa atualizar)
rg "OpenAIChatCompletionClient"  # MAF 1.0.0+: substituir por OpenAIChatClient
rg "ChatOpenAI\(" | grep -v "use_responses_api"  # LangChain: precisa de use_responses_api=True

# Infraestrutura de teste (precisa atualizar)
rg "ChatCompletionChunk|AsyncCompletions\.create" tests/
rg "_azure_ad_token_provider" tests/
rg "prompt_filter_results|content_filter_results" tests/
rg "choices\[0\]" tests/

# Acesso ao corpo de erro do filtro de conteúdo (precisa atualizar — estrutura mudou)
rg 'innererror.*content_filter_result|error\.body\["innererror"\]'
rg "content_filter_result\[" # forma singular antiga — agora content_filter_results (plural) dentro do array content_filters

# Chamadas HTTP brutas para o endpoint de Chat Completions (precisa atualizar URL)
rg "/openai/deployments/.*/chat/completions"
rg "api-version="

Heurísticas (detectar e reescrever)

• Cliente Chat Completions: client.chat.completions.create → client.responses.create(...).

• Construtores de cliente Azure: AzureOpenAI(...) → OpenAI(base_url=..., api_key=...).

• Ferramentas: converta definições de ferramentas com chamada de função do formato aninhado ({"type": "function", "function": {"name": ...}}) para o formato plano do Responses ({"type": "function", "name": ...}); use tool_choice; retorne resultados das ferramentas como itens {"type": "function_call_output", "call_id": ..., "output": ...} (não {"role": "tool", ...}).

• Ciclo das ferramentas: quando o modelo retornar chamadas de funções, anexe os itens response.output à conversa (não um dicionário manual {"role": "assistant", "tool_calls": [...]}), depois anexe os itens function_call_output para cada resultado.

• Exemplos de ferramentas few-shot: se a conversa incluir exemplos embutidos de chamadas de ferramentas, converta-os em itens {"type": "function_call", "id": "fc_...", "call_id": "fc_...", ...} + {"type": "function_call_output", ...}. IDs devem começar com fc_.

• pydantic_function_tool(): esse auxiliar ainda gera o formato aninhado antigo e não é compatível com responses.create(). Substitua por definições manuais de ferramentas ou um wrapper de achatamento.

• Multi-turn: mantenha o histórico da conversa na aplicação; passe turnos anteriores via itens input.

• Formatação: substitua o response_format do nível superior do Chat por text.format no Responses. Forma canônica: text={"format": {"type": "json_schema", "name": "Output", "strict": True, "schema": {...}}}.

• Itens de conteúdo: substitua Chat content[].type: "text" por Responses content[].type: "input_text" para turnos de usuário/sistema.

• Itens de conteúdo de imagem: substitua Chat content[].type: "image_url" por Responses content[].type: "input_image". O campo image_url muda de um objeto aninhado {"url": "..."} para uma string simples. Veja a folha de dicas para exemplos antes/depois.

• Esforço de raciocínio: migre reasoning somente se ele já existir no código original.

• Tratamento de erro do filtro de conteúdo: a estrutura do corpo do erro mudou. Chat Completions usava error.body["innererror"]["content_filter_result"] (singular); a API Responses usa error.body["content_filters"][0]["content_filter_results"] (plural, dentro de um array). Código que acessa innererror levantará KeyError. Reescreva para usar o novo caminho.

• Chamadas HTTP brutas: se o app chama a API REST Azure OpenAI diretamente (via requests, httpx, etc.) usando /openai/deployments/{name}/chat/completions?api-version=..., reescreva para /openai/v1/responses. O corpo da requisição muda: messages → input, adicione max_output_tokens e store: false, remova o parâmetro de query api-version. O corpo da resposta muda: choices[0].message.content → output[0].content[0].text (nota: output_text é uma propriedade de conveniência do SDK não presente no JSON REST cru).

Etapa 2: Aplicar Migração

Notas de migração (Chat Completions → Responses)

• Por que migrar: Responses é a API unificada para texto, ferramentas e streaming; Chat Completions é legado. Com GPT-5, Responses é obrigatório para melhor desempenho.
• HTTP: o endpoint Azure muda de /openai/deployments/{name}/chat/completions para /openai/v1/responses.
• Campos: messages → input, max_tokens → max_output_tokens. temperature permanece.
• Formatação: response_format → text.format com objeto adequado.
• Itens de conteúdo: substitua Chat content[].type: "text" por Responses content[].type: "input_text" para turnos de sistema/usuário.
• Itens de conteúdo de imagem: substitua Chat content[].type: "image_url" por Responses content[].type: "input_image". Achate o campo image_url de {"image_url": {"url": "..."}} para {"image_url": "..."} (uma string simples — URL HTTPS ou URI de dados data:image/...;base64,...).

Referência de mapeamento de parâmetros

Para exemplos completos antes/depois de código, veja cheat-sheet.md.

Para migração de infraestrutura de teste (mocks, snapshots, assertions), veja test-migration.md.

Para solução de problemas e armadilhas, veja troubleshooting.md.

Retenção de Dados & Estado

• Defina store: false em todas as requisições Responses.
• Não confie em IDs de mensagens anteriores ou contexto armazenado no servidor; mantenha o estado gerenciado pelo cliente e minimize metadados.

Critérios de Aceitação

Barreiras de nível de código (todas devem passar)

• Zero correspondências para rg "chat\.completions\.create|ChatCompletion\.create|Completion\.create" nos arquivos migrados.
• Zero correspondências para rg "AzureOpenAI\(|AsyncAzureOpenAI\(" — todos os construtores usam OpenAI/AsyncOpenAI com o endpoint v1.
• Zero correspondências para rg "models\.github\.ai|models\.inference\.ai\.azure" — caminhos de código dos modelos do GitHub removidos.
• Zero correspondências para rg "OpenAIChatCompletionClient" — código MAF 1.0.0+ usa OpenAIChatClient (que usa Responses API). Em versões pré-1.0.0, atualize para agent-framework-openai>=1.0.0.
• Todas chamadas ChatOpenAI(...) incluem use_responses_api=True.
• Zero correspondências para rg "choices\[0\]" — todo acesso a respostas usa resp.output_text ou o esquema de saída Responses.
• Nenhum response_format no nível superior; toda saída estruturada usa text={"format": {...}}.
• openai>=1.108.1 e azure-identity em requirements.txt ou pyproject.toml; dependências reinstaladas.
• store=False definido em toda chamada responses.create.
• Nenhum api_version na construção do cliente; AZURE_OPENAI_API_VERSION removido de arquivos e infraestrutura de ambiente.

Barreiras da infraestrutura de teste (todas devem passar)

• Zero correspondências para rg "ChatCompletionChunk|AsyncCompletions\.create|chat\.completions" tests/.
• Zero correspondências para rg "_azure_ad_token_provider" tests/ — asserções atualizadas para verificar isinstance(client, AsyncOpenAI) ou base_url.
• Zero correspondências para rg "prompt_filter_results|content_filter_results" tests/ — mocks do filtro específicos do Azure removidos.
• Mocks usam kwargs.get("input") e não kwargs.get("messages").
• Arquivos snapshot / golden atualizados para a forma de streaming Responses (sem choices[0], function_call, logprobs, etc.).
• pytest passa sem falhas após todas as atualizações de testes.

Barreiras comportamentais (verificar manualmente ou via suíte de testes)

• Completion básica: responses.create não-streaming retorna output_text não vazio.
• Paridade de streaming: se o código original usava streaming, o código migrado também faz streaming e emite eventos response.output_text.delta com deltas não vazios.
• Saída estruturada: se usa text.format com json_schema, json.loads(resp.output_text) funciona e corresponde ao esquema.
• Loop de chamada de ferramentas: se ferramentas são usadas, o modelo emite chamadas, o app executa, e a requisição subsequente retorna um output_text final (sem loop infinito).
• Paridade assíncrona: se usava AsyncAzureOpenAI, o equivalente AsyncOpenAI funciona com await.
• Taxa de erro: não há novos erros 400/401/404 comparados ao baseline pré-migração.

Entregáveis

• O resumo inclui arquivos editados, contagens antes/depois dos pontos de chamadas legadas e próximos passos.
• As mudanças são edições na árvore de trabalho apenas (sem commits).

Requisitos de Versão do SDK

Referências

• Folha de Dicas — todos os trechos de código
• Migração de Testes — mocks, snapshots, assertions
• Resolução de Problemas — erros, tabela de riscos, armadilhas
• detect_legacy.py — scanner automatizado
• Kit Inicial Azure OpenAI
• Documentação Azure OpenAI Responses API
• Ciclo de vida da versão da API Azure OpenAI
• Referência da API OpenAI Responses

Aviso Legal: Este documento foi traduzido usando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.

Source: microsoft/ai-agents-for-beginners → translations/pt-BR/.agents/skills/azure-openai-to-responses/SKILL.md