Microsoft Foundry SDKs and Endpoints

Learn about Microsoft Foundry SDKs, endpoints, and how to choose the right SDK for your AI application development needs.

Microsoft Foundry SDKs and Endpoints

Microsoft Foundry provides unified access to models, agents, and tools through multiple SDKs and endpoints. This guide helps you choose the right SDK for your scenario.

SDK Overview

SDK	Purpose	Endpoint
Foundry SDK	Foundry-specific capabilities with OpenAI-compatible interfaces	https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
OpenAI SDK	Latest OpenAI models with full OpenAI API surface	https://<resource-name>.openai.azure.com/openai/v1
Foundry Tools SDKs	Prebuilt AI services (Vision, Speech, Language, etc.)	Service-specific endpoints
Agent Framework	Multi-agent orchestration in code (cloud-agnostic)	Uses project endpoint via Foundry SDK

Choosing Your SDK

Foundry SDK

Use when building apps with:

• Agents and agent orchestration
• Evaluations and testing
• Foundry-specific features
• Unified access to multiple services

OpenAI SDK

Use when you need:

• Maximum OpenAI compatibility
• Direct access to Azure OpenAI models
• Latest OpenAI features
• Existing OpenAI SDK code

Foundry Tools SDKs

Use when working with:

• Computer Vision
• Speech services
• Content Safety
• Document Intelligence
• Language services

Agent Framework

Use when building:

• Multi-agent systems in code
• Local orchestration workflows
• Cloud-agnostic applications
• Complex agent coordination

Foundry SDK

The Foundry SDK connects to a single project endpoint that provides access to all Foundry capabilities.

Installation

Python

# Stable (Foundry classic)
pip install openai azure-identity azure-ai-projects==1.0.0

# Preview (Foundry new)
pip install --pre azure-ai-projects azure-identity openai

Authentication

The Foundry SDK uses Microsoft Entra ID authentication via DefaultAzureCredential:

Python

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    credential=DefaultAzureCredential(),
)

Using the Foundry SDK

The SDK exposes two client types:

Project Client

Use for Foundry-native operations like listing connections and retrieving project properties.

Python

# List connections
connections = project.connections.list()
for connection in connections:
    print(f"Connection: {connection.name}")

# Get project properties
properties = project.properties.get()
print(f"Project: {properties.name}")

OpenAI-Compatible Client

Use for agents, evaluations, and model inference.

Python

# Get OpenAI client from project
models = project.get_openai_client(api_version="2024-10-21")

# Create chat completion
response = models.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Explain quantum computing in simple terms"},
    ],
)

print(response.choices[0].message.content)

What You Can Do with the Foundry SDK

• Access Foundry Models (Azure OpenAI and Foundry Direct models)
• Create and manage agents
• Run cloud evaluations
• Enable application tracing
• Fine-tune models
• Get endpoints and keys for Foundry Tools

OpenAI SDK

Use the OpenAI SDK for direct access to Azure OpenAI models with full OpenAI API compatibility.

Installation and Usage

Python

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource-name>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "What is the speed of light?"}
    ]
)

print(response.choices[0].message.content)

Foundry Tools SDKs

Foundry Tools (formerly Azure AI Services) provide specialized AI capabilities through dedicated SDKs.

Endpoints by Service

Service	Endpoint Format
Computer Vision, Language, Translation	https://<resource-name>.cognitiveservices.azure.com/
Speech to Text	https://<region>.stt.speech.microsoft.com
Text to Speech	https://<region>.tts.speech.microsoft.com
Text Translation	https://api.cognitive.microsofttranslator.com/

Example: Content Safety

Python

from azure.ai.contentsafety import ContentSafetyClient
from azure.identity import DefaultAzureCredential

client = ContentSafetyClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential()
)

result = client.analyze_text(
    text="Sample text to analyze"
)
print(result)

Troubleshooting

Authentication Errors

If you see DefaultAzureCredential failed to retrieve a token:

1. Verify Azure CLI is authenticated:

   az account show
   az login  # if not logged in
   

2. Check RBAC role assignment:

   • Confirm you have at least the Azure AI User role on the Foundry project

3. For managed identity in production:

   • Ensure the managed identity has the appropriate role assigned

Endpoint Configuration Errors

If you see Connection refused or 404 Not Found:

• Verify resource and project names match your deployment
• Check endpoint URL format
• For custom subdomains, replace <resource-name> with your custom subdomain

SDK Version Mismatches

If code samples fail with AttributeError or ModuleNotFoundError:

• Check SDK version: pip show azure-ai-projects (Python)
• Verify you’re using the correct SDK version for your portal (2.x for new, 1.x for classic)
• Reinstall with correct version flags

Next Steps

Quickstart

Build your first Foundry application

Agents

Create intelligent agents

Models

Explore available models

Tools

Extend agent capabilities