azure-openai-to-responses

# 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) ```python 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: ```bash 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](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/models-sold-directly-by-azure?tabs=global-standard-aoai%2Cglobal-standard&pivots=azure-openai#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](./references/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`](https://www.npmjs.com/package/ndjson-readablestream). Kung makita ito sa frontend: 1. Palitan ang CDN script tag: ```html <!-- 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](./references/cheat-sheet.md). --- ## Hakbang 1: Tukuyin ang Legacy Call Sites Patakbuhin ang script na [detect_legacy.py](../../../../../.agents/skills/azure-openai-to-responses/scripts/detect_legacy.py) upang mahanap ang lahat ng call sites na kailangang i-migrate: ```bash python skills/azure-openai-to-responses/scripts/detect_legacy.py . ``` O patakbuhin nang mano-mano ang mga paghahanap — bawat tugma ay target ng migration: ```bash # 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