Skill v1.0.1
currentAutomated scan100/100+4 new
name: azure-ai-projects-dotnet description: Azure AI Projects SDK for .NET. High-level client for Azure AI Foundry projects including agents, connections, datasets, deployments, evaluations, and indexes. risk: critical source: community date_added: '2026-02-27' metadata: version: "1.0.1"
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.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
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>MODEL_DEPLOYMENT_NAME=gpt-4o-miniCONNECTION_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
The snippets span GA/preview surfaces; pin compatible package versions and verify signatures in the linked SDK samples before combining them. Confirm project endpoint, tenant, deployment, budget and permitted uploaded data. Agent runs/evaluations may bill or call external tools. Add cancellation/deadline to every poll, distinguish Completed from Failed/Cancelled/RequiresAction, and inspect output only after successful completion. Cleanup deletes only resources created by this run; use finally blocks after preserving needed evidence, never delete user-owned resources merely because a sample ends.
1. Get Persistent Agents Client
// 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)
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
// List all connectionsforeach (AIProjectConnection connection in projectClient.Connections.GetConnections()){Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");}// Get specific connectionAIProjectConnection conn = projectClient.Connections.GetConnection(connectionName,includeCredentials: false);// Get default connectionAIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(includeCredentials: false);
4. Deployments
// 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
// 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
// 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
// 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
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 |
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.