# Azure OpenAI

Message the models deployed in an Azure OpenAI (Microsoft Foundry) resource, ask about images, and create embeddings.

## Connect Azure OpenAI

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `azure openai` and choose **Azure OpenAI**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Endpoint · Required**: The resource’s address: https://\<resource>.openai.azure.com or https://\<resource>.services.ai.azure.com. It must be reachable from the internet: a private endpoint or private address is refused unless the installation allows private networks.
- **API Key · Optional**: KEY 1 or KEY 2 of the resource. Leave empty to sign in with a Microsoft Entra app (the three fields below).
- **API Version · Optional**: Leave empty for the v1 API. Set a dated version (such as 2024-10-21) to use the older deployment URLs.
- **Directory (tenant) ID · Optional**: Only for a Microsoft Entra app: the Directory (tenant) ID on the app’s overview page (a GUID).
- **Application (client) ID · Optional**: Only for a Microsoft Entra app: its Application (client) ID.
- **Client secret · Optional**: Only for a Microsoft Entra app: a client secret’s value (Certificates & secrets).

Enter the resource’s endpoint and one of its keys: Azure portal → the Azure OpenAI or Foundry resource → Keys and Endpoint (or Foundry → the project’s overview).

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in Azure OpenAI

Add an **Azure OpenAI** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Text](https://docs.gorunner.io/apps/azure-openai#fields-f-text): Message a Model
- [Image](https://docs.gorunner.io/apps/azure-openai#fields-f-image): Analyze Image
- [Embedding](https://docs.gorunner.io/apps/azure-openai#fields-f-embedding): Create Embeddings
- [Model](https://docs.gorunner.io/apps/azure-openai#fields-f-model): Get Many

To start a workflow from Azure OpenAI, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Azure OpenAI can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Azure OpenAI says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Azure OpenAI is `pieceId: "azureopenai"` with `actionId: "azureopenai"`, set by `resource` and an `operation_…` field, such as `operation_embedding`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It reads from outside without changing anything (`reads_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Azure OpenAI › Text

### Message a Model

- **Deployment · Required**: The model deployment that answers. The deployment's name as it is in Foundry → Deployments (not the model's name, unless they are the same).
- **Prompt · Required**: What to ask or tell the model.
- **System Message · Optional**: Standing instructions for the model: its role, tone and rules. Optional.
- **Earlier Messages · Optional**: Earlier turns of the conversation, oldest first, sent before the prompt: [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
- **Reasoning Effort · Optional**: How hard a reasoning model (o-series, GPT-5) thinks before it answers. Leave at Default for other models: they refuse it. Options: Default, Minimal, Low, Medium, High. Default: Default.
- **Output Format · Optional**: Text, or JSON the step parses for later steps (under json). For a JSON object, say in the prompt what the JSON should hold. Options: Text, JSON object, JSON matching a schema. Default: Text.
- **JSON Schema · Required**: The JSON Schema the answer must match, such as {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}. Shows when **Output Format** is **JSON matching a schema**.
- **Max Tokens · Optional**: The most tokens the answer may use (reasoning included on reasoning models). Empty uses the model's default.
- **Temperature · Optional**: 0–2: lower is more focused and repeatable, higher more varied. Empty uses the model's default.
- **Top P · Optional**: 0–1: sample only from the most likely tokens whose probabilities add up to this. Change this or Temperature, not both.
- **Stop Sequences · Optional**: Text that ends the answer when the model writes it, one per line (at most 4).
- **Tools · Optional**: Functions the model may ask to call, as a list: [{"type":"function","function":{"name":"get_weather","description":"…","parameters":{…}}}]. The calls it asks for are in tool_calls; this step does not call them.
- **More Options · Optional**: Other request fields Azure OpenAI documents for chat completions, as JSON (such as {"seed": 7}). They are added to the request as written.

### Azure OpenAI › Image

### Analyze Image

- **Deployment · Required**: A deployment of a model that reads images. The deployment's name as it is in Foundry → Deployments (not the model's name, unless they are the same).
- **Question · Required**: What to ask about the images.
- **System Message · Optional**: Standing instructions for the model: its role, tone and rules. Optional.
- **Earlier Messages · Optional**: Earlier turns of the conversation, oldest first, sent before the prompt: [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
- **Image URLs · Optional**: Links to the images, one per line (https:// or data: URLs). Azure fetches links itself; a file is sent with the request.
- **Image File · Optional**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). JPEG, PNG, GIF or WebP. Use this, Image URLs, or both.
- **Reasoning Effort · Optional**: How hard a reasoning model (o-series, GPT-5) thinks before it answers. Leave at Default for other models: they refuse it. Options: Default, Minimal, Low, Medium, High. Default: Default.
- **Output Format · Optional**: Text, or JSON the step parses for later steps (under json). For a JSON object, say in the prompt what the JSON should hold. Options: Text, JSON object, JSON matching a schema. Default: Text.
- **JSON Schema · Required**: The JSON Schema the answer must match, such as {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}. Shows when **Output Format** is **JSON matching a schema**.
- **Max Tokens · Optional**: The most tokens the answer may use (reasoning included on reasoning models). Empty uses the model's default.
- **Temperature · Optional**: 0–2: lower is more focused and repeatable, higher more varied. Empty uses the model's default.
- **Top P · Optional**: 0–1: sample only from the most likely tokens whose probabilities add up to this. Change this or Temperature, not both.
- **Stop Sequences · Optional**: Text that ends the answer when the model writes it, one per line (at most 4).
- **More Options · Optional**: Other request fields Azure OpenAI documents for chat completions, as JSON (such as {"seed": 7}). They are added to the request as written.

### Azure OpenAI › Embedding

### Create Embeddings

- **Deployment · Required**: A deployment of an embedding model (text-embedding-3-small, …). The deployment's name as it is in Foundry → Deployments (not the model's name, unless they are the same).
- **Texts · Required**: The text to embed, or a list of texts from an earlier step (one vector per text, at most 2048).
- **Dimensions · Optional**: How many numbers each vector has (text-embedding-3 models can shorten theirs). Empty uses the model's size.

### Azure OpenAI › Model

### Get Many

- **Return All · Optional**: Read every model, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many models to return (1–1000). Default: 100. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/azure-openai