Azure AI Agents Persistent Dotnet

1---
2name: azure-ai-agents-persistent-dotnet
3description: |
4  Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: "PersistentAgentsClient", "persistent agents", "agent threads", "agent runs", "streaming agents", "function calling agents .NET".
5package: Azure.AI.Agents.Persistent
6---
7 
8# Azure.AI.Agents.Persistent (.NET)
9 
10Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.AI.Agents.Persistent --prerelease
16dotnet add package Azure.Identity
17```
18 
19**Current Versions**: Stable v1.1.0, Preview v1.2.0-beta.8
20 
21## Environment Variables
22 
23```bash
24PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
25MODEL_DEPLOYMENT_NAME=gpt-4o-mini
26AZURE_BING_CONNECTION_ID=<bing-connection-resource-id>
27AZURE_AI_SEARCH_CONNECTION_ID=<search-connection-resource-id>
28```
29 
30## Authentication
31 
32```csharp
33using Azure.AI.Agents.Persistent;
34using Azure.Identity;
35 
36var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
37PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());
38```
39 
40## Client Hierarchy
41 
42```
43PersistentAgentsClient
44├── Administration  → Agent CRUD operations
45├── Threads         → Thread management
46├── Messages        → Message operations
47├── Runs            → Run execution and streaming
48├── Files           → File upload/download
49└── VectorStores    → Vector store management
50```
51 
52## Core Workflow
53 
54### 1. Create Agent
55 
56```csharp
57var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
58 
59PersistentAgent agent = await client.Administration.CreateAgentAsync(
60    model: modelDeploymentName,
61    name: "Math Tutor",
62    instructions: "You are a personal math tutor. Write and run code to answer math questions.",
63    tools: [new CodeInterpreterToolDefinition()]
64);
65```
66 
67### 2. Create Thread and Message
68 
69```csharp
70// Create thread
71PersistentAgentThread thread = await client.Threads.CreateThreadAsync();
72 
73// Create message
74await client.Messages.CreateMessageAsync(
75    thread.Id,
76    MessageRole.User,
77    "I need to solve the equation `3x + 11 = 14`. Can you help me?"
78);
79```
80 
81### 3. Run Agent (Polling)
82 
83```csharp
84// Create run
85ThreadRun run = await client.Runs.CreateRunAsync(
86    thread.Id,
87    agent.Id,
88    additionalInstructions: "Please address the user as Jane Doe."
89);
90 
91// Poll for completion
92do
93{
94    await Task.Delay(TimeSpan.FromMilliseconds(500));
95    run = await client.Runs.GetRunAsync(thread.Id, run.Id);
96}
97while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
98 
99// Retrieve messages
100await foreach (PersistentThreadMessage message in client.Messages.GetMessagesAsync(
101    threadId: thread.Id, 
102    order: ListSortOrder.Ascending))
103{
104    Console.Write($"{message.Role}: ");
105    foreach (MessageContent content in message.ContentItems)
106    {
107        if (content is MessageTextContent textContent)
108            Console.WriteLine(textContent.Text);
109    }
110}
111```
112 
113### 4. Streaming Response
114 
115```csharp
116AsyncCollectionResult<StreamingUpdate> stream = client.Runs.CreateRunStreamingAsync(
117    thread.Id, 
118    agent.Id
119);
120 
121await foreach (StreamingUpdate update in stream)
122{
123    if (update.UpdateKind == StreamingUpdateReason.RunCreated)
124    {
125        Console.WriteLine("--- Run started! ---");
126    }
127    else if (update is MessageContentUpdate contentUpdate)
128    {
129        Console.Write(contentUpdate.Text);
130    }
131    else if (update.UpdateKind == StreamingUpdateReason.RunCompleted)
132    {
133        Console.WriteLine("\n--- Run completed! ---");
134    }
135}
136```
137 
138### 5. Function Calling
139 
140```csharp
141// Define function tool
142FunctionToolDefinition weatherTool = new(
143    name: "getCurrentWeather",
144    description: "Gets the current weather at a location.",
145    parameters: BinaryData.FromObjectAsJson(new
146    {
147        Type = "object",
148        Properties = new
149        {
150            Location = new { Type = "string", Description = "City and state, e.g. San Francisco, CA" },
151            Unit = new { Type = "string", Enum = new[] { "c", "f" } }
152        },
153        Required = new[] { "location" }
154    }, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
155);
156 
157// Create agent with function
158PersistentAgent agent = await client.Administration.CreateAgentAsync(
159    model: modelDeploymentName,
160    name: "Weather Bot",
161    instructions: "You are a weather bot.",
162    tools: [weatherTool]
163);
164 
165// Handle function calls during polling
166do
167{
168    await Task.Delay(500);
169    run = await client.Runs.GetRunAsync(thread.Id, run.Id);
170 
171    if (run.Status == RunStatus.RequiresAction 
172        && run.RequiredAction is SubmitToolOutputsAction submitAction)
173    {
174        List<ToolOutput> outputs = [];
175        foreach (RequiredToolCall toolCall in submitAction.ToolCalls)
176        {
177            if (toolCall is RequiredFunctionToolCall funcCall)
178            {
179                // Execute function and get result
180                string result = ExecuteFunction(funcCall.Name, funcCall.Arguments);
181                outputs.Add(new ToolOutput(toolCall, result));
182            }
183        }
184        run = await client.Runs.SubmitToolOutputsToRunAsync(run, outputs, toolApprovals: null);
185    }
186}
187while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
188```
189 
190### 6. File Search with Vector Store
191 
192```csharp
193// Upload file
194PersistentAgentFileInfo file = await client.Files.UploadFileAsync(
195    filePath: "document.txt",
196    purpose: PersistentAgentFilePurpose.Agents
197);
198 
199// Create vector store
200PersistentAgentsVectorStore vectorStore = await client.VectorStores.CreateVectorStoreAsync(
201    fileIds: [file.Id],
202    name: "my_vector_store"
203);
204 
205// Create file search resource
206FileSearchToolResource fileSearchResource = new();
207fileSearchResource.VectorStoreIds.Add(vectorStore.Id);
208 
209// Create agent with file search
210PersistentAgent agent = await client.Administration.CreateAgentAsync(
211    model: modelDeploymentName,
212    name: "Document Assistant",
213    instructions: "You help users find information in documents.",
214    tools: [new FileSearchToolDefinition()],
215    toolResources: new ToolResources { FileSearch = fileSearchResource }
216);
217```
218 
219### 7. Bing Grounding
220 
221```csharp
222var bingConnectionId = Environment.GetEnvironmentVariable("AZURE_BING_CONNECTION_ID");
223 
224BingGroundingToolDefinition bingTool = new(
225    new BingGroundingSearchToolParameters(
226        [new BingGroundingSearchConfiguration(bingConnectionId)]
227    )
228);
229 
230PersistentAgent agent = await client.Administration.CreateAgentAsync(
231    model: modelDeploymentName,
232    name: "Search Agent",
233    instructions: "Use Bing to answer questions about current events.",
234    tools: [bingTool]
235);
236```
237 
238### 8. Azure AI Search
239 
240```csharp
241AzureAISearchToolResource searchResource = new(
242    connectionId: searchConnectionId,
243    indexName: "my_index",
244    topK: 5,
245    filter: "category eq 'documentation'",
246    queryType: AzureAISearchQueryType.Simple
247);
248 
249PersistentAgent agent = await client.Administration.CreateAgentAsync(
250    model: modelDeploymentName,
251    name: "Search Agent",
252    instructions: "Search the documentation index to answer questions.",
253    tools: [new AzureAISearchToolDefinition()],
254    toolResources: new ToolResources { AzureAISearch = searchResource }
255);
256```
257 
258### 9. Cleanup
259 
260```csharp
261await client.Threads.DeleteThreadAsync(thread.Id);
262await client.Administration.DeleteAgentAsync(agent.Id);
263await client.VectorStores.DeleteVectorStoreAsync(vectorStore.Id);
264await client.Files.DeleteFileAsync(file.Id);
265```
266 
267## Available Tools
268 
269| Tool | Class | Purpose |
270|------|-------|---------|
271| Code Interpreter | `CodeInterpreterToolDefinition` | Execute Python code, generate visualizations |
272| File Search | `FileSearchToolDefinition` | Search uploaded files via vector stores |
273| Function Calling | `FunctionToolDefinition` | Call custom functions |
274| Bing Grounding | `BingGroundingToolDefinition` | Web search via Bing |
275| Azure AI Search | `AzureAISearchToolDefinition` | Search Azure AI Search indexes |
276| OpenAPI | `OpenApiToolDefinition` | Call external APIs via OpenAPI spec |
277| Azure Functions | `AzureFunctionToolDefinition` | Invoke Azure Functions |
278| MCP | `MCPToolDefinition` | Model Context Protocol tools |
279| SharePoint | `SharepointToolDefinition` | Access SharePoint content |
280| Microsoft Fabric | `MicrosoftFabricToolDefinition` | Access Fabric data |
281 
282## Streaming Update Types
283 
284| Update Type | Description |
285|-------------|-------------|
286| `StreamingUpdateReason.RunCreated` | Run started |
287| `StreamingUpdateReason.RunInProgress` | Run processing |
288| `StreamingUpdateReason.RunCompleted` | Run finished |
289| `StreamingUpdateReason.RunFailed` | Run errored |
290| `MessageContentUpdate` | Text content chunk |
291| `RunStepUpdate` | Step status change |
292 
293## Key Types Reference
294 
295| Type | Purpose |
296|------|---------|
297| `PersistentAgentsClient` | Main entry point |
298| `PersistentAgent` | Agent with model, instructions, tools |
299| `PersistentAgentThread` | Conversation thread |
300| `PersistentThreadMessage` | Message in thread |
301| `ThreadRun` | Execution of agent against thread |
302| `RunStatus` | Queued, InProgress, RequiresAction, Completed, Failed |
303| `ToolResources` | Combined tool resources |
304| `ToolOutput` | Function call response |
305 
306## Best Practices
307 
3081. **Always dispose clients** — Use `using` statements or explicit disposal
3092. **Poll with appropriate delays** — 500ms recommended between status checks
3103. **Clean up resources** — Delete threads and agents when done
3114. **Handle all run statuses** — Check for `RequiresAction`, `Failed`, `Cancelled`
3125. **Use streaming for real-time UX** — Better user experience than polling
3136. **Store IDs not objects** — Reference agents/threads by ID
3147. **Use async methods** — All operations should be async
315 
316## Error Handling
317 
318```csharp
319using Azure;
320 
321try
322{
323    var agent = await client.Administration.CreateAgentAsync(...);
324}
325catch (RequestFailedException ex) when (ex.Status == 404)
326{
327    Console.WriteLine("Resource not found");
328}
329catch (RequestFailedException ex)
330{
331    Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
332}
333```
334 
335## Related SDKs
336 
337| SDK | Purpose | Install |
338|-----|---------|---------|
339| `Azure.AI.Agents.Persistent` | Low-level agents (this SDK) | `dotnet add package Azure.AI.Agents.Persistent` |
340| `Azure.AI.Projects` | High-level project client | `dotnet add package Azure.AI.Projects` |
341 
342## Reference Links
343 
344| Resource | URL |
345|----------|-----|
346| NuGet Package | https://www.nuget.org/packages/Azure.AI.Agents.Persistent |
347| API Reference | https://learn.microsoft.com/dotnet/api/azure.ai.agents.persistent |
348| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent |
349| Samples | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent/samples |
350