Azure.AI.Projects (.NET)

High-level SDK for Azure AI Foundry project operations including agents, connections, datasets, deployments, evaluations, and indexes.

Installation

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

Optional: For versioned agents with OpenAI extensions

dotnet add package Azure.AI.Projects.OpenAI --prerelease

Optional: For low-level agent operations

dotnet add package Azure.AI.Agents.Persistent --prerelease

Current Versions: GA v1.1.0, Preview v1.2.0-beta.5

Environment Variables

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project> MODEL_DEPLOYMENT_NAME=gpt-4o-mini CONNECTION_NAME=<your-connection-name> AI_SEARCH_CONNECTION_NAME=<ai-search-connection>

Authentication

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

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

Client Hierarchy

AIProjectClient ├── Agents → AIProjectAgentsOperations (versioned agents) ├── Connections → ConnectionsClient ├── Datasets → DatasetsClient ├── Deployments → DeploymentsClient ├── Evaluations → EvaluationsClient ├── Evaluators → EvaluatorsClient ├── Indexes → IndexesClient ├── Telemetry → AIProjectTelemetry ├── OpenAI → ProjectOpenAIClient (preview) └── GetPersistentAgentsClient() → PersistentAgentsClient

Core Workflows

1. Get Persistent Agents Client

// Get low-level agents client from project client PersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();

// Create agent PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync( model: "gpt-4o-mini", name: "Math Tutor", instructions: "You are a personal math tutor.");

// Create thread and run PersistentAgentThread thread = await agentsClient.Threads.CreateThreadAsync(); await agentsClient.Messages.CreateMessageAsync(thread.Id, MessageRole.User, "Solve 3x + 11 = 14"); ThreadRun run = await agentsClient.Runs.CreateRunAsync(thread.Id, agent.Id);

// Poll for completion do { await Task.Delay(500); run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id); } while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

// Get messages await foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id)) { foreach (var content in msg.ContentItems) { if (content is MessageTextContent textContent) Console.WriteLine(textContent.Text); } }

// Cleanup await agentsClient.Threads.DeleteThreadAsync(thread.Id); await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. Versioned Agents with Tools (Preview)

using Azure.AI.Projects.OpenAI;

// Create agent with web search tool PromptAgentDefinition agentDefinition = new(model: "gpt-4o-mini") { Instructions = "You are a helpful assistant that can search the web", Tools = { ResponseTool.CreateWebSearchTool( userLocation: WebSearchToolLocation.CreateApproximateLocation( country: "US", city: "Seattle", region: "Washington" ) ), } };

AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync( agentName: "myAgent", options: new(agentDefinition));

// Get response client ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

// Create response ResponseResult response = responseClient.CreateResponse("What's the weather in Seattle?"); Console.WriteLine(response.GetOutputText());

// Cleanup projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. Connections

// List all connections foreach (AIProjectConnection connection in projectClient.Connections.GetConnections()) { Console.WriteLine($"{connection.Name}: {connection.ConnectionType}"); }

// Get specific connection AIProjectConnection conn = projectClient.Connections.GetConnection( connectionName, includeCredentials: true);

// Get default connection AIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection( includeCredentials: false);

4. Deployments

// List all deployments foreach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments()) { Console.WriteLine($"{deployment.Name}: {deployment.ModelName}"); }

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

// Get specific deployment ModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. Datasets

// Upload single file FileDataset fileDataset = projectClient.Datasets.UploadFile( name: "my-dataset", version: "1.0", filePath: "data/training.txt", connectionName: connectionName);

// Upload folder FolderDataset folderDataset = projectClient.Datasets.UploadFolder( name: "my-dataset", version: "2.0", folderPath: "data/training", connectionName: connectionName, filePattern: new Regex(".*\.txt"));

// Get dataset AIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");

// Delete dataset projectClient.Datasets.Delete("my-dataset", "1.0");

6. Indexes

// Create Azure AI Search index AzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName) { Description = "Sample Index" };

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

// List indexes foreach (AIProjectIndex index in projectClient.Indexes.GetIndexes()) { Console.WriteLine(index.Name); }

// Delete index projectClient.Indexes.Delete(name: "my-index", version: "1.0");

7. Evaluations

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

// Create evaluation Evaluation evaluation = new Evaluation( data: new InputDataset("<dataset_id>"), evaluators: new Dictionary<string, EvaluatorConfiguration> { { "relevance", evaluatorConfig } } ) { DisplayName = "Sample Evaluation" };

// Run evaluation Evaluation result = projectClient.Evaluations.Create(evaluation: evaluation);

// Get evaluation Evaluation getResult = projectClient.Evaluations.Get(result.Name);

// List evaluations foreach (var eval in projectClient.Evaluations.GetAll()) { Console.WriteLine($"{eval.DisplayName}: {eval.Status}"); }

8. Get Azure OpenAI Chat Client

using Azure.AI.OpenAI; using OpenAI.Chat;

ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);

if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null) throw new InvalidOperationException("Invalid URI.");

uri = new Uri($"https://{uri.Host}");

AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential()); ChatClient chatClient = azureOpenAIClient.GetChatClient("gpt-4o-mini");

ChatCompletion result = chatClient.CompleteChat("List all rainbow colors"); Console.WriteLine(result.Content[0].Text);

Available Agent Tools

Tool Class Purpose

Code Interpreter CodeInterpreterToolDefinition

Execute Python code

File Search FileSearchToolDefinition

Search uploaded files

Function Calling FunctionToolDefinition

Call custom functions

Bing Grounding BingGroundingToolDefinition

Web search via Bing

Azure AI Search AzureAISearchToolDefinition

Search Azure AI indexes

OpenAPI OpenApiToolDefinition

Call external APIs

Azure Functions AzureFunctionToolDefinition

Invoke Azure Functions

MCP MCPToolDefinition

Model Context Protocol tools

Key Types Reference

Type Purpose

AIProjectClient

Main entry point

PersistentAgentsClient

Low-level agent operations

PromptAgentDefinition

Versioned agent definition

AgentVersion

Versioned agent instance

AIProjectConnection

Connection to Azure resource

AIProjectDeployment

Model deployment info

AIProjectDataset

Dataset metadata

AIProjectIndex

Search index metadata

Evaluation

Evaluation configuration and results

Best Practices

• Use DefaultAzureCredential for production authentication

• Use async methods (*Async ) for all I/O operations

• Poll with appropriate delays (500ms recommended) when waiting for runs

• Clean up resources — delete threads, agents, and files when done

• Use versioned agents (via Azure.AI.Projects.OpenAI ) for production scenarios

• Store connection IDs rather than names for tool configurations

• Use includeCredentials: true only when credentials are needed

• Handle pagination — use AsyncPageable<T> for listing operations

Error Handling

using Azure;

try { var result = await projectClient.Evaluations.CreateAsync(evaluation); } catch (RequestFailedException ex) { Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}"); }

Related SDKs

SDK Purpose Install

Azure.AI.Projects

High-level project client (this SDK) dotnet add package Azure.AI.Projects

Azure.AI.Agents.Persistent

Low-level agent operations dotnet add package Azure.AI.Agents.Persistent

Azure.AI.Projects.OpenAI

Versioned agents with OpenAI dotnet add package Azure.AI.Projects.OpenAI

Reference Links

Resource URL

NuGet Package https://www.nuget.org/packages/Azure.AI.Projects

API Reference https://learn.microsoft.com/dotnet/api/azure.ai.projects

GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects

Samples https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/samples