azure-ai-projects-dotnet

用途

Azure.AI.Projects 是面向 .NET 的 Azure AI Foundry 项目操作高级 SDK，用于在应用中统一管理 Azure AI Foundry 项目下的各类资源。其核心对象 AIProjectClient 作为主要入口点，向下暴露多个子客户端，覆盖智能体、连接、数据集、部署、评估、评估器、索引与遥测等操作。

安装

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

当前版本：GA v1.1.0、Preview v1.2.0-beta.5。

环境变量

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
CONNECTION_NAME=<your-connection-name>
AI_SEARCH_CONNECTION_NAME=<ai-search-connection>

认证

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

var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
AIProjectClient projectClient = new AIProjectClient(
    new Uri(endpoint), 
    new DefaultAzureCredential());

客户端层级

AIProjectClient
├── Agents          → AIProjectAgentsOperations（版本化智能体）
├── Connections     → ConnectionsClient
├── Datasets        → DatasetsClient
├── Deployments     → DeploymentsClient
├── Evaluations     → EvaluationsClient
├── Evaluators      → EvaluatorsClient
├── Indexes         → IndexesClient
├── Telemetry       → AIProjectTelemetry
├── OpenAI          → ProjectOpenAIClient（预览）
└── GetPersistentAgentsClient() → PersistentAgentsClient

主要能力与使用方式

持久化智能体

可通过 projectClient.GetPersistentAgentsClient() 获取底层智能体客户端，进而创建智能体、创建线程并运行、轮询运行状态、读取消息，并在完成后清理线程与智能体。示例中展示了创建数学辅导智能体、发送消息、轮询 RunStatus.Queued 与 RunStatus.InProgress 状态，以及通过 GetMessagesAsync 读取消息文本的流程。

版本化智能体与工具（预览）

使用 Azure.AI.Projects.OpenAI 命名空间，可基于 PromptAgentDefinition 定义带工具的智能体版本，例如 Web 搜索工具（可指定近似位置：国家、城市、区域），通过 CreateAgentVersionAsync 创建 AgentVersion，再用项目 OpenAI 的响应客户端获取回复。

连接

可列出全部连接、获取指定连接（includeCredentials 控制是否包含凭据）、获取默认连接，返回类型为 AIProjectConnection，包含名称与连接类型等信息。

部署

可列出全部部署、按发布者过滤（如 modelPublisher: "Microsoft"）、获取指定部署详情（如 ModelDeployment）。

数据集

支持上传单个文件（UploadFile）或整个文件夹（UploadFolder，可配合正则 filePattern 过滤文件）、获取数据集、删除数据集。

索引

可创建 Azure AI Search 索引（AzureAISearchIndex，可设置 Description）、创建或更新、列出索引、删除索引。

评估

可创建评估配置（如 EvaluatorIDs.Relevance，并通过 InitParams 指定 deployment_name）、创建评估并运行（Evaluation 包含 data 与 evaluators）、获取评估结果、列出全部评估。

获取 Azure OpenAI 聊天客户端

可通过 projectClient.GetConnection 获取连接并解析 URI，构建 AzureOpenAIClient 与 ChatClient，执行聊天补全。

可用的智能体工具

工具	类	用途
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	Model Context Protocol 工具

关键类型

AIProjectClient（主入口点）、PersistentAgentsClient（底层智能体操作）、PromptAgentDefinition（版本化智能体定义）、AgentVersion（版本化智能体实例）、AIProjectConnection、AIProjectDeployment、AIProjectDataset、AIProjectIndex、Evaluation。

适用场景

用于在 .NET 应用中执行 Azure AI Foundry 项目相关工作流：智能体创建与运行、连接与部署查询、数据集上传、索引创建、评估运行，以及接入 Azure OpenAI 聊天客户端。

最佳实践

生产环境使用 DefaultAzureCredential；所有 I/O 操作使用异步方法（*Async）；等待运行时以合适延迟轮询（推荐 500ms）；完成后清理资源（线程、智能体、文件）；生产场景使用版本化智能体；工具配置存储连接 ID 而非名称；仅在需要凭据时使用 includeCredentials: true；使用 AsyncPageable<T> 处理分页。

错误处理

using Azure;

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

参考链接

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

限制

仅当任务明确匹配上述范围时使用此技能。不要将其输出视为环境特定验证、测试或专家评审的替代。若缺少必需输入、权限、安全边界或成功标准，应停止并请求澄清。

技能介绍

用途

安装