Azure AI Projects SDK for .NET: Setup, Usage & Best Practices

Azure AI Projects SDK for .NET provides high-level orchestration of Azure AI Foundry resources including agents, connections, datasets, deployments, evaluations, and indexes through a unified AIProjectClient. This skill enables .NET applications to manage entire AI project lifecycles—from data ingestion and model deployment through agent creation and evaluation—without manual Azure Portal configuration.

What This Skill Does

This SDK wraps Azure AI Foundry's project API with property-based access to different resource types: Agents for versioned agent management, Connections for Azure resource links, Datasets for training data, Deployments for model endpoints, Evaluations for quality metrics, and Indexes for vector search. The client also provides GetPersistentAgentsClient() to access low-level agent operations for fine-grained control.

The workflow centers on project-scoped resources. A project acts as a container for agents, data, and models with shared connections to Azure OpenAI, Azure AI Search, and storage accounts. You create agents referencing model deployments within the project, upload datasets to project-scoped storage, build indexes for RAG, and run evaluations against ground-truth data. All operations support versioning (datasets, agents, indexes) for reproducibility and rollback.

Unlike standalone SDKs (Azure.AI.OpenAI, Azure.AI.Agents.Persistent), the Projects SDK provides project-level abstractions. For example, Connections.GetConnection() retrieves pre-configured Azure resource links instead of requiring manual endpoint/credential management. Deployments list available models within the project scope, and evaluations run with project-managed compute without provisioning infrastructure.

Getting Started

Install the SDK:

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Configure environment variable:

export PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project-id>

Create a client:

using Azure.AI.Projects;
using Azure.Identity;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!),
    new DefaultAzureCredential()
);

Key Features

Unified Project Management: Single client for all project resources. No separate SDKs for agents, data, models—everything through AIProjectClient.

Connection Management: Retrieve pre-configured connections to Azure OpenAI, AI Search, storage, and databases without manual credential handling.

Versioned Datasets: Upload files or folders as versioned datasets. Reference specific versions in training jobs or agent tools.

Agent Operations: Create persistent agents via GetPersistentAgentsClient(), or use versioned agents (preview) with AIProjectClient.Agents for integrated tool support.

Evaluation Framework: Run evaluations against datasets with built-in evaluators (relevance, groundedness, coherence) using project-managed compute.

Index Management: Create and manage Azure AI Search indexes for RAG without leaving the SDK.

Deployment Discovery: List available model deployments within the project scope, filtered by publisher or capability.

Usage Examples

Get Persistent Agents Client and Create Agent:

using Azure.AI.Agents.Persistent;

var agentsClient = projectClient.GetPersistentAgentsClient();

var agent = await agentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Research Assistant",
    instructions: "You help with research tasks."
);

var thread = await agentsClient.Threads.CreateThreadAsync();
await agentsClient.Messages.CreateMessageAsync(
    thread.Id, MessageRole.User, "Summarize quantum computing");

var run = await agentsClient.Runs.CreateRunAsync(thread.Id, agent.Id);

// Poll and retrieve response...

List Connections:

foreach (var conn in projectClient.Connections.GetConnections())
{
    Console.WriteLine($"{conn.Name}: {conn.ConnectionType}");
}

var azureOpenAI = projectClient.Connections.GetConnection("AzureOpenAI", includeCredentials: true);

Upload Dataset:

var dataset = projectClient.Datasets.UploadFile(
    name: "training-data",
    version: "1.0",
    filePath: "./data/train.jsonl",
    connectionName: "WorkspaceStorage"
);

List Model Deployments:

foreach (var deployment in projectClient.Deployments.GetDeployments())
{
    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");
}

// Filter by publisher
foreach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "OpenAI"))
{
    Console.WriteLine(deployment.Name);
}

Create Azure AI Search Index:

using Azure.AI.Projects.Models;

var searchIndex = new AzureAISearchIndex(
    aiSearchConnectionName: "AISearch",
    aiSearchIndexName: "documents-index")
{
    Description = "Document search index"
};

var createdIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(
    name: "doc-index",
    version: "1.0",
    index: searchIndex
);

Run Evaluation:

var evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);
evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));

var evaluation = new Evaluation(
    data: new InputDataset("<dataset-id>"),
    evaluators: new Dictionary<string, EvaluatorConfiguration>
    {
        { "relevance", evaluatorConfig }
    }
)
{
    DisplayName = "Quality Check"
};

var result = projectClient.Evaluations.Create(evaluation);
Console.WriteLine($"Evaluation Status: {result.Status}");

Best Practices

Use DefaultAzureCredential: Prefer managed identities over API keys. Configure in App Service or AKS for automatic credential injection.

Version All Assets: Always specify versions for datasets, indexes, and agents. Enables rollback and reproducibility.

Reuse Connections: Call GetConnection() once and cache results. Reduces API calls and latency.

Filter Deployments: Use modelPublisher parameter when listing deployments to reduce response size and query time.

Handle Pagination: Use AsyncPageable for list operations. Don't assume all results fit in one page.

Clean Up Resources: Delete unused datasets, agents, and indexes to avoid quota exhaustion.

Poll Evaluations: Evaluations are long-running operations. Poll status until Completed before accessing results.

When to Use / When NOT to Use

Use this skill when:

• You're building .NET applications managing Azure AI Foundry projects


• You need unified access to agents, data, models, and evaluations


• You're orchestrating multi-step AI workflows


• You want project-scoped resource management


• You're implementing MLOps for AI applications


• You need versioned datasets and agents


• You're integrating Azure OpenAI and Azure AI Search

Avoid this skill when:

• You only need Azure OpenAI (use Azure.AI.OpenAI directly)


• You're working in Python or Java (use language-specific SDKs)


• You need standalone agent operations without projects


• You're on AWS or GCP (use native services)


• You prefer Azure Portal for manual resource management

Related Skills

• azure-ai-projects-py: Python version of this SDK
• azure-ai-projects-java: Java version of this SDK
• azure-ai-openai-dotnet: Azure OpenAI client for .NET
• azure-ai-agents-persistent-dotnet: Low-level agent operations

Source

Maintained by Microsoft. View on GitHub