[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699A23AF3V4AVR5GTK4GPHX":3,"skill-same:01M699A23AF3V4AVR5GTK4GPHX":62},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M699A23AF3V4AVR5GTK4GPHX","azure-openai-to-responses",null,"microsoft\u002Fai-agents-for-beginners","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M6998ZK2275KMJE6Y5SEA2X2",79423,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002FSKILL.md",[],[18],"azure openai to responses","2026-11-10 10:12:30",false,"---\nname: azure-openai-to-responses\nlicense: MIT\n---\n# Мигриране на Python приложения от Azure OpenAI Chat Completions към Responses API\n\n> **АВТОРИТЕТНО РЪКОВОДСТВО — СПАЗВАЙТЕ ТОЧНО**\n>\n> Тази функция мигрира Python кодови бази, използващи Azure OpenAI Chat Completions\n> към унифицирания Responses API. Следвайте тези инструкции прецизно.\n> Не импровизирайте с параметрични съпоставяния или измисляйте форми на API.\n\n---\n\n## Тригери\n\nАктивирайте тази функция, когато потребителят иска да:\n- Мигрира Python приложение от Azure OpenAI Chat Completions към Responses API\n- Обнови употребата на Python OpenAI SDK до последната форма на API спрямо Azure OpenAI\n- Подготви Python код за модели GPT-5 или по-нови, които изискват Responses на Azure\n- Превключи от `AzureOpenAI`\u002F`AsyncAzureOpenAI` към стандартния `OpenAI`\u002F`AsyncOpenAI` клиент с v1 endpoint\n- Поправи предупреждения за оттегляне, свързани с конструкторите на `AzureOpenAI` или `api_version`\n\n---\n\n## ⚠️ Съвместимост на моделите — ПРОВЕРЕТЕ ПЪРВО\n\n> **Преди миграцията, уверете се, че вашето разгръщане на Azure OpenAI поддържа Responses API.**\n\n### 1. Бърз тест на разгръщането (най-бърз)\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"AZURE_OPENAI_API_KEY\"],\n    base_url=f\"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('\u002F')}\u002Fopenai\u002Fv1\u002F\",\n)\n\ntry:\n    resp = client.responses.create(\n        model=os.environ[\"AZURE_OPENAI_DEPLOYMENT\"],\n        input=\"ping\",\n        max_output_tokens=50,\n        store=False,\n    )\n    print(f\"✅ Deployment supports Responses API: {resp.output_text}\")\nexcept Exception as e:\n    print(f\"❌ Deployment does NOT support Responses API: {e}\")\n```\n\n> **Бележка**: `max_output_tokens` има **минимум 16** в Azure OpenAI. Стойности под 16 връщат грешка 400. Използвайте 50+ за бързи тестове.\n\nАко това връща 404, моделът на разгръщането все още не поддържа Responses — проверете референцията по-долу или преинсталирайте с поддържан модел.\n\n### 2. Проверете наличните модели във вашия регион (препоръчително)\n\nСтартирайте вградения инструмент за съвместимост на модели, за да видите какво е налично с поддръжка на Responses API във вашия конкретен регион:\n\n```bash\npython migrate.py models --subscription YOUR_SUB_ID --location YOUR_REGION\n```\n\nТова заявява директно към Azure ARM и показва матрица на съвместимост — кои модели поддържат Responses, структурирани изходи, инструменти и др. Използвайте `--filter gpt-5.1,gpt-5.2` за филтриране или `--json` за скриптиране.\n\n### 3. Пълна референция за поддръжка на модели\n\n- **Живо запитване**: `python migrate.py models` (вижте по-горе — специфично за регион, винаги актуално)\n- **Преглед на наличности**: [Таблица с обобщение на модели и регионална наличност](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Ffoundry\u002Ffoundry-models\u002Fconcepts\u002Fmodels-sold-directly-by-azure?tabs=global-standard-aoai%2Cglobal-standard&pivots=azure-openai#model-summary-table-and-region-availability)\n- **Бърз старт и ръководство**: **https:\u002F\u002Faka.ms\u002Fopenai\u002Fstart**\n\n### ⚠️ Ограничения на по-старите модели\n\n> **ВНИМАНИЕ**: По-старите модели (тези преди `gpt-4.1`) може да не поддържат всички функции на Responses API пълноценно.\n>\n> Известни ограничения с по-старите модели:\n> - **Параметър `reasoning`**: Не се поддържа при много модели без reasoning. Мигрирайте `reasoning` само ако вече присъства в оригиналния код.\n> - **Параметър `seed`**: Не се поддържа изобщо в Responses API — премахнете го от всички заявки.\n> - **Структуриран изход чрез `text.format`**: При по-старите модели `strict: true` JSON схеми може да не се налагат надеждно.\n> - **Оркестрация на инструменти**: GPT-5+ обработва извиквания на инструменти като част от вътрешния reasoning. По-старите модели на Responses работят, но им липсва тази дълбока интеграция.\n> - **Ограничения на температурата**: При мигриране към `gpt-5`, температурата трябва да се пропусне или зададе на `1`. По-старите модели нямат такова ограничение.\n\n### O-серия reasoning модели (o1, o3-mini, o3, o4-mini)\n\nМоделите от серия O имат уникални параметрични ограничения. При мигриране на приложения, които целят тези модели:\n\n- **`temperature`**: Трябва да бъде `1` (или пропуснат). O-серия моделите не приемат други стойности.\n- **`max_completion_tokens` → `max_output_tokens`**: Приложения, използващи Azure-специфичния `max_completion_tokens`, трябва да преминат към `max_output_tokens`. Задайте високи стойности (4096+) тъй като токените за reasoning се броят към лимита.\n- **`reasoning_effort`**: Ако приложението използва `reasoning_effort` (ниско\u002Fсредно\u002Fвисоко), запазете това — Responses API поддържа този параметър за o-серия модели.\n- **Поведение на стрийминг**: O-серия моделите може да буферират изхода до приключване на reasoning преди да изпратят събития с текстови дялове. Стриймингът все още работи, но първият `response.output_text.delta` може да пристигне с по-голямо изчакване спрямо GPT моделите.\n- **`top_p`**: Не се поддържа на o-серия — премахнете го, ако е наличен.\n- **Употреба на инструменти**: O-серия моделите поддържат инструменти чрез Responses API както GPT моделите, но качеството на оркестрация на извикванията варира по модели.\n\n**Действие — проактивна информационна препоръка**: По време на сканиране проверявайте към кой модел таргетира приложението (имена на разгръщания, системни променливи, конфигурация). Ако моделът е преди `gpt-4.1` (не е gpt-4.1+), проактивно уведомете потребителя:\n- Миграцията ще работи за базов текст, чат, стрийминг и инструменти на текущия му модел.\n- По-новите модели (`gpt-5.1`, `gpt-5.2`) предлагат по-добра оркестрация на инструменти, прилагане на структурирани изходи, reasoning и крос-регионална наличност.\n- Те трябва да обмислят ъпгрейд на разгръщането си когато са готови — това не блокира миграцията.\n\nНе блокирайте или отказвайте миграция според версията на модела. Информацията е само препоръчителна.\n\n### GitHub моделите НЕ поддържат Responses API\n\n> **GitHub моделите (`models.github.ai`, `models.inference.ai.azure.com`) не поддържат Responses API.**\n\nАко кодовата база съдържа път за GitHub модели (потърсете `base_url`, сочещ към `models.github.ai` или `models.inference.ai.azure.com`), **премахнете го изцяло** при миграцията. Responses API изисква Azure OpenAI, OpenAI, или съвместим локален endpoint (например Ollama с Responses поддръжка).\n\nДействия по време на сканиране:\n- Отбележете всеки кодов път с GitHub модели за премахване.\n\n---\n\n## Миграция на рамката (Framework)\n\nМного приложения използват по-високо ниво рамки върху OpenAI. При миграция на тези, промените са в самия API на рамката — не само основните OpenAI извиквания.\n\n### Microsoft Agent Framework (MAF)\n\n**Проверете първо версията на MAF** — миграцията зависи дали сте на MAF 1.0.0+ или на пред-1.0.0 бета\u002Frc.\n\n#### MAF 1.0.0+ (agent-framework-openai >= 1.0.0)\n\n`OpenAIChatClient` **вече използва Responses API** — няма нужда от миграция. Ако кодовата база използва остарялото `OpenAIChatCompletionClient` (който ползва `chat.completions.create`), заменете го с `OpenAIChatClient`.\n\n| Преди | След |\n|--------|-------|\n| `from agent_framework.openai import OpenAIChatCompletionClient` | `from agent_framework.openai import OpenAIChatClient` |\n| `OpenAIChatCompletionClient(...)` | `OpenAIChatClient(...)` |\n\nЗа да проверите версията: `python -c \"import agent_framework_openai; print(agent_framework_openai.__version__)\"`\n\n#### MAF преди 1.0.0 (бета\u002Frc версии)\n\nВ пред-1.0.0 MAF, `OpenAIChatClient` използва Chat Completions. Ъпгрейднете до `agent-framework-openai>=1.0.0`, където `OpenAIChatClient` по подразбиране използва Responses API.\n\nДруги промени не са необходими — `Agent` и инструменталните API остават същите.\n\n### LangChain (`langchain-openai`)\n\nДобавете `use_responses_api=True` на `ChatOpenAI()`. Също така обновете достъпа до отговорите от `.content` към `.text`.\n\n| Преди | След |\n|--------|-------|\n| `ChatOpenAI(model=..., base_url=..., api_key=...)` | `ChatOpenAI(model=..., base_url=..., api_key=..., use_responses_api=True)` |\n| `result['messages'][-1].content` | `result['messages'][-1].text` |\n\nЗа пълни пример кодове преди\u002Fслед, вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\n---\n\n## Ръководство за миграция на фронтенд\n\n> **Responses API е грижа на сървърната страна.** Мигрирайте backend на Python; HTTP контракта на фронтенда трябва да остане непроменен, освен ако backend не е тънък пропускателен слой — в такъв случай обмислете да приемете формата на Responses заявки, за да елиминирате слой превод. Ако фронтенд извиква OpenAI директно с ключ на клиентската страна, преместете тези извиквания първо в backend.\n\n### Оттегляне на `@microsoft\u002Fai-chat-protocol`\n\nПакетът npm `@microsoft\u002Fai-chat-protocol` е оттеглен и трябва да бъде заменен с [`ndjson-readablestream`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fndjson-readablestream). Ако го срещнете във фронтенд:\n\n1. Заменете CDN скрипт тага:\n   ```html\n   \u003C!-- Before -->\n   \u003Cscript src=\"https:\u002F\u002Fcdn.jsdelivr.net\u002Fnpm\u002F@microsoft\u002Fai-chat-protocol@...\u002Fdist\u002Fiife\u002Findex.js\">\u003C\u002Fscript>\n   \u003C!-- After -->\n   \u003Cscript src=\"https:\u002F\u002Fcdn.jsdelivr.net\u002Fnpm\u002Fndjson-readablestream@1.0.7\u002Fdist\u002Fndjson-readablestream.umd.js\">\u003C\u002Fscript>\n   ```\n2. Премахнете инстанцията `AIChatProtocolClient` (`new ChatProtocol.AIChatProtocolClient(\"\u002Fchat\")`).\n3. Заменете `client.getStreamedCompletion(messages)` с директно `fetch()` извикване към backend стрийминг endpoint.\n4. Заменете `for await (const response of result)` с `for await (const chunk of readNDJSONStream(response.body))`.\n5. Обновете достъпа до свойства от `response.delta.content` \u002F `response.error` към `chunk.delta.content` \u002F `chunk.error`.\n\n---\n\n## Цели\n\n- Изброяване на всички Python извиквания, използващи Chat Completions или остарели Completions срещу Azure OpenAI.\n- Предложете план и последователност за миграция на Python кодовата база.\n- Прилагане на сигурни, минимални редакции за превключване към Responses API.\n- Актуализиране на извикващите, за да консумират схемата за изход на Responses; няма нужда от обвивни backward-compatibility решения.\n- Изпълнете тестове\u002Fлинт проверки; поправете дребни счупвания, въведени при миграцията.\n- Подгответе малки, лесно рецензируеми набори промени и предоставете финално резюме с дифове (не комитвайте).\n\n---\n\n## Граници\n\n- Променяйте само файлове в git workspace. Никога не пишете извън него.\n- Не запазвайте backward-compatibility шими; мигрирайте кода към новата форма на API.\n- Не оставяйте преходни коментари или резервни копия на файлове.\n- Запазвайте семантиката на стрийминг ако преди сте я използвали; иначе използвайте не-стрийминг.\n- Поискайте одобрение преди изпълнение на команди или мрежови извиквания, ако сте в режим на одобрение.\n- Не изпълнявайте `git add`\u002F`git commit`\u002F`git push`; правете само редакции на работното дърво.\n\n---\n\n## Стъпка 0: Миграция на Azure OpenAI клиент (предварително условие)\n\nАко кодовата база използва конструктори `AzureOpenAI` или `AsyncAzureOpenAI`, първо мигрирайте към стандартните конструктори `OpenAI` \u002F `AsyncOpenAI`. Специфичните конструктори за Azure са оттеглени в `openai>=1.108.1`.\n\n### Защо API пътя v1?\n\nНовият endpoint `\u002Fopenai\u002Fv1` използва стандартния клиент `OpenAI()` вместо `AzureOpenAI()`, не изисква параметър `api_version` и работи еднакво както с OpenAI, така и с Azure OpenAI. Същият клиент код е бъдещо устойчива — няма нужда от управление на версии.\n\n### Основни промени\n\n| Преди | След |\n|--------|-------|\n| `AzureOpenAI` | `OpenAI` |\n| `AsyncAzureOpenAI` | `AsyncOpenAI` |\n| `azure_endpoint` | `base_url` |\n| `azure_ad_token_provider` | `api_key` |\n| `api_version=...` | Премахнете напълно |\n\n### Контролен списък за почистване\n\n- Премахнете аргумента `api_version` от конструктора на клиента.\n- Премахнете променливите на средата `AZURE_OPENAI_VERSION` \u002F `AZURE_OPENAI_API_VERSION` от `.env`, настройки на приложение и Bicep\u002Finfra файлове.\n- Преименувайте `AZURE_OPENAI_CLIENT_ID` → `AZURE_CLIENT_ID` в `.env`, настройки на приложение, Bicep\u002Finfra и тестови фикстури (стандартна конвенция на Azure Identity SDK).\n- Уверете се, че `openai>=1.108.1` е в `requirements.txt` или `pyproject.toml`.\n\n### Миграция на променливи на средата\n\n| Стара променлива | Действие | Забележки |\n|-------------|--------|-------|\n| `AZURE_OPENAI_VERSION` | **Премахнете** | Не е нужна `api_version` с v1 endpoint |\n| `AZURE_OPENAI_API_VERSION` | **Премахнете** | Същото като по-горе |\n| `AZURE_OPENAI_CLIENT_ID` | **Преименувайте** → `AZURE_CLIENT_ID` | Стандартна конвенция на Azure Identity SDK за `ManagedIdentityCredential(client_id=...)` |\n| `AZURE_OPENAI_ENDPOINT` | **Запазете** | Все още се използва за конструкция на `base_url` |\n| `AZURE_OPENAI_CHAT_DEPLOYMENT` | **Запазете** | Използва се като параметър `model` в `responses.create` |\n| `AZURE_OPENAI_API_KEY` | **Запазете** | Използва се като `api_key` за автентикация с ключ |\n\nЗа примери за настройка на клиент (синхронен, асинхронен, EntraID, API ключ, мулти-клиентски), вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\n---\n\n## Стъпка 1: Откриване на остарели извиквания\n\nСтартирайте скрипта [detect_legacy.py](..\u002F..\u002F..\u002F..\u002F..\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py) за намиране на всички извиквания, които трябва да бъдат мигрирани:\n\n```bash\npython skills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py .\n```\n\nИли изпълнете тези търсения ръчно — всяко съвпадение е цел за миграция:\n\n```bash\n# Обаждания към остарял API (трябва преписване)\nrg \"chat\\.completions\\.create\"\nrg \"ChatCompletion\\.create\"\nrg \"Completion\\.create\"\n\n# Остарели конструктори на Azure клиент (трябва замяна)\nrg \"AzureOpenAI\\(\"\nrg \"AsyncAzureOpenAI\\(\"\n\n# Модели за достъп до формата на отговорите (трябва обновяване)\nrg \"choices\\[0\\]\\.message\\.content\"\nrg \"choices\\[0\\]\\.delta\\.content\"\nrg \"choices\\[0\\]\\.message\\.function_call\"\nrg \"choices\\[0\\]\\.message\\.tool_calls\"\n\n# Определения на инструменти в стар вложен формат (трябва изглаждане)\nrg '\"function\":\\s*{\\s*\"name\"'\nrg \"pydantic_function_tool\"\n\n# Резултати от инструменти в стар формат (трябва конвертиране във function_call_output)\nrg '\"role\":\\s*\"tool\"'\nrg '\"tool_call_id\"'\n\n# Остарели параметри (трябва премахване или преименуване)\nrg \"response_format\"\nrg \"max_tokens\\b\"        # преименувай на max_output_tokens\nrg \"['\\\"]seed['\\\"]\"      # remove entirely\n\n# Остарели променливи на средата (почистване)\nrg \"AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION\"\nrg \"AZURE_OPENAI_CLIENT_ID\"  # трябва да е AZURE_CLIENT_ID\n\n# Крайни точки на GitHub Models (трябва премахване — Responses API не се поддържа)\nrg \"models\\.github\\.ai|models\\.inference\\.ai\\.azure\"\n\n# Наследствени модели на ниво фреймуърк (трябва обновяване)\nrg \"OpenAIChatCompletionClient\"  # MAF 1.0.0+: замени с OpenAIChatClient\nrg \"ChatOpenAI\\(\" | grep -v \"use_responses_api\"  # LangChain: изисква use_responses_api=True\n\n# Тестова инфраструктура (трябва обновяване)\nrg \"ChatCompletionChunk|AsyncCompletions\\.create\" tests\u002F\nrg \"_azure_ad_token_provider\" tests\u002F\nrg \"prompt_filter_results|content_filter_results\" tests\u002F\nrg \"choices\\[0\\]\" tests\u002F\n\n# Достъп до тялото на грешката при филтър за съдържание (трябва обновяване — структурата се е променила)\nrg 'innererror.*content_filter_result|error\\.body\\[\"innererror\"\\]'\nrg \"content_filter_result\\[\" # старо единствено число — сега content_filter_results (множествено) вътре в масива content_filters\n\n# Сурови HTTP повиквания към крайна точка Chat Completions (трябва обновяване на URL)\nrg \"\u002Fopenai\u002Fdeployments\u002F.*\u002Fchat\u002Fcompletions\"\nrg \"api-version=\"\n```\n\n### Евристики (откриване и преписване)\n\n- **Chat Completions клиент**: `client.chat.completions.create` → `client.responses.create(...)`.\n\n- **Конструктори на Azure клиент**: `AzureOpenAI(...)` → `OpenAI(base_url=..., api_key=...)`.\n- **Инструменти**: конвертирайте дефинициите на инструментите за извикване на функции от вложен формат (`{\"type\": \"function\", \"function\": {\"name\": ...}}`) във формат на Responses (`{\"type\": \"function\", \"name\": ...}`); използвайте `tool_choice`; връщайте резултатите от инструмента като елементи `{\"type\": \"function_call_output\", \"call_id\": ..., \"output\": ...}` (не като `{\"role\": \"tool\", ...}`).\n- **Обратни трансформации на инструментите**: когато моделът връща извиквания на функции, добавяйте елементите `response.output` към разговора (не ръчно речник `{\"role\": \"assistant\", \"tool_calls\": [...]}`), след което добавяйте елементите `function_call_output` за всеки резултат.\n- **Примери с малък брой удари за инструменти**: ако в разговора има твърдо кодирани примери за извикване на инструменти, конвертирайте ги в елементи `{\"type\": \"function_call\", \"id\": \"fc_...\", \"call_id\": \"fc_...\", ...}` + `{\"type\": \"function_call_output\", ...}`. Идентификаторите трябва да започват с `fc_`.\n- **`pydantic_function_tool()`**: този помощник все още генерира стария вложен формат и **не е съвместим** с `responses.create()`. Заменете с ръчно дефинирани инструменти или обвивка за изравняване.\n- **Многостъпков режим**: поддържайте история на разговора в приложението; предавайте предишни ходове чрез елементи `input`.\n- **Форматиране**: заменете главното ниво `response_format` на Chat с `text.format` в Responses. Канонична форма: `text={\"format\": {\"type\": \"json_schema\", \"name\": \"Output\", \"strict\": True, \"schema\": {...}}}`.\n- **Елементи съдържание**: заменете `content[].type: \"text\"` в Chat с `content[].type: \"input_text\"` в Responses за ходове на потребител\u002Fсистема.\n- **Елементи съдържание с изображения**: заменете `content[].type: \"image_url\"` в Chat с `content[].type: \"input_image\"` в Responses. Полето `image_url` се променя от вложен обект `{\"url\": \"...\"}` на плосък низ. Вижте листа с препоръки за примери преди\u002Fслед.\n- **Усилие за логическо обяснение**: **мигрирайте `reasoning` само ако вече съществува в оригиналния код**.\n- **Обработка на грешки от филтъра на съдържание**: структурата на тялото на грешката се промени. Chat Completions използваше `error.body[\"innererror\"][\"content_filter_result\"]` (в единствено число); Responses API използва `error.body[\"content_filters\"][0][\"content_filter_results\"]` (в множествено число вътре в масив). Код, който достъпва `innererror`, ще вдигне `KeyError`. Пренапишете, за да използвате новия път.\n- **Сурови HTTP повиквания**: ако приложението директно извиква Azure OpenAI REST API (чрез `requests`, `httpx` и др.) с `\u002Fopenai\u002Fdeployments\u002F{name}\u002Fchat\u002Fcompletions?api-version=...`, пренапишете към `\u002Fopenai\u002Fv1\u002Fresponses`. Тялото на заявката се променя: `messages` → `input`, добавя се `max_output_tokens` и `store: false`, премахва се заявният параметър `api-version`. Тялото на отговора се променя: `choices[0].message.content` → `output[0].content[0].text` (забележка: `output_text` е удобство в SDK, което липсва в суровия REST JSON).\n\n---\n\n## Стъпка 2: Приложете миграцията\n\n### Бележки по миграцията (Chat Completions → Responses)\n\n- **Защо да мигрираме**: Responses е унифицирано API за текст, инструменти и стрийминг; Chat Completions е наследен. С GPT-5 Responses се изисква за най-добра производителност.\n- **HTTP**: Azure ендпойнт преминава от `\u002Fopenai\u002Fdeployments\u002F{name}\u002Fchat\u002Fcompletions` към `\u002Fopenai\u002Fv1\u002Fresponses`.\n- **Полетата**: `messages` → `input`, `max_tokens` → `max_output_tokens`. `temperature` остава.\n- **Форматиране**: `response_format` → `text.format` с правилен обект.\n- **Елементи съдържание**: Заменете `content[].type: \"text\"` в Chat с `content[].type: \"input_text\"` в Responses за системни и потребителски ходове.\n- **Елементи съдържание с изображения**: Заменете `content[].type: \"image_url\"` в Chat с `content[].type: \"input_image\"` в Responses. Изравнете полето `image_url` от `{\"image_url\": {\"url\": \"...\"}}` в `{\"image_url\": \"...\"}` (обикновен низ — HTTPS URL или data URI от тип `data:image\u002F...;base64,...`).\n\n### Справка със съпоставяне на параметри\n\n| Chat Completions | Responses API |\n|-----------------|---------------|\n| `prompt` | `input` |\n| `messages` | `input` (масив от елементи) |\n| `max_tokens` | `max_output_tokens` |\n| `response_format` | `text.format` (обект) |\n| `temperature` | `temperature` (непроменено) |\n| `stop` | `stop` (непроменено) |\n| `frequency_penalty` | `frequency_penalty` (непроменено) |\n| `presence_penalty` | `presence_penalty` (непроменено) |\n| `tools` \u002F извикване на функции | `tools` (непроменено) |\n| `seed` | **Премахнете** (не се поддържа) |\n| `store` | `store` (зададено на `false`) |\n| `content[].type: \"text\"` | `content[].type: \"input_text\"` |\n| `content[].type: \"image_url\"` | `content[].type: \"input_image\"` |\n| `\"image_url\": {\"url\": \"...\"}` | `\"image_url\": \"...\"` (плосък низ) |\n\nЗа пълни примери с код преди и след, вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\nЗа миграция на тестова инфраструктура (мокове, снимки, проверки), вижте [test-migration.md](.\u002Freferences\u002Ftest-migration.md).\n\nЗа отстраняване на грешки и често срещани проблеми, вижте [troubleshooting.md](.\u002Freferences\u002Ftroubleshooting.md).\n\n---\n\n## Съхранение на данни и състояние\n\n- Задайте `store: false` на всички заявки към Responses.\n- Не се доверявайте на предишни идентификатори на съобщения или контекст, съхраняван на сървъра; управлявайте състоянието от клиента и минимизирайте метаданните.\n\n---\n\n## Критерии за приемане\n\n### Кодови проверки (всички трябва да преминат)\n\n- [ ] Нулев брой съвпадения за `rg \"chat\\.completions\\.create|ChatCompletion\\.create|Completion\\.create\"` в мигрираните файлове.\n- [ ] Нулев брой съвпадения за `rg \"AzureOpenAI\\(|AsyncAzureOpenAI\\(\"` — всички конструктори използват `OpenAI`\u002F`AsyncOpenAI` с v1 ендпойнт.\n- [ ] Нулев брой съвпадения за `rg \"models\\.github\\.ai|models\\.inference\\.ai\\.azure\"` — премахнати са пътища в кода за модели на GitHub.\n- [ ] Нулев брой съвпадения за `rg \"OpenAIChatCompletionClient\"` — кодът от MAF 1.0.0+ използва `OpenAIChatClient` (който използва Responses API). В преди 1.0.0 ъпгрейднете до `agent-framework-openai>=1.0.0`.\n- [ ] Всички повиквания `ChatOpenAI(...)` включват `use_responses_api=True`.\n- [ ] Нулев брой съвпадения за `rg \"choices\\[0\\]\"` — целият достъп до отговори използва `resp.output_text` или схемата за отговори на Responses.\n- [ ] Няма `response_format` на главно ниво; цялата структурирана продукция използва `text={\"format\": {...}}`.\n- [ ] `openai>=1.108.1` и `azure-identity` в `requirements.txt` или `pyproject.toml`; зависимости преинсталирани.\n- [ ] `store=False` зададено във всяко извикване на `responses.create`.\n- [ ] Няма `api_version` в конструкцията на клиента; `AZURE_OPENAI_API_VERSION` премахнат от файловете с околна среда и инфраструктурата.\n\n### Тестови инфраструктурни проверки (всички трябва да преминат)\n\n- [ ] Нулев брой съвпадения за `rg \"ChatCompletionChunk|AsyncCompletions\\.create|chat\\.completions\" tests\u002F`.\n- [ ] Нулев брой съвпадения за `rg \"_azure_ad_token_provider\" tests\u002F` — проверки актуализирани да проверяват `isinstance(client, AsyncOpenAI)` или `base_url`.\n- [ ] Нулев брой съвпадения за `rg \"prompt_filter_results|content_filter_results\" tests\u002F` — премахнати са мокове, специфични за Azure филтри.\n- [ ] Моковете използват `kwargs.get(\"input\")`, не `kwargs.get(\"messages\")`.\n- [ ] Файловете със снимки \u002F златни файлове са актуализирани към формата на Responses за стрийминг (няма `choices[0]`, `function_call`, `logprobs` и т.н.).\n- [ ] `pytest` минава без грешки след всички тестови актуализации.\n\n### Поведенчески проверки (проверяват се ръчно или с тестови инструменти)\n\n- [ ] **Основно завършване**: нестрийминг `responses.create` връща непразен `output_text`.\n- [ ] **Паритет на стрийминг**: ако оригиналният код използваше стрийминг, мигрираният код стриймва и излъчва събития `response.output_text.delta` с непразни делти.\n- [ ] **Структуриран изход**: ако се използва `text.format` с `json_schema`, `json.loads(resp.output_text)` е успешна и съвпада със схемата.\n- [ ] **Цикъл за извикване на инструменти**: ако се използват инструменти, моделът издава извиквания на инструменти, приложението ги изпълнява, а следващата заявка връща финален `output_text` (няма безкраен цикъл).\n- [ ] **Паритет на асинхронност**: ако е използван `AsyncAzureOpenAI`, равностойният `AsyncOpenAI` работи с `await`.\n- [ ] **Ниво на грешки**: няма нови грешки 400\u002F401\u002F404 в сравнение с базовата линия преди миграцията.\n\n### Доставки\n\n- Резюмето включва редактирани файлове, брой повиквания на наследен код преди\u002Fслед и следващи стъпки.\n- Промените са само като редакции в работното дърво (без комити).\n\n---\n\n## Изисквания за версия на SDK\n\n| Пакет | Минимална версия |\n|---------|----------------|\n| `openai` | `>=1.108.1` |\n| `azure-identity` | Най-нова (за EntraID автентикация) |\n\n---\n\n## Препратки\n\n- [Cheat Sheet — всички кодови фрагменти](.\u002Freferences\u002Fcheat-sheet.md)\n- [Test Migration — мокове, снимки, проверки](.\u002Freferences\u002Ftest-migration.md)\n- [Troubleshooting — грешки, таблица с рискове, често срещани проблеми](.\u002Freferences\u002Ftroubleshooting.md)\n- [detect_legacy.py — автоматизиран скенер](..\u002F..\u002F..\u002F..\u002F..\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py)\n- [Azure OpenAI Starter Kit](https:\u002F\u002Faka.ms\u002Fopenai\u002Fstart)\n- [Azure OpenAI Responses API docs](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-foundry\u002Fopenai\u002Fhow-to\u002Fresponses)\n- [Azure OpenAI API version lifecycle](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-foundry\u002Fopenai\u002Fapi-version-lifecycle?view=foundry-classic&tabs=python#api-evolution)\n- [OpenAI Responses API reference](https:\u002F\u002Fplatform.openai.com\u002Fdocs\u002Fapi-reference\u002Fresponses)\n\n---\n\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**Отказ от отговорност**:\nТози документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https:\u002F\u002Fgithub.com\u002FAzure\u002Fco-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER END -->","# Мигриране на Python приложения от Azure OpenAI Chat Completions към Responses API\n\n> **АВТОРИТЕТНО РЪКОВОДСТВО — СПАЗВАЙТЕ ТОЧНО**\n>\n> Тази функция мигрира Python кодови бази, използващи Azure OpenAI Chat Completions\n> към унифицирания Responses API. Следвайте тези инструкции прецизно.\n> Не импровизирайте с параметрични съпоставяния или измисляйте форми на API.\n\n---\n\n## Тригери\n\nАктивирайте тази функция, когато потребителят иска да:\n- Мигрира Python приложение от Azure OpenAI Chat Completions към Responses API\n- Обнови употребата на Python OpenAI SDK до последната форма на API спрямо Azure OpenAI\n- Подготви Python код за модели GPT-5 или по-нови, които изискват Responses на Azure\n- Превключи от `AzureOpenAI`\u002F`AsyncAzureOpenAI` към стандартния `OpenAI`\u002F`AsyncOpenAI` клиент с v1 endpoint\n- Поправи предупреждения за оттегляне, свързани с конструкторите на `AzureOpenAI` или `api_version`\n\n---\n\n## ⚠️ Съвместимост на моделите — ПРОВЕРЕТЕ ПЪРВО\n\n> **Преди миграцията, уверете се, че вашето разгръщане на Azure OpenAI поддържа Responses API.**\n\n### 1. Бърз тест на разгръщането (най-бърз)\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=os.environ[\"AZURE_OPENAI_API_KEY\"],\n    base_url=f\"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('\u002F')}\u002Fopenai\u002Fv1\u002F\",\n)\n\ntry:\n    resp = client.responses.create(\n        model=os.environ[\"AZURE_OPENAI_DEPLOYMENT\"],\n        input=\"ping\",\n        max_output_tokens=50,\n        store=False,\n    )\n    print(f\"✅ Deployment supports Responses API: {resp.output_text}\")\nexcept Exception as e:\n    print(f\"❌ Deployment does NOT support Responses API: {e}\")\n```\n\n> **Бележка**: `max_output_tokens` има **минимум 16** в Azure OpenAI. Стойности под 16 връщат грешка 400. Използвайте 50+ за бързи тестове.\n\nАко това връща 404, моделът на разгръщането все още не поддържа Responses — проверете референцията по-долу или преинсталирайте с поддържан модел.\n\n### 2. Проверете наличните модели във вашия регион (препоръчително)\n\nСтартирайте вградения инструмент за съвместимост на модели, за да видите какво е налично с поддръжка на Responses API във вашия конкретен регион:\n\n```bash\npython migrate.py models --subscription YOUR_SUB_ID --location YOUR_REGION\n```\n\nТова заявява директно към Azure ARM и показва матрица на съвместимост — кои модели поддържат Responses, структурирани изходи, инструменти и др. Използвайте `--filter gpt-5.1,gpt-5.2` за филтриране или `--json` за скриптиране.\n\n### 3. Пълна референция за поддръжка на модели\n\n- **Живо запитване**: `python migrate.py models` (вижте по-горе — специфично за регион, винаги актуално)\n- **Преглед на наличности**: [Таблица с обобщение на модели и регионална наличност](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Ffoundry\u002Ffoundry-models\u002Fconcepts\u002Fmodels-sold-directly-by-azure?tabs=global-standard-aoai%2Cglobal-standard&pivots=azure-openai#model-summary-table-and-region-availability)\n- **Бърз старт и ръководство**: **https:\u002F\u002Faka.ms\u002Fopenai\u002Fstart**\n\n### ⚠️ Ограничения на по-старите модели\n\n> **ВНИМАНИЕ**: По-старите модели (тези преди `gpt-4.1`) може да не поддържат всички функции на Responses API пълноценно.\n>\n> Известни ограничения с по-старите модели:\n> - **Параметър `reasoning`**: Не се поддържа при много модели без reasoning. Мигрирайте `reasoning` само ако вече присъства в оригиналния код.\n> - **Параметър `seed`**: Не се поддържа изобщо в Responses API — премахнете го от всички заявки.\n> - **Структуриран изход чрез `text.format`**: При по-старите модели `strict: true` JSON схеми може да не се налагат надеждно.\n> - **Оркестрация на инструменти**: GPT-5+ обработва извиквания на инструменти като част от вътрешния reasoning. По-старите модели на Responses работят, но им липсва тази дълбока интеграция.\n> - **Ограничения на температурата**: При мигриране към `gpt-5`, температурата трябва да се пропусне или зададе на `1`. По-старите модели нямат такова ограничение.\n\n### O-серия reasoning модели (o1, o3-mini, o3, o4-mini)\n\nМоделите от серия O имат уникални параметрични ограничения. При мигриране на приложения, които целят тези модели:\n\n- **`temperature`**: Трябва да бъде `1` (или пропуснат). O-серия моделите не приемат други стойности.\n- **`max_completion_tokens` → `max_output_tokens`**: Приложения, използващи Azure-специфичния `max_completion_tokens`, трябва да преминат към `max_output_tokens`. Задайте високи стойности (4096+) тъй като токените за reasoning се броят към лимита.\n- **`reasoning_effort`**: Ако приложението използва `reasoning_effort` (ниско\u002Fсредно\u002Fвисоко), запазете това — Responses API поддържа този параметър за o-серия модели.\n- **Поведение на стрийминг**: O-серия моделите може да буферират изхода до приключване на reasoning преди да изпратят събития с текстови дялове. Стриймингът все още работи, но първият `response.output_text.delta` може да пристигне с по-голямо изчакване спрямо GPT моделите.\n- **`top_p`**: Не се поддържа на o-серия — премахнете го, ако е наличен.\n- **Употреба на инструменти**: O-серия моделите поддържат инструменти чрез Responses API както GPT моделите, но качеството на оркестрация на извикванията варира по модели.\n\n**Действие — проактивна информационна препоръка**: По време на сканиране проверявайте към кой модел таргетира приложението (имена на разгръщания, системни променливи, конфигурация). Ако моделът е преди `gpt-4.1` (не е gpt-4.1+), проактивно уведомете потребителя:\n- Миграцията ще работи за базов текст, чат, стрийминг и инструменти на текущия му модел.\n- По-новите модели (`gpt-5.1`, `gpt-5.2`) предлагат по-добра оркестрация на инструменти, прилагане на структурирани изходи, reasoning и крос-регионална наличност.\n- Те трябва да обмислят ъпгрейд на разгръщането си когато са готови — това не блокира миграцията.\n\nНе блокирайте или отказвайте миграция според версията на модела. Информацията е само препоръчителна.\n\n### GitHub моделите НЕ поддържат Responses API\n\n> **GitHub моделите (`models.github.ai`, `models.inference.ai.azure.com`) не поддържат Responses API.**\n\nАко кодовата база съдържа път за GitHub модели (потърсете `base_url`, сочещ към `models.github.ai` или `models.inference.ai.azure.com`), **премахнете го изцяло** при миграцията. Responses API изисква Azure OpenAI, OpenAI, или съвместим локален endpoint (например Ollama с Responses поддръжка).\n\nДействия по време на сканиране:\n- Отбележете всеки кодов път с GitHub модели за премахване.\n\n---\n\n## Миграция на рамката (Framework)\n\nМного приложения използват по-високо ниво рамки върху OpenAI. При миграция на тези, промените са в самия API на рамката — не само основните OpenAI извиквания.\n\n### Microsoft Agent Framework (MAF)\n\n**Проверете първо версията на MAF** — миграцията зависи дали сте на MAF 1.0.0+ или на пред-1.0.0 бета\u002Frc.\n\n#### MAF 1.0.0+ (agent-framework-openai >= 1.0.0)\n\n`OpenAIChatClient` **вече използва Responses API** — няма нужда от миграция. Ако кодовата база използва остарялото `OpenAIChatCompletionClient` (който ползва `chat.completions.create`), заменете го с `OpenAIChatClient`.\n\n| Преди | След |\n|--------|-------|\n| `from agent_framework.openai import OpenAIChatCompletionClient` | `from agent_framework.openai import OpenAIChatClient` |\n| `OpenAIChatCompletionClient(...)` | `OpenAIChatClient(...)` |\n\nЗа да проверите версията: `python -c \"import agent_framework_openai; print(agent_framework_openai.__version__)\"`\n\n#### MAF преди 1.0.0 (бета\u002Frc версии)\n\nВ пред-1.0.0 MAF, `OpenAIChatClient` използва Chat Completions. Ъпгрейднете до `agent-framework-openai>=1.0.0`, където `OpenAIChatClient` по подразбиране използва Responses API.\n\nДруги промени не са необходими — `Agent` и инструменталните API остават същите.\n\n### LangChain (`langchain-openai`)\n\nДобавете `use_responses_api=True` на `ChatOpenAI()`. Също така обновете достъпа до отговорите от `.content` към `.text`.\n\n| Преди | След |\n|--------|-------|\n| `ChatOpenAI(model=..., base_url=..., api_key=...)` | `ChatOpenAI(model=..., base_url=..., api_key=..., use_responses_api=True)` |\n| `result['messages'][-1].content` | `result['messages'][-1].text` |\n\nЗа пълни пример кодове преди\u002Fслед, вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\n---\n\n## Ръководство за миграция на фронтенд\n\n> **Responses API е грижа на сървърната страна.** Мигрирайте backend на Python; HTTP контракта на фронтенда трябва да остане непроменен, освен ако backend не е тънък пропускателен слой — в такъв случай обмислете да приемете формата на Responses заявки, за да елиминирате слой превод. Ако фронтенд извиква OpenAI директно с ключ на клиентската страна, преместете тези извиквания първо в backend.\n\n### Оттегляне на `@microsoft\u002Fai-chat-protocol`\n\nПакетът npm `@microsoft\u002Fai-chat-protocol` е оттеглен и трябва да бъде заменен с [`ndjson-readablestream`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fndjson-readablestream). Ако го срещнете във фронтенд:\n\n1. Заменете CDN скрипт тага:\n   ```html\n   \u003C!-- Before -->\n   \u003Cscript src=\"https:\u002F\u002Fcdn.jsdelivr.net\u002Fnpm\u002F@microsoft\u002Fai-chat-protocol@...\u002Fdist\u002Fiife\u002Findex.js\">\u003C\u002Fscript>\n   \u003C!-- After -->\n   \u003Cscript src=\"https:\u002F\u002Fcdn.jsdelivr.net\u002Fnpm\u002Fndjson-readablestream@1.0.7\u002Fdist\u002Fndjson-readablestream.umd.js\">\u003C\u002Fscript>\n   ```\n2. Премахнете инстанцията `AIChatProtocolClient` (`new ChatProtocol.AIChatProtocolClient(\"\u002Fchat\")`).\n3. Заменете `client.getStreamedCompletion(messages)` с директно `fetch()` извикване към backend стрийминг endpoint.\n4. Заменете `for await (const response of result)` с `for await (const chunk of readNDJSONStream(response.body))`.\n5. Обновете достъпа до свойства от `response.delta.content` \u002F `response.error` към `chunk.delta.content` \u002F `chunk.error`.\n\n---\n\n## Цели\n\n- Изброяване на всички Python извиквания, използващи Chat Completions или остарели Completions срещу Azure OpenAI.\n- Предложете план и последователност за миграция на Python кодовата база.\n- Прилагане на сигурни, минимални редакции за превключване към Responses API.\n- Актуализиране на извикващите, за да консумират схемата за изход на Responses; няма нужда от обвивни backward-compatibility решения.\n- Изпълнете тестове\u002Fлинт проверки; поправете дребни счупвания, въведени при миграцията.\n- Подгответе малки, лесно рецензируеми набори промени и предоставете финално резюме с дифове (не комитвайте).\n\n---\n\n## Граници\n\n- Променяйте само файлове в git workspace. Никога не пишете извън него.\n- Не запазвайте backward-compatibility шими; мигрирайте кода към новата форма на API.\n- Не оставяйте преходни коментари или резервни копия на файлове.\n- Запазвайте семантиката на стрийминг ако преди сте я използвали; иначе използвайте не-стрийминг.\n- Поискайте одобрение преди изпълнение на команди или мрежови извиквания, ако сте в режим на одобрение.\n- Не изпълнявайте `git add`\u002F`git commit`\u002F`git push`; правете само редакции на работното дърво.\n\n---\n\n## Стъпка 0: Миграция на Azure OpenAI клиент (предварително условие)\n\nАко кодовата база използва конструктори `AzureOpenAI` или `AsyncAzureOpenAI`, първо мигрирайте към стандартните конструктори `OpenAI` \u002F `AsyncOpenAI`. Специфичните конструктори за Azure са оттеглени в `openai>=1.108.1`.\n\n### Защо API пътя v1?\n\nНовият endpoint `\u002Fopenai\u002Fv1` използва стандартния клиент `OpenAI()` вместо `AzureOpenAI()`, не изисква параметър `api_version` и работи еднакво както с OpenAI, така и с Azure OpenAI. Същият клиент код е бъдещо устойчива — няма нужда от управление на версии.\n\n### Основни промени\n\n| Преди | След |\n|--------|-------|\n| `AzureOpenAI` | `OpenAI` |\n| `AsyncAzureOpenAI` | `AsyncOpenAI` |\n| `azure_endpoint` | `base_url` |\n| `azure_ad_token_provider` | `api_key` |\n| `api_version=...` | Премахнете напълно |\n\n### Контролен списък за почистване\n\n- Премахнете аргумента `api_version` от конструктора на клиента.\n- Премахнете променливите на средата `AZURE_OPENAI_VERSION` \u002F `AZURE_OPENAI_API_VERSION` от `.env`, настройки на приложение и Bicep\u002Finfra файлове.\n- Преименувайте `AZURE_OPENAI_CLIENT_ID` → `AZURE_CLIENT_ID` в `.env`, настройки на приложение, Bicep\u002Finfra и тестови фикстури (стандартна конвенция на Azure Identity SDK).\n- Уверете се, че `openai>=1.108.1` е в `requirements.txt` или `pyproject.toml`.\n\n### Миграция на променливи на средата\n\n| Стара променлива | Действие | Забележки |\n|-------------|--------|-------|\n| `AZURE_OPENAI_VERSION` | **Премахнете** | Не е нужна `api_version` с v1 endpoint |\n| `AZURE_OPENAI_API_VERSION` | **Премахнете** | Същото като по-горе |\n| `AZURE_OPENAI_CLIENT_ID` | **Преименувайте** → `AZURE_CLIENT_ID` | Стандартна конвенция на Azure Identity SDK за `ManagedIdentityCredential(client_id=...)` |\n| `AZURE_OPENAI_ENDPOINT` | **Запазете** | Все още се използва за конструкция на `base_url` |\n| `AZURE_OPENAI_CHAT_DEPLOYMENT` | **Запазете** | Използва се като параметър `model` в `responses.create` |\n| `AZURE_OPENAI_API_KEY` | **Запазете** | Използва се като `api_key` за автентикация с ключ |\n\nЗа примери за настройка на клиент (синхронен, асинхронен, EntraID, API ключ, мулти-клиентски), вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\n---\n\n## Стъпка 1: Откриване на остарели извиквания\n\nСтартирайте скрипта [detect_legacy.py](..\u002F..\u002F..\u002F..\u002F..\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py) за намиране на всички извиквания, които трябва да бъдат мигрирани:\n\n```bash\npython skills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py .\n```\n\nИли изпълнете тези търсения ръчно — всяко съвпадение е цел за миграция:\n\n```bash\n# Обаждания към остарял API (трябва преписване)\nrg \"chat\\.completions\\.create\"\nrg \"ChatCompletion\\.create\"\nrg \"Completion\\.create\"\n\n# Остарели конструктори на Azure клиент (трябва замяна)\nrg \"AzureOpenAI\\(\"\nrg \"AsyncAzureOpenAI\\(\"\n\n# Модели за достъп до формата на отговорите (трябва обновяване)\nrg \"choices\\[0\\]\\.message\\.content\"\nrg \"choices\\[0\\]\\.delta\\.content\"\nrg \"choices\\[0\\]\\.message\\.function_call\"\nrg \"choices\\[0\\]\\.message\\.tool_calls\"\n\n# Определения на инструменти в стар вложен формат (трябва изглаждане)\nrg '\"function\":\\s*{\\s*\"name\"'\nrg \"pydantic_function_tool\"\n\n# Резултати от инструменти в стар формат (трябва конвертиране във function_call_output)\nrg '\"role\":\\s*\"tool\"'\nrg '\"tool_call_id\"'\n\n# Остарели параметри (трябва премахване или преименуване)\nrg \"response_format\"\nrg \"max_tokens\\b\"        # преименувай на max_output_tokens\nrg \"['\\\"]seed['\\\"]\"      # remove entirely\n\n# Остарели променливи на средата (почистване)\nrg \"AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION\"\nrg \"AZURE_OPENAI_CLIENT_ID\"  # трябва да е AZURE_CLIENT_ID\n\n# Крайни точки на GitHub Models (трябва премахване — Responses API не се поддържа)\nrg \"models\\.github\\.ai|models\\.inference\\.ai\\.azure\"\n\n# Наследствени модели на ниво фреймуърк (трябва обновяване)\nrg \"OpenAIChatCompletionClient\"  # MAF 1.0.0+: замени с OpenAIChatClient\nrg \"ChatOpenAI\\(\" | grep -v \"use_responses_api\"  # LangChain: изисква use_responses_api=True\n\n# Тестова инфраструктура (трябва обновяване)\nrg \"ChatCompletionChunk|AsyncCompletions\\.create\" tests\u002F\nrg \"_azure_ad_token_provider\" tests\u002F\nrg \"prompt_filter_results|content_filter_results\" tests\u002F\nrg \"choices\\[0\\]\" tests\u002F\n\n# Достъп до тялото на грешката при филтър за съдържание (трябва обновяване — структурата се е променила)\nrg 'innererror.*content_filter_result|error\\.body\\[\"innererror\"\\]'\nrg \"content_filter_result\\[\" # старо единствено число — сега content_filter_results (множествено) вътре в масива content_filters\n\n# Сурови HTTP повиквания към крайна точка Chat Completions (трябва обновяване на URL)\nrg \"\u002Fopenai\u002Fdeployments\u002F.*\u002Fchat\u002Fcompletions\"\nrg \"api-version=\"\n```\n\n### Евристики (откриване и преписване)\n\n- **Chat Completions клиент**: `client.chat.completions.create` → `client.responses.create(...)`.\n\n- **Конструктори на Azure клиент**: `AzureOpenAI(...)` → `OpenAI(base_url=..., api_key=...)`.\n- **Инструменти**: конвертирайте дефинициите на инструментите за извикване на функции от вложен формат (`{\"type\": \"function\", \"function\": {\"name\": ...}}`) във формат на Responses (`{\"type\": \"function\", \"name\": ...}`); използвайте `tool_choice`; връщайте резултатите от инструмента като елементи `{\"type\": \"function_call_output\", \"call_id\": ..., \"output\": ...}` (не като `{\"role\": \"tool\", ...}`).\n- **Обратни трансформации на инструментите**: когато моделът връща извиквания на функции, добавяйте елементите `response.output` към разговора (не ръчно речник `{\"role\": \"assistant\", \"tool_calls\": [...]}`), след което добавяйте елементите `function_call_output` за всеки резултат.\n- **Примери с малък брой удари за инструменти**: ако в разговора има твърдо кодирани примери за извикване на инструменти, конвертирайте ги в елементи `{\"type\": \"function_call\", \"id\": \"fc_...\", \"call_id\": \"fc_...\", ...}` + `{\"type\": \"function_call_output\", ...}`. Идентификаторите трябва да започват с `fc_`.\n- **`pydantic_function_tool()`**: този помощник все още генерира стария вложен формат и **не е съвместим** с `responses.create()`. Заменете с ръчно дефинирани инструменти или обвивка за изравняване.\n- **Многостъпков режим**: поддържайте история на разговора в приложението; предавайте предишни ходове чрез елементи `input`.\n- **Форматиране**: заменете главното ниво `response_format` на Chat с `text.format` в Responses. Канонична форма: `text={\"format\": {\"type\": \"json_schema\", \"name\": \"Output\", \"strict\": True, \"schema\": {...}}}`.\n- **Елементи съдържание**: заменете `content[].type: \"text\"` в Chat с `content[].type: \"input_text\"` в Responses за ходове на потребител\u002Fсистема.\n- **Елементи съдържание с изображения**: заменете `content[].type: \"image_url\"` в Chat с `content[].type: \"input_image\"` в Responses. Полето `image_url` се променя от вложен обект `{\"url\": \"...\"}` на плосък низ. Вижте листа с препоръки за примери преди\u002Fслед.\n- **Усилие за логическо обяснение**: **мигрирайте `reasoning` само ако вече съществува в оригиналния код**.\n- **Обработка на грешки от филтъра на съдържание**: структурата на тялото на грешката се промени. Chat Completions използваше `error.body[\"innererror\"][\"content_filter_result\"]` (в единствено число); Responses API използва `error.body[\"content_filters\"][0][\"content_filter_results\"]` (в множествено число вътре в масив). Код, който достъпва `innererror`, ще вдигне `KeyError`. Пренапишете, за да използвате новия път.\n- **Сурови HTTP повиквания**: ако приложението директно извиква Azure OpenAI REST API (чрез `requests`, `httpx` и др.) с `\u002Fopenai\u002Fdeployments\u002F{name}\u002Fchat\u002Fcompletions?api-version=...`, пренапишете към `\u002Fopenai\u002Fv1\u002Fresponses`. Тялото на заявката се променя: `messages` → `input`, добавя се `max_output_tokens` и `store: false`, премахва се заявният параметър `api-version`. Тялото на отговора се променя: `choices[0].message.content` → `output[0].content[0].text` (забележка: `output_text` е удобство в SDK, което липсва в суровия REST JSON).\n\n---\n\n## Стъпка 2: Приложете миграцията\n\n### Бележки по миграцията (Chat Completions → Responses)\n\n- **Защо да мигрираме**: Responses е унифицирано API за текст, инструменти и стрийминг; Chat Completions е наследен. С GPT-5 Responses се изисква за най-добра производителност.\n- **HTTP**: Azure ендпойнт преминава от `\u002Fopenai\u002Fdeployments\u002F{name}\u002Fchat\u002Fcompletions` към `\u002Fopenai\u002Fv1\u002Fresponses`.\n- **Полетата**: `messages` → `input`, `max_tokens` → `max_output_tokens`. `temperature` остава.\n- **Форматиране**: `response_format` → `text.format` с правилен обект.\n- **Елементи съдържание**: Заменете `content[].type: \"text\"` в Chat с `content[].type: \"input_text\"` в Responses за системни и потребителски ходове.\n- **Елементи съдържание с изображения**: Заменете `content[].type: \"image_url\"` в Chat с `content[].type: \"input_image\"` в Responses. Изравнете полето `image_url` от `{\"image_url\": {\"url\": \"...\"}}` в `{\"image_url\": \"...\"}` (обикновен низ — HTTPS URL или data URI от тип `data:image\u002F...;base64,...`).\n\n### Справка със съпоставяне на параметри\n\n| Chat Completions | Responses API |\n|-----------------|---------------|\n| `prompt` | `input` |\n| `messages` | `input` (масив от елементи) |\n| `max_tokens` | `max_output_tokens` |\n| `response_format` | `text.format` (обект) |\n| `temperature` | `temperature` (непроменено) |\n| `stop` | `stop` (непроменено) |\n| `frequency_penalty` | `frequency_penalty` (непроменено) |\n| `presence_penalty` | `presence_penalty` (непроменено) |\n| `tools` \u002F извикване на функции | `tools` (непроменено) |\n| `seed` | **Премахнете** (не се поддържа) |\n| `store` | `store` (зададено на `false`) |\n| `content[].type: \"text\"` | `content[].type: \"input_text\"` |\n| `content[].type: \"image_url\"` | `content[].type: \"input_image\"` |\n| `\"image_url\": {\"url\": \"...\"}` | `\"image_url\": \"...\"` (плосък низ) |\n\nЗа пълни примери с код преди и след, вижте [cheat-sheet.md](.\u002Freferences\u002Fcheat-sheet.md).\n\nЗа миграция на тестова инфраструктура (мокове, снимки, проверки), вижте [test-migration.md](.\u002Freferences\u002Ftest-migration.md).\n\nЗа отстраняване на грешки и често срещани проблеми, вижте [troubleshooting.md](.\u002Freferences\u002Ftroubleshooting.md).\n\n---\n\n## Съхранение на данни и състояние\n\n- Задайте `store: false` на всички заявки към Responses.\n- Не се доверявайте на предишни идентификатори на съобщения или контекст, съхраняван на сървъра; управлявайте състоянието от клиента и минимизирайте метаданните.\n\n---\n\n## Критерии за приемане\n\n### Кодови проверки (всички трябва да преминат)\n\n- [ ] Нулев брой съвпадения за `rg \"chat\\.completions\\.create|ChatCompletion\\.create|Completion\\.create\"` в мигрираните файлове.\n- [ ] Нулев брой съвпадения за `rg \"AzureOpenAI\\(|AsyncAzureOpenAI\\(\"` — всички конструктори използват `OpenAI`\u002F`AsyncOpenAI` с v1 ендпойнт.\n- [ ] Нулев брой съвпадения за `rg \"models\\.github\\.ai|models\\.inference\\.ai\\.azure\"` — премахнати са пътища в кода за модели на GitHub.\n- [ ] Нулев брой съвпадения за `rg \"OpenAIChatCompletionClient\"` — кодът от MAF 1.0.0+ използва `OpenAIChatClient` (който използва Responses API). В преди 1.0.0 ъпгрейднете до `agent-framework-openai>=1.0.0`.\n- [ ] Всички повиквания `ChatOpenAI(...)` включват `use_responses_api=True`.\n- [ ] Нулев брой съвпадения за `rg \"choices\\[0\\]\"` — целият достъп до отговори използва `resp.output_text` или схемата за отговори на Responses.\n- [ ] Няма `response_format` на главно ниво; цялата структурирана продукция използва `text={\"format\": {...}}`.\n- [ ] `openai>=1.108.1` и `azure-identity` в `requirements.txt` или `pyproject.toml`; зависимости преинсталирани.\n- [ ] `store=False` зададено във всяко извикване на `responses.create`.\n- [ ] Няма `api_version` в конструкцията на клиента; `AZURE_OPENAI_API_VERSION` премахнат от файловете с околна среда и инфраструктурата.\n\n### Тестови инфраструктурни проверки (всички трябва да преминат)\n\n- [ ] Нулев брой съвпадения за `rg \"ChatCompletionChunk|AsyncCompletions\\.create|chat\\.completions\" tests\u002F`.\n- [ ] Нулев брой съвпадения за `rg \"_azure_ad_token_provider\" tests\u002F` — проверки актуализирани да проверяват `isinstance(client, AsyncOpenAI)` или `base_url`.\n- [ ] Нулев брой съвпадения за `rg \"prompt_filter_results|content_filter_results\" tests\u002F` — премахнати са мокове, специфични за Azure филтри.\n- [ ] Моковете използват `kwargs.get(\"input\")`, не `kwargs.get(\"messages\")`.\n- [ ] Файловете със снимки \u002F златни файлове са актуализирани към формата на Responses за стрийминг (няма `choices[0]`, `function_call`, `logprobs` и т.н.).\n- [ ] `pytest` минава без грешки след всички тестови актуализации.\n\n### Поведенчески проверки (проверяват се ръчно или с тестови инструменти)\n\n- [ ] **Основно завършване**: нестрийминг `responses.create` връща непразен `output_text`.\n- [ ] **Паритет на стрийминг**: ако оригиналният код използваше стрийминг, мигрираният код стриймва и излъчва събития `response.output_text.delta` с непразни делти.\n- [ ] **Структуриран изход**: ако се използва `text.format` с `json_schema`, `json.loads(resp.output_text)` е успешна и съвпада със схемата.\n- [ ] **Цикъл за извикване на инструменти**: ако се използват инструменти, моделът издава извиквания на инструменти, приложението ги изпълнява, а следващата заявка връща финален `output_text` (няма безкраен цикъл).\n- [ ] **Паритет на асинхронност**: ако е използван `AsyncAzureOpenAI`, равностойният `AsyncOpenAI` работи с `await`.\n- [ ] **Ниво на грешки**: няма нови грешки 400\u002F401\u002F404 в сравнение с базовата линия преди миграцията.\n\n### Доставки\n\n- Резюмето включва редактирани файлове, брой повиквания на наследен код преди\u002Fслед и следващи стъпки.\n- Промените са само като редакции в работното дърво (без комити).\n\n---\n\n## Изисквания за версия на SDK\n\n| Пакет | Минимална версия |\n|---------|----------------|\n| `openai` | `>=1.108.1` |\n| `azure-identity` | Най-нова (за EntraID автентикация) |\n\n---\n\n## Препратки\n\n- [Cheat Sheet — всички кодови фрагменти](.\u002Freferences\u002Fcheat-sheet.md)\n- [Test Migration — мокове, снимки, проверки](.\u002Freferences\u002Ftest-migration.md)\n- [Troubleshooting — грешки, таблица с рискове, често срещани проблеми](.\u002Freferences\u002Ftroubleshooting.md)\n- [detect_legacy.py — автоматизиран скенер](..\u002F..\u002F..\u002F..\u002F..\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Fscripts\u002Fdetect_legacy.py)\n- [Azure OpenAI Starter Kit](https:\u002F\u002Faka.ms\u002Fopenai\u002Fstart)\n- [Azure OpenAI Responses API docs](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-foundry\u002Fopenai\u002Fhow-to\u002Fresponses)\n- [Azure OpenAI API version lifecycle](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Fai-foundry\u002Fopenai\u002Fapi-version-lifecycle?view=foundry-classic&tabs=python#api-evolution)\n- [OpenAI Responses API reference](https:\u002F\u002Fplatform.openai.com\u002Fdocs\u002Fapi-reference\u002Fresponses)\n\n---\n\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**Отказ от отговорност**:\nТози документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https:\u002F\u002Fgithub.com\u002FAzure\u002Fco-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER END -->",{"name":5,"license":14},"main","f09e94ffe170f8af6d3db7c42987bbe4db227723","translations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses",26019,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners","https:\u002F\u002Faka.ms\u002Fai-agents-beginners","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-07 12:51:12",{"source":7,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add microsoft\u002Fai-agents-for-beginners --skill azure-openai-to-responses",{"tool":40,"command":41},"bunx","bunx skills add microsoft\u002Fai-agents-for-beginners --skill azure-openai-to-responses",{"tool":43,"command":44},"pnpm","pnpm dlx skills add microsoft\u002Fai-agents-for-beginners --skill azure-openai-to-responses","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002FSKILL.md",true,[48,54,58],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fcheat-sheet.md","REFERENCE","参考文档",35987,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Freferences\u002Fcheat-sheet.md",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Ftest-migration.md",9141,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Freferences\u002Ftest-migration.md",{"path":59,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Ftroubleshooting.md",23285,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fbg\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002Freferences\u002Ftroubleshooting.md",[63,81,92,100,108,115],{"skillNo":64,"name":65,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":78,"publishedAt":19},"01M69A206TRZ8KK0CW0HYJF5V5","testing-course-samples","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Ftesting-course-samples\u002FSKILL.md",[68,73],{"categoryNo":69,"categoryName":70,"taxonomyType":71,"taxonomyTypeDesc":72},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":74,"categoryName":75,"taxonomyType":76,"taxonomyTypeDesc":77},"01JBSEEDCAT000000000000039","教师与教育","PROFESSION","适用职业",[79,80],"testing","testing course samples",{"skillNo":82,"name":83,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":89,"publishedAt":19},"01M69A1XRB2SFHYRMEH0K08EKZ","microsoft-docs","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fmicrosoft-docs\u002FSKILL.md",[86],{"categoryNo":87,"categoryName":88,"taxonomyType":71,"taxonomyTypeDesc":72},"01JBSEEDCAT000000000000023","Skill与智能体开发",[90,8,91],"docs","microsoft docs",{"skillNo":93,"name":94,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M69A1VPZFJQ1HNGTZQ5P3WSC","local-ai-agents","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Flocal-ai-agents\u002FSKILL.md",[],[98,99],"ai agents","local ai agents",{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M69A1S947N7MM6V9JF85S2E7","jupyter-notebook","當使用者要求建立、搭建或編輯 Jupyter 筆記本（`.ipynb`）用於實驗、探索或教學時使用；優先使用隨附範本並執行輔助腳本 `new_notebook.py` 來產生一個乾淨的起始筆記本。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fjupyter-notebook\u002FSKILL.md",[],[107],"jupyter notebook",{"skillNo":109,"name":110,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":19},"01M69A1Q8EXPWKZSQK69V6WF22","deploying-scalable-agents","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fdeploying-scalable-agents\u002FSKILL.md",[],[114],"deploying scalable agents",{"skillNo":116,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":19},"01M69A1MHZTH3RH9N8VYSYG74X","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002FSKILL.md",[],[18]]