---

name: azure-openai description: Integrates Azure OpenAI Service (GPT deployments, Responses API, Content Filters, Entra ID auth, Assistants) using the OpenAI SDK with Azure v1 endpoint patterns. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: coding triggers: azure openai, azure openai service, azure gpt, azure responses api, content filters, azure openai deployment, how do i use azure openai, microsoft foundry archetypes:

• tactical
• generation anti_triggers:
• brainstorming
• vague ideation
• code golf
• over-engineering response_profile: verbosity: low directive_strength: high abstraction_level: operational role: implementation scope: implementation output-format: code content-types:
• code
• guidance
• examples
• do-dont related-skills: coding-openai-api, coding-aws-bedrock, coding-langchain

---

Azure OpenAI Service Integration

Integrates Azure OpenAI Service using the openai Python SDK with the Azure v1 API endpoint. When loaded, this skill makes the model implement Azure OpenAI calls with proper authentication (API key and Entra ID), the Responses API, content filter handling, and deployment management.

When to Use

Use this skill when:

• Deploying and calling OpenAI models through Microsoft Azure OpenAI Service
• Using the new Azure OpenAI v1 API (stable, no api-version parameter needed)
• Implementing Entra ID (formerly Azure AD) token-based authentication
• Handling Azure OpenAI content filters and responsible AI configurations
• Building with GPT-5+ and newer models that require the Responses API on Azure
• Migrating from AzureOpenAI() client to the standard OpenAI() client with v1 endpoint
• Working with Azure Foundry model catalog (DeepSeek, Grok, etc. via OpenAI SDK)

---

When NOT to Use

• For direct OpenAI API usage (not through Azure), use coding-openai-api
• For AWS Bedrock, use coding-aws-bedrock
• For Azure AI Inference SDK patterns, prefer the OpenAI SDK migration

---

Core Workflow

1. Choose Authentication Method — Use API key auth for simplicity: set AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT. Use Entra ID auth for production: use DefaultAzureCredential and get_bearer_token_provider. The v1 API uses the standard OpenAI() client, not the deprecated AzureOpenAI() constructor. Checkpoint: Verify that base_url ends with /openai/v1/ — this is the stable v1 endpoint format.

2. Check Model Capabilities — Verify which API your deployed model supports: GPT-5+ requires the Responses API; older models (GPT-4o) work with both Chat Completions and Responses. Use the migrate.py script from the azure-openai-to-responses tooling to check per-region capability. Checkpoint: Confirm the model deployment name (not the model name) is used in the model parameter.

3. Send a Request with the Responses API — Use client.responses.create() with the deployment name as model. The Responses API is the recommended surface for GPT-5+ models and provides access to tools, web search, file search, and structured outputs. Checkpoint: Handle content filter errors separately — the error body structure differs between Chat Completions (innererror.content_filter_result) and Responses (content_filters[0].content_filter_results).

4. Handle Content Filters — Catch openai.PermissionDeniedError for content filter triggers. Access content filter results via e.body["content_filters"][0]["content_filter_results"] for the Responses API. Checkpoint: Test with a known trigger prompt to verify content filter error handling works.

5. Optional: Use Foundry AI Project Client — For advanced agent building, use the azure-ai-projects SDK with AIProjectClient and get_openai_client(). This provides access to Agents, Tools, and MCP integration with Azure Foundry. Checkpoint: Verify the project endpoint and model deployment exist in the Foundry project.

---

Implementation Patterns

Pattern 1: Basic Azure OpenAI with API Key Auth

from __future__ import annotations

import os

from openai import OpenAI

# ❌ BAD — uses deprecated AzureOpenAI() constructor, requires api_version
from openai import AzureOpenAI
client = AzureOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com",
    api_key="...",
    api_version="2024-12-01-preview",
)
response = client.chat.completions.create(
    model="gpt-4o-deployment",
    messages=[{"role": "user", "content": "Hello"}],
)

# ✅ GOOD — uses standard OpenAI() with v1 endpoint, no api_version needed
client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url="https://my-resource.openai.azure.com/openai/v1/",
)


def generate(
    prompt: str,
    deployment_name: str = "gpt-5.2-chat",
    max_tokens: int = 1024,
) -> str:
    """Generate a response using Azure OpenAI Responses API.

    Args:
        prompt: User input text.
        deployment_name: The Azure deployment name (not the model name).
        max_tokens: Maximum output tokens.

    Returns:
        The model's response text.

    Raises:
        ValueError: On authentication errors.
        RuntimeError: On content filter triggers or API errors.
    """
    try:
        response = client.responses.create(
            model=deployment_name,
            input=prompt,
            max_output_tokens=max_tokens,
        )
        return response.output_text
    except openai.PermissionDeniedError as e:
        # Check for content filter triggers
        body = getattr(e, "body", {})
        if body and "content_filters" in body:
            categories = body["content_filters"][0].get("content_filter_results", {})
            raise RuntimeError(
                f"Content filter triggered: {categories}"
            ) from e
        raise ValueError("Authentication failed. Check API key.") from e
    except openai.APIError as e:
        raise RuntimeError(f"Azure OpenAI API error: {e}") from e

Pattern 2: Entra ID Authentication (Production)

from __future__ import annotations

import os

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI

# ✅ GOOD — Entra ID auth with automatic token refresh
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

client = OpenAI(
    base_url="https://my-resource.openai.azure.com/openai/v1/",
    api_key=token_provider,  # type: ignore  # token_provider is callable
)


def generate_with_entra(prompt: str, deployment_name: str) -> str:
    """Generate using Entra ID authentication.

    The token provider handles automatic refresh, so no token management
    is needed in application code.

    Args:
        prompt: User input text.
        deployment_name: Azure deployment name.

    Returns:
        Generated response text.
    """
    response = client.responses.create(
        model=deployment_name,
        input=prompt,
    )
    return response.output_text

Pattern 3: Chat Completions with Non-OpenAI Models

The Azure v1 API also supports third-party models like DeepSeek and Grok via the chat completions endpoint.

from __future__ import annotations

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url="https://my-resource.openai.azure.com/openai/v1/",
)


def chat_with_third_party(
    prompt: str,
    deployment_name: str = "DeepSeek-V3.1",
) -> str:
    """Use Azure-hosted third-party models via Chat Completions.

    Args:
        prompt: User input.
        deployment_name: Deployment name for the third-party model.

    Returns:
        Model response text.
    """
    response = client.chat.completions.create(
        model=deployment_name,
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": prompt},
        ],
    )
    return response.choices[0].message.content or ""

---

Constraints

MUST DO

• Use the standard OpenAI() client, not the deprecated AzureOpenAI() constructor
• Append /openai/v1/ to the base URL — this is the stable v1 API endpoint
• Use the deployment name (not the model name) as the model parameter
• Use Entra ID token authentication for production workloads via DefaultAzureCredential and get_bearer_token_provider
• Handle content filter errors by checking e.body["content_filters"] (Responses API) vs e.body["innererror"] (Chat Completions)
• Use pip install openai>=1.108.1 for Azure v1 API support

MUST NOT DO

• Use api_version parameter with the v1 API — it is not needed and may cause errors
• Use AzureOpenAI(azure_endpoint=...) constructor — it is deprecated in openai>=1.108.1
• Hardcode Azure resource names, API keys, or tenant IDs in source files
• Skip Entra ID auth for production — API keys lack token refresh and role-based access control

---

Live References

Resource	URL
Azure OpenAI v1 API Guide	https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle
Azure Responses API Migration	https://github.com/Azure-Samples/azure-openai-to-responses
Azure AI Projects SDK	https://learn.microsoft.com/en-us/python/api/overview/azure/ai-projects-readme
Azure OpenAI Reference	https://learn.microsoft.com/en-us/azure/ai-services/openai/reference
Migrate to OpenAI SDK	https://learn.microsoft.com/en-us/azure/foundry/how-to/model-inference-to-openai-migration
OpenAI SDK (PyPI)	https://pypi.org/project/openai/

---

Related Skills

Skill	Purpose
coding-openai-api	Direct OpenAI API patterns (non-Azure)
coding-aws-bedrock	AWS alternative for foundation model hosting
coding-langchain	Cross-provider orchestration including Azure OpenAI