Azure Ai Projects Dotnet

作者 microsoft354361d83247MIT收录于 2026年10月8日更新于 2026年10月8日

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

精选仅含说明AI & Agents
AI 生成的概览

介绍用于 .NET 的 Azure AI Projects SDK,可管理 AI Foundry 的代理、连接、数据集、部署、评估和索引。

功能
提供 Azure.AI.Projects 客户端库的参考说明和 C# 代码示例。内容涵盖身份验证、客户端层次结构、创建并运行带工具的持久代理和版本化代理,以及管理连接、部署、数据集、索引和评估。还列出可用的代理工具、关键类型、最佳实践和错误处理方式。
适用场景
适用于编写或审查与 Azure AI Foundry 项目交互的 .NET 代码,例如创建版本化代理、运行评估,或管理项目连接、数据集和部署。
运行要求
需要 .NET SDK 与 Azure.AI.Projects 包(以及 Azure.Identity,可选 Azure.AI.Projects.OpenAI 或 Azure.AI.Agents.Persistent)、Azure AI Foundry 项目终结点、模型部署名称,以及 DefaultAzureCredential 等 Azure 凭据。需要访问 Azure 的网络。仅为说明文档,不附带脚本。

Azure.AI.Projects (.NET)

High-level SDK for Azure AI Foundry project operations including agents, connections, datasets, deployments, evaluations, and indexes.

Installation

bash
dotnet add package Azure.AI.Projectsdotnet add package Azure.Identity
# Optional: For versioned agents with OpenAI extensionsdotnet add package Azure.AI.Projects.OpenAI --prerelease
# Optional: For low-level agent operationsdotnet add package Azure.AI.Agents.Persistent --prerelease

Current Versions: GA v1.1.0, Preview v1.2.0-beta.5

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 nameCONNECTION_NAME=<your-connection-name>  # Optional: project connection nameAI_SEARCH_CONNECTION_NAME=<ai-search-connection>  # Optional: Azure AI Search connection nameAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Authentication

csharp
using Azure.Identity;using Azure.AI.Projects;
var endpoint = 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();AIProjectClient projectClient = new AIProjectClient(    new Uri(endpoint),     credential);

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

csharp
// Get low-level agents client from project clientPersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();
// Create agentPersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(    model: "gpt-4o-mini",    name: "Math Tutor",    instructions: "You are a personal math tutor.");
// Create thread and runPersistentAgentThread 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 completiondo{    await Task.Delay(500);    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);}while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
// Get messagesawait foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id)){    foreach (var content in msg.ContentItems)    {        if (content is MessageTextContent textContent)            Console.WriteLine(textContent.Text);    }}
// Cleanupawait agentsClient.Threads.DeleteThreadAsync(thread.Id);await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. Versioned Agents with Tools (Preview)

csharp
using Azure.AI.Projects.OpenAI;
// Create agent with web search toolPromptAgentDefinition 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 clientProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
// Create responseResponseResult response = responseClient.CreateResponse("What's the weather in Seattle?");Console.WriteLine(response.GetOutputText());
// CleanupprojectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. Connections

csharp
// List all connectionsforeach (AIProjectConnection connection in projectClient.Connections.GetConnections()){    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");}
// Get specific connectionAIProjectConnection conn = projectClient.Connections.GetConnection(    connectionName,     includeCredentials: true);
// Get default connectionAIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(    includeCredentials: false);

4. Deployments

csharp
// List all deploymentsforeach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments()){    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");}
// Filter by publisherforeach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft")){    Console.WriteLine(deployment.Name);}
// Get specific deploymentModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. Datasets

csharp
// Upload single fileFileDataset fileDataset = projectClient.Datasets.UploadFile(    name: "my-dataset",    version: "1.0",    filePath: "data/training.txt",    connectionName: connectionName);
// Upload folderFolderDataset folderDataset = projectClient.Datasets.UploadFolder(    name: "my-dataset",    version: "2.0",    folderPath: "data/training",    connectionName: connectionName,    filePattern: new Regex(".*\\.txt"));
// Get datasetAIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");
// Delete datasetprojectClient.Datasets.Delete("my-dataset", "1.0");

6. Indexes

csharp
// Create Azure AI Search indexAzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName){    Description = "Sample Index"};
searchIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(    name: "my-index",    version: "1.0",    index: searchIndex);
// List indexesforeach (AIProjectIndex index in projectClient.Indexes.GetIndexes()){    Console.WriteLine(index.Name);}
// Delete indexprojectClient.Indexes.Delete(name: "my-index", version: "1.0");

7. Evaluations

csharp
// Create evaluation configurationvar evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));
// Create evaluationEvaluation evaluation = new Evaluation(    data: new InputDataset("<dataset_id>"),    evaluators: new Dictionary<string, EvaluatorConfiguration>     {         { "relevance", evaluatorConfig }     }){    DisplayName = "Sample Evaluation"};
// Run evaluationEvaluation result = projectClient.Evaluations.Create(evaluation: evaluation);
// Get evaluationEvaluation getResult = projectClient.Evaluations.Get(result.Name);
// List evaluationsforeach (var eval in projectClient.Evaluations.GetAll()){    Console.WriteLine($"{eval.DisplayName}: {eval.Status}");}

8. Get Azure OpenAI Chat Client

csharp
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

ToolClassPurpose
Code InterpreterCodeInterpreterToolDefinitionExecute Python code
File SearchFileSearchToolDefinitionSearch uploaded files
Function CallingFunctionToolDefinitionCall custom functions
Bing GroundingBingGroundingToolDefinitionWeb search via Bing
Azure AI SearchAzureAISearchToolDefinitionSearch Azure AI indexes
OpenAPIOpenApiToolDefinitionCall external APIs
Azure FunctionsAzureFunctionToolDefinitionInvoke Azure Functions
MCPMCPToolDefinitionModel Context Protocol tools

Key Types Reference

TypePurpose
AIProjectClientMain entry point
PersistentAgentsClientLow-level agent operations
PromptAgentDefinitionVersioned agent definition
AgentVersionVersioned agent instance
AIProjectConnectionConnection to Azure resource
AIProjectDeploymentModel deployment info
AIProjectDatasetDataset metadata
AIProjectIndexSearch index metadata
EvaluationEvaluation configuration and results

Best Practices

  1. Use DefaultAzureCredential for production authentication
  2. Use async methods (*Async) for all I/O operations
  3. Poll with appropriate delays (500ms recommended) when waiting for runs
  4. Clean up resources — delete threads, agents, and files when done
  5. Use versioned agents (via Azure.AI.Projects.OpenAI) for production scenarios
  6. Store connection IDs rather than names for tool configurations
  7. Use includeCredentials: true only when credentials are needed
  8. Handle pagination — use AsyncPageable<T> for listing operations

Error Handling

csharp
using Azure;
try{    var result = await projectClient.Evaluations.CreateAsync(evaluation);}catch (RequestFailedException ex){    Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");}

Related SDKs

SDKPurposeInstall
Azure.AI.ProjectsHigh-level project client (this SDK)dotnet add package Azure.AI.Projects
Azure.AI.Agents.PersistentLow-level agent operationsdotnet add package Azure.AI.Agents.Persistent
Azure.AI.Projects.OpenAIVersioned agents with OpenAIdotnet add package Azure.AI.Projects.OpenAI

Reference Links

来源与署名

来源:microsoft/skills位于.github/plugins/azure-sdk-dotnet/skills/azure-ai-projects-dotnet提交354361d

许可证: MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架