> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure OpenAI

> This page outlines how to use the Azure OpenAI integration for AI-powered actions in Cargo.

Azure OpenAI Service provides access to OpenAI's powerful language models through Microsoft Azure's enterprise-grade infrastructure. This integration allows you to use your Azure OpenAI deployments directly in Cargo workflows, ideal for organizations with compliance, data residency, or security requirements.

## How to set up Azure OpenAI

Azure OpenAI requires your own Azure credentials (BYOC). Cargo credits are not available for this integration.

### Prerequisites

Before connecting, ensure you have:

1. An active Azure subscription
2. An Azure OpenAI resource created in the Azure Portal
3. At least one model deployment in your Azure OpenAI resource

### Connection details

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Resource Name** | Your Azure OpenAI resource name (e.g., `my-company-openai`) |
| **API Key**       | Your Azure OpenAI API key from the Azure Portal             |
| **API Version**   | Optional. Defaults to `2024-08-01-preview`                  |

### Finding your credentials

#### Resource Name

1. Go to the [Azure Portal](https://portal.azure.com)
2. Navigate to your Azure OpenAI resource
3. The resource name is in the overview page and part of your endpoint URL
   * If your endpoint is `https://my-company-openai.openai.azure.com/`, your resource name is `my-company-openai`

#### API Key

1. In the Azure Portal, navigate to your Azure OpenAI resource
2. Click **Keys and Endpoint** under "Resource Management"
3. Copy **KEY 1** or **KEY 2**

<Tip>
  Find your API key and endpoint in the Azure Portal under your Azure OpenAI resource → **Keys and Endpoint**.
</Tip>

***

## Azure OpenAI actions

### Instruct

Send a prompt to an Azure OpenAI deployment and receive a text response.

**Use cases**

* **Content generation** – Generate personalized emails, messages, or content
* **Classification** – Categorize text into predefined categories
* **Summarization** – Summarize long text into concise summaries
* **Data extraction** – Extract structured data from unstructured text
* **Translation** – Translate text between languages
* **Analysis** – Analyze sentiment, intent, or other text properties

**Configuration**

| Field               | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Deployment Name** | The name of your Azure OpenAI deployment                |
| **Prompt**          | The prompt to send to the model                         |
| **System prompt**   | Optional system instructions                            |
| **Maximum tokens**  | Limit output length                                     |
| **Temperature**     | Control randomness (0 = deterministic, 2 = very random) |
| **Response format** | Text, JSON object, or JSON schema                       |

<Warning>
  Azure OpenAI uses **deployment names** instead of model names. You define these names when deploying models in the Azure Portal.
</Warning>

### Understanding deployments

Unlike standard OpenAI where you select models like `gpt-4o`, Azure OpenAI requires you to:

1. Deploy a model in the Azure Portal
2. Give it a custom deployment name (e.g., `my-gpt4o-deployment`)
3. Use that deployment name in Cargo

To find your deployment names:

1. Go to your Azure OpenAI resource in the Azure Portal
2. Click **Model deployments** in the left sidebar
3. Note the **Deployment name** for each model

### Response formats

Control how the model returns its response:

| Format          | Description                                       |
| --------------- | ------------------------------------------------- |
| **Text**        | Free-form text response (default)                 |
| **JSON object** | Response formatted as valid JSON                  |
| **JSON schema** | Response validated against a specific JSON schema |

<Tip>
  Use **JSON schema** when you need structured output with specific fields.
  Define your schema to ensure consistent, parseable responses.
</Tip>

#### Example JSON schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" },
    "summary": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["sentiment", "confidence", "summary"]
}
```

### Advanced settings

#### System prompt

Set instructions that guide the model's behavior across all prompts:

* Define the model's role or persona
* Set output format guidelines
* Provide context about your use case
* Establish constraints or rules

#### Temperature

Control the randomness of outputs:

| Temperature | Behavior                               |
| ----------- | -------------------------------------- |
| **0**       | Most deterministic, consistent outputs |
| **0.5-1**   | Balanced creativity and consistency    |
| **1-2**     | More creative, varied outputs          |

<Warning>
  For tasks requiring consistency (classification, extraction), use low
  temperature (0-0.3). For creative tasks (content generation), use higher
  temperature (0.7-1).
</Warning>

***

## API versions

Azure OpenAI requires an API version. Cargo defaults to `2024-08-01-preview`. If you need specific features, you can override it:

| Version              | Description              |
| -------------------- | ------------------------ |
| `2024-08-01-preview` | Latest preview (default) |
| `2024-06-01`         | Latest stable version    |
| `2024-02-01`         | Older stable version     |

***

## Troubleshooting

### "DeploymentNotFound" error

The deployment name you specified doesn't exist. Verify:

* The deployment name matches exactly as shown in the Azure Portal
* The deployment is in the same resource you configured

### "Unauthorized" error

Your credentials may be incorrect. Check that:

* Your API key is correct and hasn't been regenerated
* Your Azure OpenAI resource is active
* The API key has access to the specified resource