Use with Microsoft Foundry

Prerequisites

• A Microsoft Foundry project or an Azure OpenAI resource with a deployed model (e.g., gpt-4o-mini)
• The resource endpoint:
  • Foundry project endpoint (recommended): https://<resource>.services.ai.azure.com/api/projects/<project>
  • Classic Azure OpenAI endpoint (legacy): https://<resource>.openai.azure.com/
• Either an API key or Microsoft Entra ID credentials

Python

# API key auth
pip install prompty[jinja2,foundry]

# Entra ID auth (adds azure-identity)
pip install prompty[jinja2,foundry] azure-identity

TypeScript

npm install @prompty/core @prompty/foundry

C#

dotnet add package Prompty.Core --prerelease
dotnet add package Prompty.Foundry --prerelease

Rust

cargo add prompty prompty-foundry

Migrating from Azure OpenAI?

If your .prompty files use provider: azure, they still work — it’s a deprecated alias for provider: foundry. Update when convenient. Similarly, pip install prompty[azure] still works as an alias for prompty[foundry].

---

Option A: API Key Authentication

The simplest approach — use an API key from the Azure AI Foundry portal or Azure Portal.

1. Write the .prompty File

Create foundry-chat.prompty:

---
name: foundry-chat
description: Chat completion with Microsoft Foundry (API key)
model:
  id: gpt-4o-mini
  provider: foundry
  apiType: chat
  connection:
    kind: key
    endpoint: ${env:AZURE_AI_PROJECT_ENDPOINT}
    apiKey: ${env:AZURE_AI_PROJECT_KEY}
  options:
    temperature: 0.7
    maxOutputTokens: 1024
inputs:
  - name: question
    kind: string
    default: What is Microsoft Foundry?
---
system:
You are a helpful assistant. Answer concisely.

user:
{{question}}

Note

model.id is the deployment name, not the base model name. If your deployment is called my-gpt4o, use id: my-gpt4o.

2. Run It

Python

import prompty

result = prompty.invoke(
    "foundry-chat.prompty",
    inputs={"question": "What services does Microsoft Foundry offer?"},
)
print(result)

TypeScript

import { invoke } from "@prompty/core";
import "@prompty/foundry";

const result = await invoke("foundry-chat.prompty", {
  question: "What services does Microsoft Foundry offer?",
});

console.log(result);

C#

using Prompty.Core;

var result = await Pipeline.InvokeAsync(
    "foundry-chat.prompty",
    new() { ["question"] = "What services does Microsoft Foundry offer?" }
);

Console.WriteLine(result);

Rust

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_foundry::register();

    let result = prompty::invoke_from_path(
        "foundry-chat.prompty",
        Some(&json!({ "question": "What services does Microsoft Foundry offer?" })),
    ).await?;
    println!("{result}");
    Ok(())
}

3. Environment Setup

# .env — Foundry project endpoint (recommended)
AZURE_AI_PROJECT_ENDPOINT=https://my-resource.services.ai.azure.com/api/projects/my-project
AZURE_AI_PROJECT_KEY=abc123...

# .env — Classic Azure OpenAI endpoint (legacy, also works)
# AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
# AZURE_OPENAI_API_KEY=abc123...

---

Option B: Microsoft Entra ID Authentication

For production workloads, use Microsoft Entra ID — no API keys to manage or rotate. This section covers two approaches:

• DefaultAzureCredential — convenient for local development; automatically discovers your Azure CLI, VS Code, or managed identity credentials.
• ManagedIdentityCredential — recommended for deployed services (App Service, Container Apps, AKS, Functions). Explicit, no fallback chain, no risk of accidentally using developer credentials in production.

Which credential should I use?

Use DefaultAzureCredential during development — it finds your Azure CLI or VS Code login automatically. For production deployments, switch to ManagedIdentityCredential to avoid ambiguous credential chains. See Microsoft’s authentication best practices for details.

1. Write the .prompty File

Create foundry-chat-aad.prompty:

---
name: foundry-chat-aad
description: Chat completion with Microsoft Foundry (Microsoft Entra ID)
model:
  id: gpt-4o-mini
  provider: foundry
  apiType: chat
  connection:
    kind: reference
    name: foundry_default
  options:
    temperature: 0.7
    maxOutputTokens: 1024
inputs:
  - name: question
    kind: string
    default: What is Microsoft Foundry?

Tip

kind: reference tells Prompty to look up the connection by name at runtime. This keeps credentials out of the .prompty file entirely.

2. Register the Connection and Run (Local Development)

During development, DefaultAzureCredential automatically finds your Azure CLI or VS Code login:

Python

import os
from azure.identity import DefaultAzureCredential
import prompty

# Register the named connection before loading the prompt
prompty.register_connection(
    "foundry_default",
    {
        "endpoint": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        "credential": DefaultAzureCredential(),
    },
)

result = prompty.invoke(
    "foundry-chat-aad.prompty",
    inputs={"question": "What is Microsoft Foundry?"},
)
print(result)

TypeScript

import { invoke, registerConnection } from "@prompty/core";
import "@prompty/foundry";
import { DefaultAzureCredential } from "@azure/identity";

registerConnection("foundry_default", {
  endpoint: process.env.AZURE_AI_PROJECT_ENDPOINT!,
  credential: new DefaultAzureCredential(),
});

const result = await invoke("foundry-chat-aad.prompty", {
  question: "What is Microsoft Foundry?",
});

console.log(result);

C#

using Azure.Identity;
using Prompty.Core;

// DefaultAzureCredential finds your Azure CLI / VS Code login
var result = await Pipeline.InvokeAsync(
    "foundry-chat-aad.prompty",
    new() { ["question"] = "What is Microsoft Foundry?" }
);

Console.WriteLine(result);

Note

The Prompty.Foundry package uses Azure.Identity.DefaultAzureCredential under the hood when the connection kind is reference. No manual credential registration is needed in C#.

Rust

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_foundry::register();

    // Register the named connection before loading the prompt
    prompty::register_connection(
        "foundry_default",
        json!({
            "endpoint": std::env::var("AZURE_AI_PROJECT_ENDPOINT")?,
            "credential": "default",
        }),
    );

    let result = prompty::invoke_from_path(
        "foundry-chat-aad.prompty",
        Some(&json!({ "question": "What is Microsoft Foundry?" })),
    ).await?;
    println!("{result}");
    Ok(())
}

3. Production Deployment: Use Managed Identity

Don't use DefaultAzureCredential in production

DefaultAzureCredential tries multiple credential sources in order. In a deployed environment, this can cause silent fallbacks to unexpected credentials (e.g., developer tools left on a VM). Use ManagedIdentityCredential directly for production services. See Microsoft’s authentication best practices.

Step 1: Enable Managed Identity on your Azure hosting resource:

# App Service
az webapp identity assign --name <app-name> --resource-group <rg>

# Container Apps
az containerapp identity assign --name <app-name> --resource-group <rg> --system-assigned

# Azure Kubernetes Service (pod identity)
az aks update --name <cluster> --resource-group <rg> --enable-oidc-issuer --enable-workload-identity

Step 2: Assign the RBAC role — grant only what’s needed (principle of least privilege):

az role assignment create \
  --assignee <managed-identity-object-id> \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<resource>

Note

Use the narrowest scope possible. Assigning the role at the resource level (not subscription or resource group) follows the principle of least privilege.

Step 3: Use ManagedIdentityCredential in your code:

Python

import os
from azure.identity import ManagedIdentityCredential
import prompty

prompty.register_connection(
    "foundry_default",
    {
        "endpoint": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        "credential": ManagedIdentityCredential(),
    },
)

result = prompty.invoke(
    "foundry-chat-aad.prompty",
    inputs={"question": "What is Microsoft Foundry?"},
)
print(result)

TypeScript

import { invoke, registerConnection } from "@prompty/core";
import "@prompty/foundry";
import { ManagedIdentityCredential } from "@azure/identity";

registerConnection("foundry_default", {
  endpoint: process.env.AZURE_AI_PROJECT_ENDPOINT!,
  credential: new ManagedIdentityCredential(),
});

const result = await invoke("foundry-chat-aad.prompty", {
  question: "What is Microsoft Foundry?",
});

console.log(result);

C#

using Azure.Identity;
using Prompty.Core;

// For production: explicitly use ManagedIdentityCredential
Pipeline.RegisterConnection("foundry_default", new Dictionary<string, object>
{
    ["endpoint"] = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")!,
    ["credential"] = new ManagedIdentityCredential(),
});

var result = await Pipeline.InvokeAsync(
    "foundry-chat-aad.prompty",
    new() { ["question"] = "What is Microsoft Foundry?" }
);

Console.WriteLine(result);

Rust

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    prompty::register_defaults();
    prompty_foundry::register();

    // For production: use managed identity credential
    prompty::register_connection(
        "foundry_default",
        json!({
            "endpoint": std::env::var("AZURE_AI_PROJECT_ENDPOINT")?,
            "credential": "managed_identity",
        }),
    );

    let result = prompty::invoke_from_path(
        "foundry-chat-aad.prompty",
        Some(&json!({ "question": "What is Microsoft Foundry?" })),
    ).await?;
    println!("{result}");
    Ok(())
}

Dev/prod pattern

A common pattern is to switch credentials based on your environment:

import os
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential

credential = (
    ManagedIdentityCredential()
    if os.getenv("WEBSITE_INSTANCE_ID")  # Set automatically in App Service
    else DefaultAzureCredential()
)

This gives you seamless local development with Azure CLI and explicit managed identity in production — with no code changes at deploy time.

---

Comparing Authentication Options

	API Key (kind: key)	Entra ID — DefaultAzureCredential	Entra ID — ManagedIdentityCredential
Setup	Copy key from portal	az login or VS Code	Enable managed identity + RBAC
Security	Key in env var — can leak	Token-based — no static secret	Token-based — no static secret
Credential source	Static string	Auto-discovers (CLI, VS Code, MI, …)	Managed identity only — no fallbacks
Rotation	Manual	Automatic	Automatic
Best for	Quick prototyping	Local development	Production deployments

Caution

Never commit API keys to source control. Always use ${env:...} references or kind: reference connections.

---

Using a Shared Connection File

If multiple .prompty files share the same Foundry config, extract it into a JSON file and reference it with ${file:...}:

shared/foundry-connection.json:

{
  "kind": "key",
  "endpoint": "https://my-resource.services.ai.azure.com/api/projects/my-project",
  "apiKey": "${env:AZURE_AI_PROJECT_KEY}"
}

my-prompt.prompty:

---
name: shared-connection-demo
model:
  id: gpt-4o-mini
  provider: foundry
  connection: ${file:shared/foundry-connection.json}
---
system:
You are a helpful assistant.

user:
{{question}}

This avoids duplicating endpoint and auth config across prompts.

---

Environment Setup (Both Options)

.env

AZURE_AI_PROJECT_ENDPOINT=https://my-resource.services.ai.azure.com/api/projects/my-project
AZURE_AI_PROJECT_KEY=abc123...                # Only needed for API key auth

# Optional: specify deployment names per model type
AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4o-mini
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small