Build Persistent AI Agents with .NET SDK

Azure.AI.Agents.Persistent is a low-level .NET SDK for creating and managing persistent AI agents with threads, messages, runs, and tools, authenticating via PersistentAgentsClient with DefaultAzureCredential. The client exposes six sub-clients: Administration (agent CRUD), Threads, Messages, Runs (execution and streaming), Files, and VectorStores.

The core workflow creates an agent with a model deployment, instructions, and tools; creates a thread and posts a user message to it; creates a run against the thread and polls its status (Queued/InProgress/RequiresAction/Completed/Failed) until it settles, then reads back the thread's messages; or, instead of polling, consumes a streaming response that yields run-lifecycle and message-content-chunk updates in real time. Function calling defines a FunctionToolDefinition with a JSON parameter schema, and during polling checks for a RequiresAction status with a SubmitToolOutputsAction, executing each requested function and submitting its output back to the run. File search uploads a file, wraps it in a vector store, and attaches a FileSearchToolResource to the agent. Two grounding tools connect external data: Bing Grounding (web search via a Bing connection resource) and Azure AI Search (querying a named index with a top-K count and an OData filter). Cleanup deletes threads, agents, vector stores, and files explicitly once done.

Ten tool types are supported in total: Code Interpreter, File Search, Function Calling, Bing Grounding, Azure AI Search, OpenAPI (calling external APIs via spec), Azure Functions, MCP (Model Context Protocol), SharePoint, and Microsoft Fabric.

Use it when you need low-level control over agent threads, runs, and tool orchestration - polling or streaming run status yourself, handling function-call tool outputs directly. For a higher-level entry point that wraps this, the SDK's own reference points to the separate Azure.AI.Projects package instead.

Input is a model deployment name, agent instructions, a tool set, and thread messages. Output is agent responses (polled or streamed), tool-call results, and search/file-based grounding. Install it with:

dotnet add package Azure.AI.Agents.Persistent --prerelease
dotnet add package Azure.Identity

Its own best practices: always dispose clients, poll with a 500ms delay between status checks, delete threads/agents/vector stores/files when done, explicitly handle RequiresAction/Failed/Cancelled run statuses, prefer streaming over polling for real-time UX, store IDs rather than objects for later reference, and use the async methods throughout. Errors surface as a RequestFailedException you can branch on by HTTP status, such as 404 for a missing resource.

It connects to Bing (via a Bing connection resource ID) and Azure AI Search (via a search connection resource ID and index name) as grounding tools, alongside file-based vector-store search, and is the low-level counterpart to the higher-level Azure.AI.Projects package.

.NET developers building AI agents that need direct control over threads, runs, streaming, and tool orchestration (function calling, file search, Bing/Azure AI Search grounding) rather than a higher-level, less configurable agent wrapper.