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: "数学家教",
    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);

可用的代理工具

工具	类	用途
代码解释器	CodeInterpreterToolDefinition	执行 Python 代码
文件搜索	FileSearchToolDefinition	搜索上传的文件
函数调用	FunctionToolDefinition	调用自定义函数
Bing 搜索	BingGroundingToolDefinition	通过 Bing 进行网络搜索
Azure AI 搜索	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

参考链接

资源	链接
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