Azure Openai To Responses Agent Skill

Migrate Python Apps from Azure OpenAI Chat Completions to Responses API

> AUTHORITATIVE GUIDANCE — FOLLOW EXACTLY

>

> This skill migrates Python codebases using Azure OpenAI Chat Completions

> to the unified Responses API. Follow these instructions precisely.

> Do not improvise parameter mappings or invent API shapes.

Installed from Azure-Samples/azure-openai-to-responses (MIT).

Triggers

Activate this skill when the user wants to:

• Migrate a Python app from Azure OpenAI Chat Completions to Responses API
• Upgrade Python OpenAI SDK usage to the latest API shape against Azure OpenAI
• Prepare Python code for GPT-5 or newer models that require Responses on Azure
• Switch from AzureOpenAI/AsyncAzureOpenAI to standard OpenAI/AsyncOpenAI client with the v1 endpoint
• Fix deprecation warnings related to AzureOpenAI constructors or api_version

Why migrate

GPT-5 and newer models require the Responses API. The new /openai/v1/ endpoint

uses the standard OpenAI() client instead of AzureOpenAI(), requires no

api_version parameter, and works identically across OpenAI and Azure OpenAI.

What changes

| Chat Completions (before) | Responses API (after) |

| --- | --- |

| AzureOpenAI() / AsyncAzureOpenAI() | OpenAI(base_url=...) / AsyncOpenAI(base_url=...) |

| azure_endpoint=... | base_url=f"{endpoint.rstrip('/')}/openai/v1/" |

| api_version="2024-..." | Remove entirely — /openai/v1/ is stable |

| azure_ad_token_provider=... | api_key=token_provider |

| client.chat.completions.create(messages=...) | client.responses.create(input=...) |

| resp.choices[0].message.content | resp.output_text |

| max_tokens | max_output_tokens (min 16 on Azure) |

| response_format | text={"format": {...}} |

| seed | Remove (not supported) |

| tools nested {"type":"function","function":{...}} | flat {"type":"function","name":...} |

| tool result {"role":"tool","tool_call_id":...} | {"type":"function_call_output","call_id":...,"output":...} |

| content[].type: "text" | content[].type: "input_text" |

| content[].type: "image_url" + {"url": "..."} | content[].type: "input_image" + flat "image_url": "..." |

| streaming chunk.choices[0].delta.content | event.type == "response.output_text.delta" → event.delta |

Model compatibility — CHECK FIRST

Verify the deployed model supports the Responses API before migrating. GPT-4o and

GPT-4 support Responses for basic text/chat/streaming/tools but not all features.

Newer models (gpt-4.1+, gpt-5.x) have full support. **GitHub Models

(models.github.ai, models.inference.ai.azure.com) do NOT support the Responses

API** — remove those code paths and switch to Azure OpenAI, OpenAI, or a compatible

local endpoint.

Smoke test:

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/",
)
resp = client.responses.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    input="ping",
    max_output_tokens=50,
    store=False,
)
print(resp.output_text)

Step 0: Client migration (prerequisite)

AzureOpenAI/AsyncAzureOpenAI constructors are deprecated in openai>=1.108.1.

Before:

from openai import AzureOpenAI
client = AzureOpenAI(
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
)

After:

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/",
)

Cleanup: remove api_version args, remove AZURE_OPENAI_API_VERSION /

AZURE_OPENAI_VERSION from .env/infra, rename AZURE_OPENAI_CLIENT_ID →

AZURE_CLIENT_ID, ensure openai>=1.108.1.

Step 1: Detect legacy call sites

rg "chat\.completions\.create"        # legacy API calls
rg "ChatCompletion\.create|Completion\.create"
rg "AzureOpenAI\(|AsyncAzureOpenAI\("  # deprecated constructors
rg "choices\[0\]\.message\.content"    # response access
rg "choices\[0\]\.delta\.content"      # streaming access
rg "max_tokens\b"                      # rename to max_output_tokens
rg "['\"]seed['\"]"                    # remove entirely
rg "response_format"                   # → text.format
rg "AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION"
rg "models\.github\.ai|models\.inference\.ai\.azure"  # GitHub Models: remove

Step 2: Apply migration

• client.chat.completions.create(messages=...) → client.responses.create(input=...)
• resp.choices[0].message.content → resp.output_text
• max_tokens → max_output_tokens (min 16); remove seed
• response_format → text={"format": {"type": "json_schema", "name": "Output", "strict": True, "schema": {...}}}
• Set store=False on every request (client-managed state)
• Streaming: iterate events, handle event.type == "response.output_text.delta" (use event.delta) and response.completed
• Tools: flat format, tool_choice, return results as function_call_output items; append response.output items for round-trips
• Multi-turn: maintain conversation in an input array, or use previous_response_id (requires store=True)
• Reasoning models (o-series, GPT-5): max_completion_tokens → max_output_tokens (4096+), reasoning_effort → reasoning={"effort": ...}, omit temperature/top_p (GPT-5 rejects temperature outright; to vary output use a non-reasoning model like Llama-3.3-70B-Instruct via Foundry Models)

Acceptance criteria (all must pass)

• Zero matches for chat.completions.create|ChatCompletion.create|Completion.create
• Zero matches for AzureOpenAI(|AsyncAzureOpenAI( — all use OpenAI/AsyncOpenAI + v1 endpoint
• Zero matches for models.github.ai|models.inference.ai.azure
• Zero matches for choices[0] — all access uses resp.output_text / Responses schema
• No top-level response_format; structured output uses text={"format": {...}}
• openai>=1.108.1 in requirements; store=False on every call; no api_version in client construction
• Tests updated (mocks use kwargs.get("input"), snapshots use Responses shape); pytest passes

See references/cheat-sheet.md for complete before/after code examples.

References

• Azure OpenAI Responses API docs
• OpenAI Responses API reference
• Source skill: Azure-Samples/azure-openai-to-responses