Azure AI Projects Dotnet

1---
2name: azure-ai-projects-dotnet
3description: |
4  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".
5package: Azure.AI.Projects
6---
7 
8# Azure.AI.Projects (.NET)
9 
10High-level SDK for Azure AI Foundry project operations including agents, connections, datasets, deployments, evaluations, and indexes.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.AI.Projects
16dotnet add package Azure.Identity
17 
18# Optional: For versioned agents with OpenAI extensions
19dotnet add package Azure.AI.Projects.OpenAI --prerelease
20 
21# Optional: For low-level agent operations
22dotnet add package Azure.AI.Agents.Persistent --prerelease
23```
24 
25**Current Versions**: GA v1.1.0, Preview v1.2.0-beta.5
26 
27## Environment Variables
28 
29```bash
30PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
31MODEL_DEPLOYMENT_NAME=gpt-4o-mini
32CONNECTION_NAME=<your-connection-name>
33AI_SEARCH_CONNECTION_NAME=<ai-search-connection>
34```
35 
36## Authentication
37 
38```csharp
39using Azure.Identity;
40using Azure.AI.Projects;
41 
42var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
43AIProjectClient projectClient = new AIProjectClient(
44    new Uri(endpoint), 
45    new DefaultAzureCredential());
46```
47 
48## Client Hierarchy
49 
50```
51AIProjectClient
52├── Agents          → AIProjectAgentsOperations (versioned agents)
53├── Connections     → ConnectionsClient
54├── Datasets        → DatasetsClient
55├── Deployments     → DeploymentsClient
56├── Evaluations     → EvaluationsClient
57├── Evaluators      → EvaluatorsClient
58├── Indexes         → IndexesClient
59├── Telemetry       → AIProjectTelemetry
60├── OpenAI          → ProjectOpenAIClient (preview)
61└── GetPersistentAgentsClient() → PersistentAgentsClient
62```
63 
64## Core Workflows
65 
66### 1. Get Persistent Agents Client
67 
68```csharp
69// Get low-level agents client from project client
70PersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();
71 
72// Create agent
73PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(
74    model: "gpt-4o-mini",
75    name: "Math Tutor",
76    instructions: "You are a personal math tutor.");
77 
78// Create thread and run
79PersistentAgentThread thread = await agentsClient.Threads.CreateThreadAsync();
80await agentsClient.Messages.CreateMessageAsync(thread.Id, MessageRole.User, "Solve 3x + 11 = 14");
81ThreadRun run = await agentsClient.Runs.CreateRunAsync(thread.Id, agent.Id);
82 
83// Poll for completion
84do
85{
86    await Task.Delay(500);
87    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);
88}
89while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
90 
91// Get messages
92await foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id))
93{
94    foreach (var content in msg.ContentItems)
95    {
96        if (content is MessageTextContent textContent)
97            Console.WriteLine(textContent.Text);
98    }
99}
100 
101// Cleanup
102await agentsClient.Threads.DeleteThreadAsync(thread.Id);
103await agentsClient.Administration.DeleteAgentAsync(agent.Id);
104```
105 
106### 2. Versioned Agents with Tools (Preview)
107 
108```csharp
109using Azure.AI.Projects.OpenAI;
110 
111// Create agent with web search tool
112PromptAgentDefinition agentDefinition = new(model: "gpt-4o-mini")
113{
114    Instructions = "You are a helpful assistant that can search the web",
115    Tools = {
116        ResponseTool.CreateWebSearchTool(
117            userLocation: WebSearchToolLocation.CreateApproximateLocation(
118                country: "US",
119                city: "Seattle",
120                region: "Washington"
121            )
122        ),
123    }
124};
125 
126AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
127    agentName: "myAgent",
128    options: new(agentDefinition));
129 
130// Get response client
131ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
132 
133// Create response
134ResponseResult response = responseClient.CreateResponse("What's the weather in Seattle?");
135Console.WriteLine(response.GetOutputText());
136 
137// Cleanup
138projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
139```
140 
141### 3. Connections
142 
143```csharp
144// List all connections
145foreach (AIProjectConnection connection in projectClient.Connections.GetConnections())
146{
147    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");
148}
149 
150// Get specific connection
151AIProjectConnection conn = projectClient.Connections.GetConnection(
152    connectionName, 
153    includeCredentials: true);
154 
155// Get default connection
156AIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(
157    includeCredentials: false);
158```
159 
160### 4. Deployments
161 
162```csharp
163// List all deployments
164foreach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments())
165{
166    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");
167}
168 
169// Filter by publisher
170foreach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft"))
171{
172    Console.WriteLine(deployment.Name);
173}
174 
175// Get specific deployment
176ModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");
177```
178 
179### 5. Datasets
180 
181```csharp
182// Upload single file
183FileDataset fileDataset = projectClient.Datasets.UploadFile(
184    name: "my-dataset",
185    version: "1.0",
186    filePath: "data/training.txt",
187    connectionName: connectionName);
188 
189// Upload folder
190FolderDataset folderDataset = projectClient.Datasets.UploadFolder(
191    name: "my-dataset",
192    version: "2.0",
193    folderPath: "data/training",
194    connectionName: connectionName,
195    filePattern: new Regex(".*\\.txt"));
196 
197// Get dataset
198AIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");
199 
200// Delete dataset
201projectClient.Datasets.Delete("my-dataset", "1.0");
202```
203 
204### 6. Indexes
205 
206```csharp
207// Create Azure AI Search index
208AzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName)
209{
210    Description = "Sample Index"
211};
212 
213searchIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(
214    name: "my-index",
215    version: "1.0",
216    index: searchIndex);
217 
218// List indexes
219foreach (AIProjectIndex index in projectClient.Indexes.GetIndexes())
220{
221    Console.WriteLine(index.Name);
222}
223 
224// Delete index
225projectClient.Indexes.Delete(name: "my-index", version: "1.0");
226```
227 
228### 7. Evaluations
229 
230```csharp
231// Create evaluation configuration
232var evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);
233evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));
234 
235// Create evaluation
236Evaluation evaluation = new Evaluation(
237    data: new InputDataset("<dataset_id>"),
238    evaluators: new Dictionary<string, EvaluatorConfiguration> 
239    { 
240        { "relevance", evaluatorConfig } 
241    }
242)
243{
244    DisplayName = "Sample Evaluation"
245};
246 
247// Run evaluation
248Evaluation result = projectClient.Evaluations.Create(evaluation: evaluation);
249 
250// Get evaluation
251Evaluation getResult = projectClient.Evaluations.Get(result.Name);
252 
253// List evaluations
254foreach (var eval in projectClient.Evaluations.GetAll())
255{
256    Console.WriteLine($"{eval.DisplayName}: {eval.Status}");
257}
258```
259 
260### 8. Get Azure OpenAI Chat Client
261 
262```csharp
263using Azure.AI.OpenAI;
264using OpenAI.Chat;
265 
266ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
267 
268if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
269    throw new InvalidOperationException("Invalid URI.");
270 
271uri = new Uri($"https://{uri.Host}");
272 
273AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
274ChatClient chatClient = azureOpenAIClient.GetChatClient("gpt-4o-mini");
275 
276ChatCompletion result = chatClient.CompleteChat("List all rainbow colors");
277Console.WriteLine(result.Content[0].Text);
278```
279 
280## Available Agent Tools
281 
282| Tool | Class | Purpose |
283|------|-------|---------|
284| Code Interpreter | `CodeInterpreterToolDefinition` | Execute Python code |
285| File Search | `FileSearchToolDefinition` | Search uploaded files |
286| Function Calling | `FunctionToolDefinition` | Call custom functions |
287| Bing Grounding | `BingGroundingToolDefinition` | Web search via Bing |
288| Azure AI Search | `AzureAISearchToolDefinition` | Search Azure AI indexes |
289| OpenAPI | `OpenApiToolDefinition` | Call external APIs |
290| Azure Functions | `AzureFunctionToolDefinition` | Invoke Azure Functions |
291| MCP | `MCPToolDefinition` | Model Context Protocol tools |
292 
293## Key Types Reference
294 
295| Type | Purpose |
296|------|---------|
297| `AIProjectClient` | Main entry point |
298| `PersistentAgentsClient` | Low-level agent operations |
299| `PromptAgentDefinition` | Versioned agent definition |
300| `AgentVersion` | Versioned agent instance |
301| `AIProjectConnection` | Connection to Azure resource |
302| `AIProjectDeployment` | Model deployment info |
303| `AIProjectDataset` | Dataset metadata |
304| `AIProjectIndex` | Search index metadata |
305| `Evaluation` | Evaluation configuration and results |
306 
307## Best Practices
308 
3091. **Use `DefaultAzureCredential`** for production authentication
3102. **Use async methods** (`*Async`) for all I/O operations
3113. **Poll with appropriate delays** (500ms recommended) when waiting for runs
3124. **Clean up resources** — delete threads, agents, and files when done
3135. **Use versioned agents** (via `Azure.AI.Projects.OpenAI`) for production scenarios
3146. **Store connection IDs** rather than names for tool configurations
3157. **Use `includeCredentials: true`** only when credentials are needed
3168. **Handle pagination** — use `AsyncPageable<T>` for listing operations
317 
318## Error Handling
319 
320```csharp
321using Azure;
322 
323try
324{
325    var result = await projectClient.Evaluations.CreateAsync(evaluation);
326}
327catch (RequestFailedException ex)
328{
329    Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
330}
331```
332 
333## Related SDKs
334 
335| SDK | Purpose | Install |
336|-----|---------|---------|
337| `Azure.AI.Projects` | High-level project client (this SDK) | `dotnet add package Azure.AI.Projects` |
338| `Azure.AI.Agents.Persistent` | Low-level agent operations | `dotnet add package Azure.AI.Agents.Persistent` |
339| `Azure.AI.Projects.OpenAI` | Versioned agents with OpenAI | `dotnet add package Azure.AI.Projects.OpenAI` |
340 
341## Reference Links
342 
343| Resource | URL |
344|----------|-----|
345| NuGet Package | https://www.nuget.org/packages/Azure.AI.Projects |
346| API Reference | https://learn.microsoft.com/dotnet/api/azure.ai.projects |
347| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects |
348| Samples | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/samples |
349