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 ( "" ) , 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 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.