azure-ai-projects-dotnet

Azure.AI.Projects (.NET)

エージェント、接続、データセット、デプロイ、評価、インデックスなど、Azure AI Foundry プロジェクトの操作に対応する高レベル SDK です。

インストール

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

# Optional: For versioned agents with OpenAI extensions
dotnet add package Azure.AI.Projects.OpenAI --prerelease

# Optional: For low-level agent operations
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>
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 (versioned agents)
├── Connections     → ConnectionsClient
├── Datasets        → DatasetsClient
├── Deployments     → DeploymentsClient
├── Evaluations     → EvaluationsClient
├── Evaluators      → EvaluatorsClient
├── Indexes         → IndexesClient
├── Telemetry       → AIProjectTelemetry
├── OpenAI          → ProjectOpenAIClient (preview)
└── GetPersistentAgentsClient() → PersistentAgentsClient

コアワークフロー

以下のスニペットは GA とプレビューの両方の API を対象としています。互換性のあるパッケージバージョンを固定し、組み合わせて使用する前に、リンク先の SDK サンプルでシグネチャを確認してください。プロジェクトのエンドポイント、テナント、デプロイ、予算、およびアップロードが許可されたデータを確認してください。エージェントの実行や評価では、課金が発生したり、外部ツールが呼び出されたりする場合があります。すべてのポーリングにキャンセルまたは期限を設定し、Completed と Failed／Cancelled／RequiresAction を区別してください。正常に完了した場合にのみ、出力を確認してください。クリーンアップでは、この実行で作成したリソースのみを削除してください。必要な証拠を保存したうえで finally ブロックを使用し、サンプルの終了時にユーザー所有のリソースを削除しないでください。

1. 永続エージェントのクライアントを取得する

// Get low-level agents client from project client
PersistentAgentsClient agentsClient = projectClient.GetPersistentAgentsClient();

// Create agent
PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Math Tutor",
    instructions: "You are a personal math tutor.");

// Create thread and run
PersistentAgentThread 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 completion
do
{
    await Task.Delay(500);
    run = await agentsClient.Runs.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

// Get messages
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);
    }
}

// Cleanup
await agentsClient.Threads.DeleteThreadAsync(thread.Id);
await agentsClient.Administration.DeleteAgentAsync(agent.Id);

2. ツールを使用するバージョン管理されたエージェント（プレビュー）

using Azure.AI.Projects.OpenAI;

// Create agent with web search tool
PromptAgentDefinition 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 client
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

// Create response
ResponseResult response = responseClient.CreateResponse("What's the weather in Seattle?");
Console.WriteLine(response.GetOutputText());

// Cleanup
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

3. 接続

// List all connections
foreach (AIProjectConnection connection in projectClient.Connections.GetConnections())
{
    Console.WriteLine($"{connection.Name}: {connection.ConnectionType}");
}

// Get specific connection
AIProjectConnection conn = projectClient.Connections.GetConnection(
    connectionName, 
    includeCredentials: false);

// Get default connection
AIProjectConnection defaultConn = projectClient.Connections.GetDefaultConnection(
    includeCredentials: false);

4. デプロイ

// List all deployments
foreach (AIProjectDeployment deployment in projectClient.Deployments.GetDeployments())
{
    Console.WriteLine($"{deployment.Name}: {deployment.ModelName}");
}

// Filter by publisher
foreach (var deployment in projectClient.Deployments.GetDeployments(modelPublisher: "Microsoft"))
{
    Console.WriteLine(deployment.Name);
}

// Get specific deployment
ModelDeployment details = (ModelDeployment)projectClient.Deployments.GetDeployment("gpt-4o-mini");

5. データセット

// Upload single file
FileDataset fileDataset = projectClient.Datasets.UploadFile(
    name: "my-dataset",
    version: "1.0",
    filePath: "data/training.txt",
    connectionName: connectionName);

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

// Get dataset
AIProjectDataset dataset = projectClient.Datasets.GetDataset("my-dataset", "1.0");

// Delete dataset
projectClient.Datasets.Delete("my-dataset", "1.0");

6. インデックス

// Create Azure AI Search index
AzureAISearchIndex searchIndex = new(aiSearchConnectionName, aiSearchIndexName)
{
    Description = "Sample Index"
};

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

// List indexes
foreach (AIProjectIndex index in projectClient.Indexes.GetIndexes())
{
    Console.WriteLine(index.Name);
}

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

7. 評価

// Create evaluation configuration
var evaluatorConfig = new EvaluatorConfiguration(id: EvaluatorIDs.Relevance);
evaluatorConfig.InitParams.Add("deployment_name", BinaryData.FromObjectAsJson("gpt-4o"));

// Create evaluation
Evaluation evaluation = new Evaluation(
    data: new InputDataset("<dataset_id>"),
    evaluators: new Dictionary<string, EvaluatorConfiguration> 
    { 
        { "relevance", evaluatorConfig } 
    }
)
{
    DisplayName = "Sample Evaluation"
};

// Run evaluation
Evaluation result = projectClient.Evaluations.Create(evaluation: evaluation);

// Get evaluation
Evaluation getResult = projectClient.Evaluations.Get(result.Name);

// List evaluations
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("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);

利用可能なエージェントツール

ツール	クラス	用途
コードインタープリター	CodeInterpreterToolDefinition	Python コードを実行
ファイル検索	FileSearchToolDefinition	アップロードしたファイルを検索
関数呼び出し	FunctionToolDefinition	カスタム関数を呼び出す
Bing グラウンディング	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	Azure リソースへの接続
AIProjectDeployment	モデルのデプロイ情報
AIProjectDataset	データセットのメタデータ
AIProjectIndex	検索インデックスのメタデータ
Evaluation	評価の構成と結果

ベストプラクティス

1. 本番環境の認証には DefaultAzureCredential を使用する
2. すべての I/O 操作には非同期メソッド（*Async）を使用する
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($"Error: {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

使用する場面

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記のスコープに明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、成功基準が欠けている場合は、作業を中断して確認を求めてください。