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

現在のバージョン：GA 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 Search接続名
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;

// Web検索ツールを使用してエージェントを作成
PromptAgentDefinition agentDefinition = new(model: "gpt-4o-mini")
{
    Instructions = "あなたはWeb検索ができる便利なアシスタントです",
    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 Searchインデックスを作成
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 Chatクライアントの取得

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によるWeb検索
Azure AI Search	AzureAISearchToolDefinition	Azure AIインデックスの検索
OpenAPI	OpenApiToolDefinition	外部APIの呼び出し
Azure Functions	AzureFunctionToolDefinition	Azure Functionsの呼び出し
MCP	MCPToolDefinition	Model Context Protocolツール

主要型リファレンス

型	目的
AIProjectClient	メインエントリポイント
PersistentAgentsClient	低レベルエージェント操作
PromptAgentDefinition	バージョン管理エージェント定義
AgentVersion	バージョン管理エージェントインスタンス
AIProjectConnection	Azureリソースへの接続
AIProjectDeployment	モデルデプロイ情報
AIProjectDataset	データセットメタデータ
AIProjectIndex	検索インデックスメタデータ
Evaluation	評価設定と結果

ベストプラクティス

1. DefaultAzureCredentialを使用して本番認証を行う
2. 非同期メソッド（*Async）をすべてのI/O操作に使用する
3. 適切な遅延でポーリング（500ms推奨）して実行完了を待つ
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