microsoft/azure-ai-projects-dotnet

Azure.AI.Projects (.NET)

用於 Azure AI Foundry 專案操作的高階 SDK，包含代理程式、連線、資料集、部署、評估與索引。

安裝

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

# 選用：若需搭配 OpenAI 擴充功能的版本化代理程式
dotnet add package Azure.AI.Projects.OpenAI --prerelease

# 選用：若需低階代理程式操作
dotnet add package Azure.AI.Agents.Persistent --prerelease

目前版本：正式版 v1.1.0，預覽版 v1.2.0-beta.5

環境變數

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>  # 必要：Azure AI 專案端點
MODEL_DEPLOYMENT_NAME=gpt-4o-mini  # 必要：模型部署名稱
CONNECTION_NAME=<your-connection-name>  # 選用：專案連線名稱
AI_SEARCH_CONNECTION_NAME=<ai-search-connection>  # 選用：Azure AI 搜尋連線名稱
AZURE_TOKEN_CREDENTIALS=prod  # 僅在實際生產環境中使用 DefaultAzureCredential 時需要

驗證

using Azure.Identity;
using Azure.AI.Projects;

var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
// 本機開發：DefaultAzureCredential。實際生產環境：設定 AZURE_TOKEN_CREDENTIALS=prod 或 AZURE_TOKEN_CREDENTIALS=<specific_credential>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// 或者在實際生產環境中直接使用特定憑證：
// 請參閱 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);

用戶端階層

AIProjectClient
├── Agents          → AIProjectAgentsOperations (版本化代理程式)
├── Connections     → ConnectionsClient
├── Datasets        → DatasetsClient
├── Deployments     → DeploymentsClient
├── Evaluations     → EvaluationsClient
├── Evaluators      → EvaluatorsClient
├── Indexes         → IndexesClient
├── Telemetry       → AIProjectTelemetry
├── OpenAI          → ProjectOpenAIClient (預覽版)
└── GetPersistentAgentsClient() → PersistentAgentsClient

核心工作流程

1. 取得不固定代理程式用戶端

// 從專案用戶端取得低階代理程式用戶端
PersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();

// 建立代理程式
PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Math Tutor",
    instructions: "你是一位個人數學家教。");

// 建立執行緒並執行
PersistentAgentThread thread = await agentsClient.Threads.CreateThreadAsync();
await agentsClient.Messages.CreateMessageAsync(thread.Id, MessageRole.User, "解出 3x + 11 = 14");
ThreadRun run = await agentsClient.Runs.CreateRunAsync(thread.Id, agent.Id);

// 輪詢直到完成
do
{
    await Task.Delay(500);
    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

// 取得訊息
await foreach (var msg in agentsClient.Messages.GetMessagesAsync(thread.Id))
{
    foreach (var content in msg.ContentItems)
    {
        if (content is MessageTextContent textContent)
            Console.WriteLine(textContent.Text);
    }
}

// 清理資源
await agentsClient.Threads.DeleteThreadAsync(thread.Id);
await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. 版本化代理程式與工具（預覽版）

using Azure.AI.Projects.OpenAI;

// 建立具備網路搜尋工具的代理程式
PromptAgentDefinition agentDefinition = new(model: "gpt-4o-mini")
{
    Instructions = "你是一位可以搜尋網路的實用助理",
    Tools = {
        ResponseTool.CreateWebSearchTool(
            userLocation: WebSearchToolLocation.CreateApproximateLocation(
                country: "US",
                city: "Seattle",
                region: "Washington"
            )
        ),
    }
};

AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
    agentName: "myAgent",
    options: new(agentDefinition));

// 取得回應用戶端
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

// 建立回應
ResponseResult response = responseClient.CreateResponse("西雅圖的天氣如何？");
Console.WriteLine(response.GetOutputText());

// 清理資源
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. 連線

// 列出所有連線
foreach (AIProjectConnection connection in projectClient.Connections.GetConnections())
{
    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");
}

// 取得特定連線
AIProjectConnection conn = projectClient.Connections.GetConnection(
    connectionName, 
    includeCredentials: true);

// 取得預設連線
AIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(
    includeCredentials: false);

4. 部署

// 列出所有部署
foreach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments())
{
    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");
}

// 依發行者篩選
foreach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft"))
{
    Console.WriteLine(deployment.Name);
}

// 取得特定部署
ModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. 資料集

// 上傳單一檔案
FileDataset fileDataset = projectClient.Datasets.UploadFile(
    name: "my-dataset",
    version: "1.0",
    filePath: "data/training.txt",
    connectionName: connectionName);

// 上傳資料夾
FolderDataset folderDataset = projectClient.Datasets.UploadFolder(
    name: "my-dataset",
    version: "2.0",
    folderPath: "data/training",
    connectionName: connectionName,
    filePattern: new Regex(".*\\.txt"));

// 取得資料集
AIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");

// 刪除資料集
projectClient.Datasets.Delete("my-dataset", "1.0");

6. 索引

// 建立 Azure AI 搜尋索引
AzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName)
{
    Description = "範例索引"
};

searchIndex = (AzureAISearchIndex)projectClient.Indexes.CreateOrUpdate(
    name: "my-index",
    version: "1.0",
    index: searchIndex);

// 列出索引
foreach (AIProjectIndex index in projectClient.Indexes.GetIndexes())
{
    Console.WriteLine(index.Name);
}

// 刪除索引
projectClient.Indexes.Delete(name: "my-index", version: "1.0");

7. 評估

// 建立評估設定
var evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);
evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));

// 建立評估
Evaluation evaluation = new Evaluation(
    data: new InputDataset("<dataset_id>"),
    evaluators: new Dictionary<string, EvaluatorConfiguration> 
    { 
        { "relevance", evaluatorConfig } 
    }
)
{
    DisplayName = "範例評估"
};

// 執行評估
Evaluation result = projectClient.Evaluations.Create(evaluation: evaluation);

// 取得評估
Evaluation getResult = projectClient.Evaluations.Get(result.Name);

// 列出評估
foreach (var eval in projectClient.Evaluations.GetAll())
{
    Console.WriteLine($"{eval.DisplayName}: {eval.Status}");
}

8. 取得 Azure OpenAI 聊天用戶端

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("無效的 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("列出所有彩虹的顏色");
Console.WriteLine(result.Content[0].Text);

可用的代理程式工具

工具	類別	用途
Code Interpreter	CodeInterpreterToolDefinition	執行 Python 程式碼
File Search	FileSearchToolDefinition	搜尋已上傳的檔案
Function Calling	FunctionToolDefinition	呼叫自訂函式
Bing Grounding	BingGroundingToolDefinition	透過 Bing 進行網路搜尋
Azure AI Search	AzureAISearchToolDefinition	搜尋 Azure AI 索引
OpenAPI	OpenApiToolDefinition	呼叫外部 API
Azure Functions	AzureFunctionToolDefinition	叫用 Azure Functions
MCP	MCPToolDefinition	模型上下文協定工具

重要類型參考

類型	用途
AIProjectClient	主要進入點
PersistentAgentsClient	低階代理程式操作
PromptAgentDefinition	版本化代理程式定義
AgentVersion	版本化代理程式實例
AIProjectConnection	Azure 資源連線
AIProjectDeployment	模型部署資訊
AIProjectDataset	資料集中繼資料
AIProjectIndex	搜尋索引中繼資料
Evaluation	評估設定與結果

最佳實務

1. 使用 DefaultAzureCredential 進行實際生產環境驗證
2. 使用非同步方法 (*Async) 進行所有 I/O 操作
3. 使用適當延遲進行輪詢（建議 500 毫秒）等待執行完成
4. 清理資源 — 完成後刪除執行緒、代理程式與檔案
5. 使用版本化代理程式（透過 Azure.AI.Projects.OpenAI）處理實際生產環境情境
6. 儲存連線 ID 而非名稱，用於工具設定
7. 僅在需要時使用 includeCredentials: true
8. 處理分頁 — 使用 AsyncPageable<T> 處理列出操作

錯誤處理

using Azure;

try
{
    var result = await projectClient.Evaluations.CreateAsync(evaluation);
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"錯誤：{ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

相關 SDK

SDK	用途	安裝方式
Azure.AI.Projects	高階專案用戶端（此 SDK）	dotnet add package Azure.AI.Projects
Azure.AI.Agents.Persistent	低階代理程式操作	dotnet add package Azure.AI.Agents.Persistent
Azure.AI.Projects.OpenAI	搭配 OpenAI 的版本化代理程式	dotnet add package Azure.AI.Projects.OpenAI

參考連結

資源	URL
NuGet 套件	https://www.nuget.org/packages/Azure.AI.Projects
API 參考	https://learn.microsoft.com/dotnet/api/azure.ai.projects
GitHub 原始碼	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects
範例	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/samples