# Azure OpenAI (/en/ai/platform/models/llm/azure-openai)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt).


Azure OpenAI service provides REST API access to OpenAI's powerful language models through Microsoft Azure's secure infrastructure.

## Sample configuration

The following example shows how to configure Azure OpenAI as the agent's LLM when you create or update an agent. For a complete example, see [Create an agent and start a session](/en/ai/platform/get-started/start-stop-agent#create-an-agent).

Azure OpenAI supports BYOK only. It isn't available in managed mode. Store your Azure OpenAI API key in a secret set, and refer to it from the agent. For details, see [Use your own provider keys](/en/ai/platform/build/use-your-own-keys).

**Python SDK**

```python
from agora_agent import Agent, AzureOpenAI, secret_ref

# client is your configured Agora client
agent = (
    Agent(client=client)
    .with_stt(...)  # configure your ASR vendor
    .with_llm(
        AzureOpenAI(
            api_key=secret_ref("support_prod", "azure_openai"),
            endpoint="https://your-resource-name.openai.azure.com",
            deployment_name="YOUR_DEPLOYMENT_NAME",
            api_version="AZURE_API_VERSION",
            model="gpt-4o-mini",
            max_history=32,
            failure_message="Please hold on a second.",
            system_messages=[
                {"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."}
            ],
        )
    )
    .with_tts(...)  # configure your TTS vendor
)
```

**TypeScript SDK**

```ts
import { Agent, AzureOpenAI, secretRef } from 'agora-agents';

// client is your configured Agora client
const agent = new Agent({ client })
  .withStt(/* configure your ASR vendor */)
  .withLlm(
    new AzureOpenAI({
      apiKey: secretRef('support_prod', 'azure_openai'),
      endpoint: 'https://your-resource-name.openai.azure.com',
      deploymentName: 'YOUR_DEPLOYMENT_NAME',
      apiVersion: 'AZURE_API_VERSION',
      model: 'gpt-4o-mini',
      maxHistory: 32,
      failureMessage: 'Please hold on a second.',
      systemMessages: [
        { role: 'system', content: 'You are a friendly support agent for Acme. Keep your answers short.' },
      ],
    }),
  )
  .withTts(/* configure your TTS vendor */);
```

**Go SDK**

```go
// client is your configured Agora client
maxHistory := 32
agent := agentkit.NewAgent(client).
	WithStt( /* configure your ASR vendor */ ).
	WithLlm(vendors.NewAzureOpenAI(vendors.AzureOpenAIOptions{
		APIKey:         agentkit.SecretRef("support_prod", "azure_openai"),
		Endpoint:       "https://your-resource-name.openai.azure.com",
		DeploymentName: "YOUR_DEPLOYMENT_NAME",
		APIVersion:     "AZURE_API_VERSION",
		Model:          "gpt-4o-mini",
		MaxHistory:     &maxHistory,
		FailureMessage: "Please hold on a second.",
		SystemMessages: []map[string]interface{}{
			{"role": "system", "content": "You are a friendly support agent for Acme. Keep your answers short."},
		},
	})).
	WithTts( /* configure your TTS vendor */ )
```

**REST API**

Set `credential.mode` to `byok` and `credential.fields.api_key` to a reference to the key. In the following example, the key is stored as `azure_openai` in the `support_prod` set:

```json
"llm": {
  "credential": {
    "mode": "byok",
    "fields": {
      "api_key": "$secrets.support_prod.azure_openai"
    }
  },
  "vendor": "azure",
  "style": "openai",
  "model": "gpt-4o-mini",
  "url": "https://your-resource-name.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=AZURE_API_VERSION",
  "max_history": 32,
  "failure_message": "Please hold on a second."
}
```

Set the system prompt and the greeting with the agent's `instructions` and `greeting`, not in the `llm` block.

## Key parameters

The `llm` block takes the following fields. In the SDKs, the LLM class sets them from its options. The SDK builds the endpoint URL from the resource endpoint, the deployment name, and the API version, and sets the vendor to `azure`.

**llm**

**`vendor` (string) required**

Set to `azure`.

**`credential` (object) required**

Set `mode` to `byok` and `fields.api_key` to a `$secrets.<set>.<key>` reference to your Azure OpenAI API key. Find your API key in the Azure portal under your OpenAI resource.

**`style` (string) optional**

Set to `openai`.

**`model` (string) required**

Use the deployment name you created in Azure, not the base model name.

**`url` (string) required**

Replace `your-resource-name` with your Azure resource name and `YOUR_DEPLOYMENT_NAME` with your model deployment name.

For complete `llm` block options, see [Create an agent](/en/api-reference/api-ref/conversational-ai/platform/create-agent). For advanced configuration options, deployment setup, and detailed parameter descriptions, see the [Azure OpenAI API documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).