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 --prereleaseCurrent 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 productionAuthentication
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() → PersistentAgentsClientCore 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
| 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
DefaultAzureCredentialfor 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: trueonly when credentials are needed - 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
| 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 |



