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 從公開儲存庫中收錄這些內容。

檢舉或申請下架