Azure Ai Agents Persistent Dotnet

by microsoft354361d83247MITListed Oct 8, 2026Updated Oct 8, 2026

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".

FeaturedInstructions onlyAI & AgentsSoftware Development
AI-generated overview

Documents the Azure AI Agents Persistent SDK for .NET for building and managing persistent AI agents with threads, runs, and tools.

What it does
Explains how to install and authenticate the Azure.AI.Agents.Persistent .NET package and use PersistentAgentsClient to create agents, threads, messages, and runs. Covers polling and streaming run execution, function calling with tool outputs, file search with vector stores, Bing grounding, and Azure AI Search. Also lists available tools, streaming update types, key types, cleanup, and error handling.
When to use it
Use when writing .NET code against the Azure AI Agents Persistent SDK, such as creating agents, managing conversation threads, streaming responses, or wiring tools like code interpreter, file search, and function calling.
Requirements
Requires the .NET SDK with the Azure.AI.Agents.Persistent and Azure.Identity NuGet packages, an Azure AI project endpoint, a model deployment name, and credentials; Bing grounding and Azure AI Search tools need Bing and Azure AI Search connection IDs. Network access to Azure is required. Ships no scripts; instructions only.

Azure.AI.Agents.Persistent (.NET)

Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.

Installation

bash
dotnet add package Azure.AI.Agents.Persistent --prereleasedotnet add package Azure.Identity

Current Versions: Stable v1.1.0, Preview v1.2.0-beta.8

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 nameAZURE_BING_CONNECTION_ID=<bing-connection-resource-id>  # Required: Bing connection resource IDAZURE_AI_SEARCH_CONNECTION_ID=<search-connection-resource-id>  # Required: Azure AI Search connection resource IDAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Authentication

csharp
using Azure.AI.Agents.Persistent;using Azure.Identity;
var projectEndpoint = 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();PersistentAgentsClient client = new(projectEndpoint, credential);

Client Hierarchy

PersistentAgentsClient├── Administration  → Agent CRUD operations├── Threads         → Thread management├── Messages        → Message operations├── Runs            → Run execution and streaming├── Files           → File upload/download└── VectorStores    → Vector store management

Core Workflow

1. Create Agent

csharp
var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
PersistentAgent agent = await client.Administration.CreateAgentAsync(    model: modelDeploymentName,    name: "Math Tutor",    instructions: "You are a personal math tutor. Write and run code to answer math questions.",    tools: [new CodeInterpreterToolDefinition()]);

2. Create Thread and Message

csharp
// Create threadPersistentAgentThread thread = await client.Threads.CreateThreadAsync();
// Create messageawait client.Messages.CreateMessageAsync(    thread.Id,    MessageRole.User,    "I need to solve the equation `3x + 11 = 14`. Can you help me?");

3. Run Agent (Polling)

csharp
// Create runThreadRun run = await client.Runs.CreateRunAsync(    thread.Id,    agent.Id,    additionalInstructions: "Please address the user as Jane Doe.");
// Poll for completiondo{    await Task.Delay(TimeSpan.FromMilliseconds(500));    run = await client.Runs.GetRunAsync(thread.Id, run.Id);}while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
// Retrieve messagesawait foreach (PersistentThreadMessage message in client.Messages.GetMessagesAsync(    threadId: thread.Id,     order: ListSortOrder.Ascending)){    Console.Write($"{message.Role}: ");    foreach (MessageContent content in message.ContentItems)    {        if (content is MessageTextContent textContent)            Console.WriteLine(textContent.Text);    }}

4. Streaming Response

csharp
AsyncCollectionResult<StreamingUpdate> stream = client.Runs.CreateRunStreamingAsync(    thread.Id,     agent.Id);
await foreach (StreamingUpdate update in stream){    if (update.UpdateKind == StreamingUpdateReason.RunCreated)    {        Console.WriteLine("--- Run started! ---");    }    else if (update is MessageContentUpdate contentUpdate)    {        Console.Write(contentUpdate.Text);    }    else if (update.UpdateKind == StreamingUpdateReason.RunCompleted)    {        Console.WriteLine("\n--- Run completed! ---");    }}

5. Function Calling

csharp
// Define function toolFunctionToolDefinition weatherTool = new(    name: "getCurrentWeather",    description: "Gets the current weather at a location.",    parameters: BinaryData.FromObjectAsJson(new    {        Type = "object",        Properties = new        {            Location = new { Type = "string", Description = "City and state, e.g. San Francisco, CA" },            Unit = new { Type = "string", Enum = new[] { "c", "f" } }        },        Required = new[] { "location" }    }, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }));
// Create agent with functionPersistentAgent agent = await client.Administration.CreateAgentAsync(    model: modelDeploymentName,    name: "Weather Bot",    instructions: "You are a weather bot.",    tools: [weatherTool]);
// Handle function calls during pollingdo{    await Task.Delay(500);    run = await client.Runs.GetRunAsync(thread.Id, run.Id);
    if (run.Status == RunStatus.RequiresAction         && run.RequiredAction is SubmitToolOutputsAction submitAction)    {        List<ToolOutput> outputs = [];        foreach (RequiredToolCall toolCall in submitAction.ToolCalls)        {            if (toolCall is RequiredFunctionToolCall funcCall)            {                // Execute function and get result                string result = ExecuteFunction(funcCall.Name, funcCall.Arguments);                outputs.Add(new ToolOutput(toolCall, result));            }        }        run = await client.Runs.SubmitToolOutputsToRunAsync(run, outputs, toolApprovals: null);    }}while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

6. File Search with Vector Store

csharp
// Upload filePersistentAgentFileInfo file = await client.Files.UploadFileAsync(    filePath: "document.txt",    purpose: PersistentAgentFilePurpose.Agents);
// Create vector storePersistentAgentsVectorStore vectorStore = await client.VectorStores.CreateVectorStoreAsync(    fileIds: [file.Id],    name: "my_vector_store");
// Create file search resourceFileSearchToolResource fileSearchResource = new();fileSearchResource.VectorStoreIds.Add(vectorStore.Id);
// Create agent with file searchPersistentAgent agent = await client.Administration.CreateAgentAsync(    model: modelDeploymentName,    name: "Document Assistant",    instructions: "You help users find information in documents.",    tools: [new FileSearchToolDefinition()],    toolResources: new ToolResources { FileSearch = fileSearchResource });

7. Bing Grounding

csharp
var bingConnectionId = Environment.GetEnvironmentVariable("AZURE_BING_CONNECTION_ID");
BingGroundingToolDefinition bingTool = new(    new BingGroundingSearchToolParameters(        [new BingGroundingSearchConfiguration(bingConnectionId)]    ));
PersistentAgent agent = await client.Administration.CreateAgentAsync(    model: modelDeploymentName,    name: "Search Agent",    instructions: "Use Bing to answer questions about current events.",    tools: [bingTool]);

8. Azure AI Search

csharp
AzureAISearchToolResource searchResource = new(    connectionId: searchConnectionId,    indexName: "my_index",    topK: 5,    filter: "category eq 'documentation'",    queryType: AzureAISearchQueryType.Simple);
PersistentAgent agent = await client.Administration.CreateAgentAsync(    model: modelDeploymentName,    name: "Search Agent",    instructions: "Search the documentation index to answer questions.",    tools: [new AzureAISearchToolDefinition()],    toolResources: new ToolResources { AzureAISearch = searchResource });

9. Cleanup

csharp
await client.Threads.DeleteThreadAsync(thread.Id);await client.Administration.DeleteAgentAsync(agent.Id);await client.VectorStores.DeleteVectorStoreAsync(vectorStore.Id);await client.Files.DeleteFileAsync(file.Id);

Available Tools

ToolClassPurpose
Code InterpreterCodeInterpreterToolDefinitionExecute Python code, generate visualizations
File SearchFileSearchToolDefinitionSearch uploaded files via vector stores
Function CallingFunctionToolDefinitionCall custom functions
Bing GroundingBingGroundingToolDefinitionWeb search via Bing
Azure AI SearchAzureAISearchToolDefinitionSearch Azure AI Search indexes
OpenAPIOpenApiToolDefinitionCall external APIs via OpenAPI spec
Azure FunctionsAzureFunctionToolDefinitionInvoke Azure Functions
MCPMCPToolDefinitionModel Context Protocol tools
SharePointSharepointToolDefinitionAccess SharePoint content
Microsoft FabricMicrosoftFabricToolDefinitionAccess Fabric data

Streaming Update Types

Update TypeDescription
StreamingUpdateReason.RunCreatedRun started
StreamingUpdateReason.RunInProgressRun processing
StreamingUpdateReason.RunCompletedRun finished
StreamingUpdateReason.RunFailedRun errored
MessageContentUpdateText content chunk
RunStepUpdateStep status change

Key Types Reference

TypePurpose
PersistentAgentsClientMain entry point
PersistentAgentAgent with model, instructions, tools
PersistentAgentThreadConversation thread
PersistentThreadMessageMessage in thread
ThreadRunExecution of agent against thread
RunStatusQueued, InProgress, RequiresAction, Completed, Failed
ToolResourcesCombined tool resources
ToolOutputFunction call response

Best Practices

  1. Always dispose clients — Use using statements or explicit disposal
  2. Poll with appropriate delays — 500ms recommended between status checks
  3. Clean up resources — Delete threads and agents when done
  4. Handle all run statuses — Check for RequiresAction, Failed, Cancelled
  5. Use streaming for real-time UX — Better user experience than polling
  6. Store IDs not objects — Reference agents/threads by ID
  7. Use async methods — All operations should be async

Error Handling

csharp
using Azure;
try{    var agent = await client.Administration.CreateAgentAsync(...);}catch (RequestFailedException ex) when (ex.Status == 404){    Console.WriteLine("Resource not found");}catch (RequestFailedException ex){    Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");}

Related SDKs

SDKPurposeInstall
Azure.AI.Agents.PersistentLow-level agents (this SDK)dotnet add package Azure.AI.Agents.Persistent
Azure.AI.ProjectsHigh-level project clientdotnet add package Azure.AI.Projects

Reference Links

Source and attribution

Source:microsoft/skillsin.github/plugins/azure-sdk-dotnet/skills/azure-ai-agents-persistent-dotnetat commit354361d

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal