Azure Ai Projects Dotnet

by microsoft354361d83247MITListed Oct 8, 2026Updated Oct 8, 2026

Azure AI Projects SDK for .NET. High-level client for Azure AI Foundry projects including agents, connections, datasets, deployments, evaluations, and indexes. Use for AI Foundry project management, versioned agents, and orchestration. Triggers: "AI Projects", "AIProjectClient", "Foundry project", "versioned agents", "evaluations", "datasets", "connections", "deployments .NET".

FeaturedInstructions onlyAI & Agents
AI-generated overview

Documents the Azure AI Projects SDK for .NET to manage AI Foundry agents, connections, datasets, deployments, evaluations, and indexes.

What it does
Provides reference guidance and C# code samples for the Azure.AI.Projects client library. It covers authentication, client hierarchy, creating and running persistent and versioned agents with tools, and managing connections, deployments, datasets, indexes, and evaluations. It also lists available agent tools, key types, best practices, and error handling patterns.
When to use it
Use when writing or reviewing .NET code that works with Azure AI Foundry projects, such as creating versioned agents, running evaluations, or managing project connections, datasets, and deployments.
Requirements
Requires the .NET SDK with the Azure.AI.Projects package (plus Azure.Identity, and optionally Azure.AI.Projects.OpenAI or Azure.AI.Agents.Persistent), an Azure AI Foundry project endpoint, a model deployment name, and Azure credentials such as DefaultAzureCredential. Network access to Azure is needed. Instructions only; no scripts are shipped.

Azure.AI.Projects (.NET)

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

Installation

bash
dotnet add package Azure.AI.Projectsdotnet add package Azure.Identity
# Optional: For versioned agents with OpenAI extensionsdotnet add package Azure.AI.Projects.OpenAI --prerelease
# Optional: For low-level agent operationsdotnet add package Azure.AI.Agents.Persistent --prerelease

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

Environment Variables

bash
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>  # Required: Azure AI project endpointMODEL_DEPLOYMENT_NAME=gpt-4o-mini  # Required: model deployment nameCONNECTION_NAME=<your-connection-name>  # Optional: project connection nameAI_SEARCH_CONNECTION_NAME=<ai-search-connection>  # Optional: Azure AI Search connection nameAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Authentication

csharp
using Azure.Identity;using Azure.AI.Projects;
var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes// var credential = new ManagedIdentityCredential();AIProjectClient projectClient = new AIProjectClient(    new Uri(endpoint),     credential);

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

csharp
// Get low-level agents client from project clientPersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();
// Create agentPersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(    model: "gpt-4o-mini",    name: "Math Tutor",    instructions: "You are a personal math tutor.");
// Create thread and runPersistentAgentThread 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 completiondo{    await Task.Delay(500);    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);}while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
// Get messagesawait foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id)){    foreach (var content in msg.ContentItems)    {        if (content is MessageTextContent textContent)            Console.WriteLine(textContent.Text);    }}
// Cleanupawait agentsClient.Threads.DeleteThreadAsync(thread.Id);await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. Versioned Agents with Tools (Preview)

csharp
using Azure.AI.Projects.OpenAI;
// Create agent with web search toolPromptAgentDefinition 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 clientProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
// Create responseResponseResult response = responseClient.CreateResponse("What's the weather in Seattle?");Console.WriteLine(response.GetOutputText());
// CleanupprojectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. Connections

csharp
// List all connectionsforeach (AIProjectConnection connection in projectClient.Connections.GetConnections()){    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");}
// Get specific connectionAIProjectConnection conn = projectClient.Connections.GetConnection(    connectionName,     includeCredentials: true);
// Get default connectionAIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(    includeCredentials: false);

4. Deployments

csharp
// List all deploymentsforeach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments()){    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");}
// Filter by publisherforeach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft")){    Console.WriteLine(deployment.Name);}
// Get specific deploymentModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. Datasets

csharp
// Upload single fileFileDataset fileDataset = projectClient.Datasets.UploadFile(    name: "my-dataset",    version: "1.0",    filePath: "data/training.txt",    connectionName: connectionName);
// Upload folderFolderDataset folderDataset = projectClient.Datasets.UploadFolder(    name: "my-dataset",    version: "2.0",    folderPath: "data/training",    connectionName: connectionName,    filePattern: new Regex(".*\\.txt"));
// Get datasetAIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");
// Delete datasetprojectClient.Datasets.Delete("my-dataset", "1.0");

6. Indexes

csharp
// Create Azure AI Search indexAzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName){    Description = "Sample Index"};
searchIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(    name: "my-index",    version: "1.0",    index: searchIndex);
// List indexesforeach (AIProjectIndex index in projectClient.Indexes.GetIndexes()){    Console.WriteLine(index.Name);}
// Delete indexprojectClient.Indexes.Delete(name: "my-index", version: "1.0");

7. Evaluations

csharp
// Create evaluation configurationvar evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));
// Create evaluationEvaluation evaluation = new Evaluation(    data: new InputDataset("<dataset_id>"),    evaluators: new Dictionary<string, EvaluatorConfiguration>     {         { "relevance", evaluatorConfig }     }){    DisplayName = "Sample Evaluation"};
// Run evaluationEvaluation result = projectClient.Evaluations.Create(evaluation: evaluation);
// Get evaluationEvaluation getResult = projectClient.Evaluations.Get(result.Name);
// List evaluationsforeach (var eval in projectClient.Evaluations.GetAll()){    Console.WriteLine($"{eval.DisplayName}: {eval.Status}");}

8. Get Azure OpenAI Chat Client

csharp
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

ToolClassPurpose
Code InterpreterCodeInterpreterToolDefinitionExecute Python code
File SearchFileSearchToolDefinitionSearch uploaded files
Function CallingFunctionToolDefinitionCall custom functions
Bing GroundingBingGroundingToolDefinitionWeb search via Bing
Azure AI SearchAzureAISearchToolDefinitionSearch Azure AI indexes
OpenAPIOpenApiToolDefinitionCall external APIs
Azure FunctionsAzureFunctionToolDefinitionInvoke Azure Functions
MCPMCPToolDefinitionModel Context Protocol tools

Key Types Reference

TypePurpose
AIProjectClientMain entry point
PersistentAgentsClientLow-level agent operations
PromptAgentDefinitionVersioned agent definition
AgentVersionVersioned agent instance
AIProjectConnectionConnection to Azure resource
AIProjectDeploymentModel deployment info
AIProjectDatasetDataset metadata
AIProjectIndexSearch index metadata
EvaluationEvaluation configuration and results

Best Practices

  1. Use DefaultAzureCredential for production authentication
  2. Use async methods (*Async) for all I/O operations
  3. Poll with appropriate delays (500ms recommended) when waiting for runs
  4. Clean up resources — delete threads, agents, and files when done
  5. Use versioned agents (via Azure.AI.Projects.OpenAI) for production scenarios
  6. Store connection IDs rather than names for tool configurations
  7. Use includeCredentials: true only when credentials are needed
  8. Handle pagination — use AsyncPageable<T> for listing operations

Error Handling

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

Related SDKs

SDKPurposeInstall
Azure.AI.ProjectsHigh-level project client (this SDK)dotnet add package Azure.AI.Projects
Azure.AI.Agents.PersistentLow-level agent operationsdotnet add package Azure.AI.Agents.Persistent
Azure.AI.Projects.OpenAIVersioned agents with OpenAIdotnet add package Azure.AI.Projects.OpenAI

Reference Links

Source and attribution

Source:microsoft/skillsin.github/plugins/azure-sdk-dotnet/skills/azure-ai-projects-dotnetat commit354361d

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from microsoft/skills

Azure Mgmt Fabric Dotnet

microsoft

Featured

Guides .NET management-plane provisioning and lifecycle of Microsoft Fabric capacities via Azure Resource Manager.

DevOps & CloudOct 8, 2026

Azure Communication Common Java

microsoft

Featured

Reference for Azure Communication Services common Java utilities: token credentials, refresh, and user identifiers.

Software DevelopmentOct 8, 2026

Azure Mgmt Botservice Dotnet

microsoft

Featured

Azure Resource Manager SDK for Bot Service in .NET. Management plane operations for creating and managing Azure Bot resources, channels (Teams, DirectLine, Slack), and connection settings. Triggers: "Bot Service", "BotResource", "Azure Bot", "DirectLine channel", "Teams channel", "bot management .NET", "create bot".

Awaiting classificationOct 8, 2026

Azure Communication Chat Java

microsoft

Featured

Guides Java developers in building real-time chat features with the Azure Communication Services Chat SDK.

Software DevelopmentOct 8, 2026

Azure Mgmt Arizeaiobservabilityeval Dotnet

microsoft

Featured

Azure Resource Manager SDK for Arize AI Observability and Evaluation (.NET). Use when managing Arize AI organizations on Azure via Azure Marketplace, creating/updating/deleting Arize resources, or integrating Arize ML observability into .NET applications. Triggers: "Arize AI", "ML observability", "ArizeAIObservabilityEval", "Arize organization".

Awaiting classificationOct 8, 2026

Azure Mgmt Applicationinsights Dotnet

microsoft

Featured

Guides .NET developers through managing Azure Application Insights resources with the Azure Resource Manager SDK.

DevOps & CloudOct 8, 2026