Using SDKs and APIs

Module: Plan and Manage an Azure AI Solution

Section: Planning and Deploying Foundry Services

Lesson: Using SDKs and APIs for Azure AI Foundry

Introduction: Why SDKs and APIs Matter in AI Development

When we talk about Azure AI Foundry (formerly Azure AI Studio), we are discussing a unified environment for building, testing, and deploying artificial intelligence applications. While the graphical user interface in the Azure portal is excellent for exploration and initial prototyping, professional-grade AI solutions are almost always built through code. This is where Software Development Kits (SDKs) and Application Programming Interfaces (APIs) become the backbone of your development lifecycle.

Understanding how to interact with Azure AI services programmatically is not just about convenience; it is about reproducibility, scalability, and integration. When you use an SDK, you are essentially wrapping the complex REST API calls that Azure services expect into manageable, language-specific objects. This allows you to integrate AI capabilities directly into your existing CI/CD pipelines, automate the deployment of models, and manage complex workflows that would be impossible to coordinate manually through a web dashboard.

In this lesson, we will explore the mechanics of using the Azure AI SDKs, specifically focusing on the Python ecosystem, which is the industry standard for AI development. We will move beyond basic "hello world" examples to look at how to manage project resources, deploy models, and interact with inferencing endpoints in a production-ready manner.

The Architecture of Azure AI Foundry Interactions

To effectively use the SDK, you must first understand the relationship between your local environment and the Azure cloud. Azure AI Foundry is built on top of Azure Machine Learning resources, which means that when you interact with the AI Foundry API, you are often interacting with underlying Azure Resource Manager (ARM) providers.

The Role of the Azure AI Client

The primary entry point for developers is the azure-ai-ml Python package (or the newer azure-ai-projects SDK, which is becoming the standard for AI Foundry-specific tasks). These libraries provide a client object—usually called MLClient or AIProjectClient—that acts as your authenticated gateway to the cloud.

When you instantiate this client, you provide your subscription ID, resource group name, and workspace name. Once authenticated, the client allows you to perform CRUD (Create, Read, Update, Delete) operations on your AI assets, such as models, datasets, and deployments.

Callout: SDK vs. REST API While the SDK is often the preferred choice for Python developers, the underlying mechanism is always a REST API. The SDK simplifies authentication, handles retry logic, manages JSON serialization/deserialization, and provides type hinting. Use the SDK for application logic and automation; reserve raw REST API calls for scenarios where you are working in a language without an official SDK or when you need to bypass abstractions for highly specific, low-level performance tuning.

Setting Up Your Development Environment

Before writing code, you need a controlled environment. Never install SDKs directly into your global Python environment. Instead, use virtual environments or Conda environments to manage dependencies.

Step-by-Step Environment Preparation

1. Create a Virtual Environment: Open your terminal and run python -m venv .venv. This creates a local folder to store your dependencies.
2. Activate the Environment: On Windows, run .venv\Scripts\activate. On Linux or macOS, run source .venv/bin/activate.
3. Install the Required Libraries: For modern Azure AI Foundry development, you should install the core library: pip install azure-ai-projects azure-identity

The azure-identity package is crucial because it provides the DefaultAzureCredential class. This class is a "magic" utility that looks for credentials in your environment in a specific order: environment variables, managed identity, or your local Azure CLI login.

Note: Always use DefaultAzureCredential. Hardcoding keys or connection strings in your source code is a major security risk that can lead to credential leakage. By using identity-based authentication, you ensure that your code only has the permissions granted to the user or service principal running the process.

Working with the Azure AI Project Client

The AIProjectClient is the primary interface for interacting with the Azure AI Foundry service. It provides a structured way to manage your project, which acts as a container for your AI assets and configuration.

Initializing the Client

To initialize the client, you need the connection string for your project, which can be found in the Azure AI Foundry portal settings.

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

# It is best practice to load these from environment variables
project_connection_string = os.environ.get("PROJECT_CONNECTION_STRING")

# Initialize the client
client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=project_connection_string
)

print(f"Connected to project: {client.project_name}")

Understanding Project Assets

Inside your project, you deal with several key entities:

• Models: These are the AI models (like GPT-4, Llama 3, or custom trained models) that you plan to use.
• Connections: These represent the secrets and endpoints required to access external services like Azure OpenAI or search indices.
• Deployments: These are the actual running instances of a model that can accept inference requests.

Deploying Models Programmatically

Manual deployment is fine for a one-off experiment, but if you are managing a fleet of models, you need to automate the deployment process. The SDK allows you to define the configuration of your endpoint and deployment in code, ensuring that your production environment is identical to your staging environment.

Defining a Deployment

To deploy a model, you typically need to specify the model ID, the virtual machine SKU (e.g., Standard_DS3_v2), and the capacity (number of instances).

from azure.ai.ml.entities import ManagedOnlineDeployment, ManagedOnlineEndpoint

# Define the endpoint
endpoint = ManagedOnlineEndpoint(
    name="my-ai-endpoint",
    description="Endpoint for customer service chatbot",
    auth_mode="key"
)

# Define the deployment
deployment = ManagedOnlineDeployment(
    name="blue-deployment",
    endpoint_name="my-ai-endpoint",
    model="azureml:my-registered-model:1",
    instance_type="Standard_DS3_v2",
    instance_count=1
)

# Create these using the MLClient (not the AIProjectClient)
# ml_client.online_endpoints.begin_create_or_update(endpoint)
# ml_client.online_deployments.begin_create_or_update(deployment)

Best Practices for Deployments

• Blue-Green Deployments: Never update your production deployment in place. Always create a new deployment (Green) alongside the existing one (Blue), test it, and then shift traffic.
• Auto-scaling: Configure your deployment for auto-scaling based on CPU or request latency metrics to manage costs effectively.
• Environment Variables: Inject configuration settings (like temperature or system prompts) via environment variables rather than hardcoding them into the model deployment script.

Inference and Interacting with Models

Once your model is deployed, the most common task is sending data to it and receiving predictions. This is where you interact with the model's inference endpoint.

Handling Requests

When using the SDK, you often interact with the chat or completions APIs. If you are using Azure OpenAI, the openai Python library is the standard choice, but it is configured to talk to your Azure AI endpoint.

from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-15-preview",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"]
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the importance of SDKs in AI."}
    ]
)

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

Warning: Be mindful of token limits and costs. Every request sent to a large language model incurs a cost based on the number of tokens processed. Always implement a retry strategy (e.g., using the tenacity library) to handle transient network errors or rate limiting (429 Too Many Requests) gracefully.

Managing Connections and Security

Azure AI Foundry uses "Connections" to securely store credentials for services like Azure OpenAI, Azure AI Search, and Bing Search. Using the SDK to manage these connections is safer than storing keys in your application's config.json.

Accessing Connections

You can fetch existing connections using the AIProjectClient:

# List all connections available to the project
connections = client.connections.list()

for conn in connections:
    print(f"Connection Name: {conn.name}, Category: {conn.category}")

Security Considerations

• Managed Identities: Whenever possible, use Managed Identities to access Azure resources. This removes the need to manage API keys entirely, as the identity of your application is managed by Azure Active Directory.
• Key Vault Integration: If you must use secrets, store them in Azure Key Vault and use the SDK to retrieve them at runtime. Never commit secrets to your version control system.
• Network Isolation: In highly regulated environments, use Private Endpoints to ensure that your traffic between your application and the AI service never traverses the public internet.

Comparison of Methods

To help you choose the right approach for your project, refer to the following table:

Common Pitfalls and How to Avoid Them

Even experienced developers often run into recurring issues when working with the Azure AI SDKs. Recognizing these early will save you hours of debugging.

1. The "Rate Limit" Trap

When deploying applications that perform high-volume inference, you will hit rate limits. Many developers attempt to fix this by simply increasing the deployment capacity. A better approach is to implement an asynchronous request pattern or a message queue (like Azure Service Bus) to buffer requests and smooth out traffic spikes.

2. Dependency Hell

Azure SDKs are frequently updated. If you mix and match versions of azure-ai-ml, azure-ai-projects, and azure-identity, you may encounter runtime errors.

• Solution: Use a requirements.txt or pyproject.toml file to pin your dependencies to specific versions. Regularly update them in a staging environment to ensure compatibility before pushing to production.

3. Authentication Context Mismatch

A common error is running code locally that works perfectly, but failing when deployed to an Azure App Service or Function. This is usually because the local environment is using your personal Azure CLI login, while the deployed environment does not have the necessary permissions assigned to its Managed Identity.

• Solution: Always verify that your Managed Identity has the "Azure AI Developer" or "Cognitive Services User" role assigned in the Azure portal.

4. Ignoring Asynchronous Operations

Many SDK operations (like creating an endpoint) are "Long Running Operations" (LROs). If you do not wait for the operation to complete, your code will proceed to the next line and fail because the resource does not exist yet.

• Solution: Always use the begin_ prefix for methods that return a poller object, and call .result() on the poller to wait for completion.

Callout: The Power of Pollers When you see a method name starting with begin_ in the Azure SDK, it is an asynchronous operation. The method returns a "poller" object immediately. If you do not call .result() or .wait() on this object, your script will finish execution before the infrastructure is actually ready. This is the most common cause of "Resource Not Found" errors in deployment scripts.

Advanced: Extending Functionality with Custom Tools

Azure AI Foundry allows you to create "Tools" that can be used within your application logic. These might be custom Python functions that perform specific data transformations or call external APIs.

Packaging Your Code

You can package your custom code as a "Tool" in your AI project. This allows you to reference it in your flows or prompt templates.

# Example of a simple tool definition
def calculate_sentiment(text: str):
    # Logic to process text
    return {"sentiment": "positive", "score": 0.98}

By using the SDK, you can register these functions as tools within the AI Foundry project, making them discoverable and usable by other team members within the Studio interface.

Best Practices Checklist for AI Development

To ensure your solution is robust and maintainable, adopt these industry-standard practices:

• Version Control Everything: Your infrastructure-as-code (the deployment scripts) should live in the same repository as your application code.
• Structured Logging: Use the standard Python logging library. When calling Azure services, ensure you are logging request IDs so that you can troubleshoot with Microsoft support if an API call fails.
• Environment Parity: Your local dev environment, your integration test environment, and your production environment should use the same SDK versions and the same underlying Azure resource configurations.
• Fail Fast: Implement validation logic for inputs before sending them to the AI model. If the input is malformed, reject it locally rather than wasting credits on an API call that is destined to fail.
• Monitoring: Use Azure Monitor and Application Insights to track the latency and success rate of your API calls. If you see a spike in 5xx errors, you need to investigate the service health or your own request throttling.

Frequently Asked Questions (FAQ)

Q: Can I use the Azure AI SDKs with other cloud providers? A: No, the Azure AI SDKs are specifically designed to interface with the Azure Resource Manager and the Azure AI platform. If you are building a multi-cloud strategy, you should design an abstraction layer in your code that handles the specific requirements of each provider.

Q: How do I handle large datasets when using the SDK? A: Do not pass large datasets directly through the SDK calls. Instead, upload your data to an Azure Blob Storage container, and pass the URI (e.g., azureml://datastores/workspaceblobstore/paths/data.csv) to your deployment or training job.

Q: Is it better to use the OpenAI SDK or the Azure AI SDK? A: Use the OpenAI SDK if you are strictly interacting with chat or completion endpoints. Use the Azure AI SDK (Project Client) when you need to manage the lifecycle of the infrastructure, such as creating endpoints, managing connections, or deploying custom models.

Q: What is the recommended way to handle secrets in production? A: Always use Azure Key Vault. The SDK supports SecretClient which allows you to fetch keys at runtime. Never keep secrets in your code, environment variables, or configuration files.

Conclusion: Key Takeaways

Mastering the use of SDKs and APIs in Azure AI Foundry is the transition point from being an "AI enthusiast" to an "AI engineer." By moving away from the GUI and into code, you gain the ability to build repeatable, secure, and professional-grade systems.

Here are the key takeaways from this lesson:

1. Identity is Paramount: Always use DefaultAzureCredential and Managed Identities. Avoid hardcoding secrets at all costs.
2. Infrastructure as Code: Treat your model deployments and endpoint configurations as code. This ensures consistency across your development, test, and production environments.
3. Understand LROs: Recognize that many cloud operations are asynchronous. Use poller objects correctly to ensure your infrastructure is ready before your application attempts to use it.
4. Manage Dependencies: Use virtual environments and pinned dependency files to prevent "it works on my machine" syndromes when deploying to the cloud.
5. Monitor and Optimize: Use Application Insights and structured logging to keep an eye on your API performance, costs, and error rates.
6. Design for Failure: AI services are distributed systems. Always implement retry logic, circuit breakers, and graceful degradation in your application code.
7. Leverage the Ecosystem: Don't reinvent the wheel. Use the official azure-ai-projects and openai libraries, and follow the established patterns for authentication and resource management.

By following these principles, you will be well-equipped to plan, deploy, and manage sophisticated AI solutions that are not only powerful but also reliable and secure. As you continue your journey, keep exploring the documentation for the azure-ai-projects SDK, as this is where the most active development is occurring within the Azure AI ecosystem.