azure-openai-to-responses

name	azure-openai-to-responses
license	MIT
description	Ilipat ang mga Python app mula sa Azure OpenAI Chat Completions papuntang Responses API. Saklaw nito ang pag-migrate ng AzureOpenAI/AsyncAzureOpenAI client sa v1 endpoint, streaming, tools, structured output, multi-turn, EntraID auth, at mga pagsusuri sa compatibility ng modelo. Nakatuon sa Python, para sa Azure OpenAI. GAMITIN PARA SA: pag-migrate sa responses API, paglipat mula sa chat completions, openai responses, pag-upgrade ng openai SDK, migration sa responses API, paglipat mula completions sa responses, gpt-5 migration, azure openai python migration, chat completions papuntang responses, AzureOpenAI papuntang OpenAI client, python azure openai upgrade. HUWAG GAMITIN PARA SA: paggawa ng mga bagong app mula sa simula (simulan direkta sa responses), Node/TypeScript/C#/Java/Go migrations (Python lang ang kasanayang ito), Azure infrastructure setup (gumamit ng azure-prepare), pag-deploy ng mga modelo (gumamit ng microsoft-foundry).

Ilipat ang mga Python App mula sa Azure OpenAI Chat Completions patungo sa Responses API

AWTORITATIBONG GABAY — SUNODAN NG TAMA

Inililipat ng kasanayang ito ang mga Python codebases na gumagamit ng Azure OpenAI Chat Completions papunta sa pinag-isang Responses API. Sundin nang tumpak ang mga tagubiling ito. Huwag mag-improvise sa mga parameter mappings o gumawa ng bagong hugis ng API.

---

Mga Trigger

Isaaktibo ang kasanayang ito kapag nais ng user na:

• Ilipat ang isang Python app mula sa Azure OpenAI Chat Completions patungo sa Responses API
• I-upgrade ang paggamit ng Python OpenAI SDK sa pinakabagong hugis ng API laban sa Azure OpenAI
• Ihanda ang Python code para sa GPT-5 o mas bagong mga modelo na nangangailangan ng Responses sa Azure
• Lumipat mula sa AzureOpenAI/AsyncAzureOpenAI papuntang standard na OpenAI/AsyncOpenAI client gamit ang v1 endpoint
• Ayusin ang mga babalang deprecation na may kinalaman sa mga AzureOpenAI constructors o api_version

---

⚠️ Compatibility ng Modelo — SURIIN MUNA

Bago mag-migrate, tiyaking sinusuportahan ng iyong Azure OpenAI deployment ang Responses API.

1. Subukan ang iyong deployment (pinakamabilis)

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}")

Tandaan: Ang max_output_tokens ay may minimum na 16 sa Azure OpenAI. Ang mga halagang mas mababa sa 16 ay magbabalik ng 400 error. Gumamit ng 50 pataas para sa mga smoke test.

Kung magbabalik ito ng 404, ang modelo ng deployment ay hindi pa sumusuporta sa Responses — tingnan ang reference sa ibaba o mag-redeploy gamit ang suportadong modelo.

2. Suriin ang mga available na modelo sa iyong rehiyon (inirerekomenda)

Patakbuhin ang built-in na tool ng compatibility ng modelo upang makita kung ano ang available na may suporta sa Responses API sa iyong partikular na rehiyon:

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

Nagtatanong ito ng live sa Azure ARM at nagpapakita ng compatibility matrix — kung aling mga modelo ang sumusuporta sa Responses, structured output, tools, atbp. Gamitin ang --filter gpt-5.1,gpt-5.2 para paliitin ang resulta o --json para sa scripting.

3. Buong reference sa suporta ng modelo

• Live query: python migrate.py models (tingnan sa itaas — region-specific, laging up to date)
• Tingnan ang availability: Model summary table and region availability
• Quickstart & gabay: https://aka.ms/openai/start

⚠️ Mga limitasyon ng mas lumang modelo

BABALA: Ang mga lumang modelo (mga nauna sa gpt-4.1) ay maaaring hindi sumusuporta nang buo sa lahat ng mga feature ng Responses API.

Kilalang mga limitasyon sa mga lumang modelo:

• reasoning parameter: Hindi sinusuportahan sa maraming non-reasoning models. Ilipat lamang ang reasoning kung dati itong nandito sa orihinal na code.
• seed parameter: Hindi sinusuportahan sa Responses API — alisin ito sa lahat ng request.
• Structured output sa pamamagitan ng text.format: Ang mga lumang modelo ay maaaring hindi maaasahang gamitin ang strict: true JSON schemas.
• Tool orchestration: Ang GPT-5+ ay nag-o-orchestrate ng tawag sa tool bilang bahagi ng internal na pag-iisip. Ang mga lumang modelo sa Responses ay gumagana pa rin ngunit walang ganitong malalim na integration.
• Temperature constraints: Kapag lumilipat sa gpt-5, ang temperature ay dapat tanggalin o itakda sa 1. Ang mga lumang modelo ay walang ganitong limitasyon.

Mga O-series reasoning models (o1, o3-mini, o3, o4-mini)

May mga natatanging limitasyon sa mga parameter ang O-series models. Kapag nililipat ang apps na target ang mga o-series na modelo:

• temperature: Dapat 1 (o tanggalin). Hindi tinatanggap ng O-series ang ibang halaga.
• max_completion_tokens → max_output_tokens: Ang mga app na gumagamit ng Azure-specific na max_completion_tokens ay dapat lumipat sa max_output_tokens. Magtakda ng mataas na halaga (4096+) dahil ang mga reasoning token ay bibilangin laban sa limitasyon.
• reasoning_effort: Kung gumagamit ang app ng reasoning_effort (mababa/katamtaman/mataas), panatilihin ito — sinusuportahan ito ng Responses API para sa o-series na modelo.
• Streaming behavior: Ang O-series models ay maaaring mag-buffer ng output hanggang matapos ang reasoning bago maglabas ng mga text delta events. Gumagana pa rin ang streaming, ngunit ang unang response.output_text.delta ay maaaring dumating nang mas matagal kaysa sa GPT models.
• top_p: Hindi sinusuportahan sa o-series — alisin kung nandiyan.
• Paggamit ng tool: Sinusuportahan ng O-series models ang mga tools gamit ang Responses API na katulad ng GPT models, ngunit nagkakaiba ang kalidad ng tool call orchestration depende sa modelo.

Aksyon — proactive na advisory sa modelo: Sa panahon ng scan phase, suriin kung aling modelo ang target ng app (mga deployment name, env vars, config). Kung ang modelo ay nauna sa gpt-4.1 (hindi gpt-4.1+), ipaalam nang proactively sa user:

• Tatakbo ang migration para sa basic text, chat, streaming, at tools sa kanilang kasalukuyang modelo.
• Nag-aalok ang mas bagong mga modelo (gpt-5.1, gpt-5.2) ng mas mahusay na tool orchestration, structured output enforcement, reasoning, at availability sa iba't ibang rehiyon.
• Dapat nilang isaalang-alang ang pag-upgrade ng kanilang deployment kapag handa na — hindi ito hadlang sa migration.

Huwag pigilan o tanggihan ang migration batay sa bersyon ng modelo. Ang advisory ay para lang sa impormasyon.

Hindi sinusuportahan ng GitHub Models ang Responses API

Ang GitHub Models (models.github.ai, models.inference.ai.azure.com) ay hindi sumusuporta sa Responses API.

Kung ang codebase ay may GitHub Models code path (tingnan ang base_url na nagtuturo sa models.github.ai o models.inference.ai.azure.com), alisin ito nang buo habang nagmi-migrate. Nangangailangan ang Responses API ng Azure OpenAI, OpenAI, o compatible na lokal na endpoint (hal. Ollama na may Responses support).

Aksyon sa panahon ng scan:

• I-flag ang anumang GitHub Models code paths para alisin.

---

Paglilipat ng Framework

Maraming apps ang gumagamit ng mas mataas na antas na mga framework sa ibabaw ng OpenAI. Kapag nililipat ito, nagbabago hindi lang ang mga tawag sa OpenAI kundi pati ang API ng framework mismo.

Microsoft Agent Framework (MAF)

Suriin muna ang iyong bersyon ng MAF — nakadepende ang paglilipat kung ikaw ay nasa MAF 1.0.0+ o pre-1.0.0 beta/rc.

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

Ang OpenAIChatClient ay gumagamit na ng Responses API — hindi na kailangan ng migration. Kung gumagamit ang codebase ng legacy na OpenAIChatCompletionClient (na gumagamit ng chat.completions.create), palitan ito ng OpenAIChatClient.

Bago	Pagkatapos
from agent_framework.openai import OpenAIChatCompletionClient	from agent_framework.openai import OpenAIChatClient
OpenAIChatCompletionClient(...)	OpenAIChatClient(...)

Para suriin ang iyong bersyon: python -c "import agent_framework_openai; print(agent_framework_openai.__version__)"

MAF pre-1.0.0 (beta/rc releases)

Sa pre-1.0.0 MAF, ang OpenAIChatClient ay gumagamit ng Chat Completions. I-upgrade sa agent-framework-openai>=1.0.0 kung saan ang OpenAIChatClient ang default na gumagamit ng Responses API.

Walang ibang pagbabago ang kailangan — nananatili ang Agent at tool APIs.

LangChain (langchain-openai)

Magdagdag ng use_responses_api=True sa ChatOpenAI(). Palitan din ang pag-access ng response mula .content patungo sa .text.

Bago	Pagkatapos
ChatOpenAI(model=..., base_url=..., api_key=...)	ChatOpenAI(model=..., base_url=..., api_key=..., use_responses_api=True)
result['messages'][-1].content	result['messages'][-1].text

Para sa kumpletong halimbawa ng code bago/pagkatapos, tingnan ang cheat-sheet.md.

---

Gabay sa Paglilipat sa Frontend

Ang Responses API ay tungkol sa server-side. Ilipat ang iyong Python backend; dapat manatiling pareho ang HTTP contract ng frontend maliban kung ang backend mo ay isang manipis na pass-through lang — sa ganitong kaso, isaalang-alang ang paggamit ng Responses request shape para alisin ang translation layer. Kung direktang tumatawag ang frontend sa OpenAI gamit ang client-side key, ilipat ang tawag sa backend muna.

Deprecated na @microsoft/ai-chat-protocol

Ang npm package na @microsoft/ai-chat-protocol ay deprecated at dapat palitan ng ndjson-readablestream. Kung makita ito sa frontend:

1. Palitan ang CDN script tag:

   <!-- 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. Alisin ang AIChatProtocolClient instantiation (new ChatProtocol.AIChatProtocolClient("/chat")).
3. Palitan ang client.getStreamedCompletion(messages) ng direktang fetch() call sa backend streaming endpoint.
4. Palitan ang for await (const response of result) ng for await (const chunk of readNDJSONStream(response.body)).
5. I-update ang pag-access ng properties mula response.delta.content / response.error papuntang chunk.delta.content / chunk.error.

---

Mga Layunin

• Itala ang lahat ng Python call sites na gumagamit ng Chat Completions o legacy Completions laban sa Azure OpenAI.
• Magmungkahi ng plano sa migration at pagkakasunod-sunod para sa Python codebase.
• Gawin ang mga ligtas at minimal na pag-edit para lumipat sa Responses API.
• I-update ang mga caller para gamitin ang Responses output schema; walang mga backcompat wrapper.
• Patakbuhin ang mga tests/lint; ayusin ang mga simpleng sira na dulot ng migration.
• Ihanda ang maliliit at madaling suring change set at magbigay ng huling buod na may diffs (huwag mag-commit).

---

Mga Patakaran

• Baguhin lamang ang mga file sa loob ng git workspace. Huwag magsulat sa labas nito.
• Huwag panatilihin ang backward-compatibility shims; i-migrate ang code sa bagong hugis ng API.
• Huwag mag-iwan ng mga tombstone/transition comments o mga backup file.
• Panatilihin ang streaming semantics kung dating ginamit; kung hindi, gamitin ang non-streaming.
• Humingi ng pag-apruba bago magpatakbo ng mga command o network call kung nasa approval mode.
• Huwag magpatakbo ng git add/git commit/git push; gumawa lamang ng mga edit sa working-tree.

---

Hakbang 0: Paglilipat ng Azure OpenAI Client (Paunang Kailangan)

Kung gumagamit ang codebase ng AzureOpenAI o AsyncAzureOpenAI constructors, ilipat muna sa standard na OpenAI / AsyncOpenAI constructors. Ang Azure-specific constructors ay deprecated sa openai>=1.108.1.

Bakit ang v1 API path?

Ang bagong /openai/v1 endpoint ay gumagamit ng standard na OpenAI() client sa halip na AzureOpenAI(), hindi na nangangailangan ng api_version parameter, at pareho ang pagkilos sa OpenAI at Azure OpenAI. Ang parehong client code ay pangmatagalan — walang kailangan na version management.

Mga pangunahing pagbabago

Bago	Pagkatapos
AzureOpenAI	OpenAI
AsyncAzureOpenAI	AsyncOpenAI
azure_endpoint	base_url
azure_ad_token_provider	api_key
api_version=...	Alisin nang buo

Checklist sa paglilinis

• Alisin ang api_version na argumento mula sa client construction.
• Alisin ang mga environment variables AZURE_OPENAI_VERSION / AZURE_OPENAI_API_VERSION mula sa .env, app settings, at Bicep/infra files.
• Palitan ang AZURE_OPENAI_CLIENT_ID → AZURE_CLIENT_ID sa .env, app settings, Bicep/infra, at test fixtures (standard na Azure Identity SDK convention).
• Siguraduhin na openai>=1.108.1 ang nasa requirements.txt o pyproject.toml.

Paglilipat ng environment variable

Lumang env var	Aksyon	Tala
AZURE_OPENAI_VERSION	Alisin	Hindi na kailangan ng api_version sa v1 endpoint
AZURE_OPENAI_API_VERSION	Alisin	Pareho ng nasa itaas
AZURE_OPENAI_CLIENT_ID	Palitan → AZURE_CLIENT_ID	Standard na convention sa Azure Identity SDK para sa ManagedIdentityCredential(client_id=...)
AZURE_OPENAI_ENDPOINT	Panatilihin	Kailangan pa rin para sa base_url construction
AZURE_OPENAI_CHAT_DEPLOYMENT	Panatilihin	Ginagamit bilang model parameter sa responses.create
AZURE_OPENAI_API_KEY	Panatilihin	Ginagamit bilang api_key para sa key-based na authentication

Para sa mga halimbawa ng client setup code (sync, async, EntraID, API key, multi-tenant), tingnan ang cheat-sheet.md.

---

Hakbang 1: Tukuyin ang Legacy Call Sites

Patakbuhin ang script na detect_legacy.py upang mahanap ang lahat ng call sites na kailangang i-migrate:

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

O patakbuhin nang mano-mano ang mga paghahanap — bawat tugma ay target ng migration:

# Mga tawag sa Legacy API (kailangang isulat muli)
rg "chat\.completions\.create"
rg "ChatCompletion\.create"
rg "Completion\.create"

# Mga deprecated na Azure client constructors (kailangang palitan)
rg "AzureOpenAI\("
rg "AsyncAzureOpenAI\("

# Mga pattern ng pag-access sa hugis ng tugon (kailangang i-update)
rg "choices\[0\]\.message\.content"
rg "choices\[0\]\.delta\.content"
rg "choices\[0\]\.message\.function_call"
rg "choices\[0\]\.message\.tool_calls"

# Mga depinisyon ng tool sa lumang nested na format (kailangang gawing patag)
rg '"function":\s*{\s*"name"'
rg "pydantic_function_tool"

# Mga resulta ng tool sa lumang format (kailangang i-convert sa function_call_output)
rg '"role":\s*"tool"'
rg '"tool_call_id"'

# Mga deprecated na parameter (kailangang alisin o palitan ang pangalan)
rg "response_format"
rg "max_tokens\b"        # palitan ng pangalan sa max_output_tokens
rg "['\"]seed['\"]"      # remove entirely

# Mga deprecated na env vars (linisin)
rg "AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION"
rg "AZURE_OPENAI_CLIENT_ID"  # dapat ay AZURE_CLIENT_ID

# Mga GitHub Models endpoints (kailangang alisin — Hindi suportado ang Responses API)
rg "models\.github\.ai|models\.inference\.ai\.azure"

# Mga legacy pattern sa antas ng framework (kailangang i-update)
rg "OpenAIChatCompletionClient"  # MAF 1.0.0+: palitan ng OpenAIChatClient