Skip to content

AIProjectClient

Key Points

  • AIProjectClient is the entry point for Foundry SDK 2.0. Gives you typed clients for chat, embeddings, agents, evals, indexes.
  • Authenticated via managed identity / DefaultAzureCredential.
  • Returns IChatClient / IEmbeddingGenerator / agent clients / etc.
  • Use across Foundry features.

Construction

var client = new AIProjectClient(
    endpoint: new Uri("https://my-foundry.services.ai.azure.com/api/projects/my-project"),
    credential: new DefaultAzureCredential());

Chat

IChatClient chat = client.GetChatClient("gpt-4o-mini").AsIChatClient();

var resp = await chat.GetResponseAsync("Hello");

Embeddings

IEmbeddingGenerator<string, Embedding<float>> embed =
    client.GetEmbeddingsClient("text-embedding-3-small").AsIEmbeddingGenerator();

var emb = await embed.GenerateAsync("text");

Agents

var agentsClient = client.GetAgentsClient();
var agent = await agentsClient.CreateAgentAsync(new()
{
    Name = "MyAgent",
    Model = "gpt-4o-mini",
    Instructions = "..."
});

var thread = await agentsClient.CreateThreadAsync();
await agentsClient.CreateMessageAsync(thread.Id, MessageRole.User, "Hello");
var run = await agentsClient.CreateRunAsync(thread.Id, agent.Id);

while (run.Status is "queued" or "in_progress")
{
    await Task.Delay(500);
    run = await agentsClient.GetRunAsync(thread.Id, run.Id);
}

var messages = await agentsClient.GetMessagesAsync(thread.Id);

Vector indexes

var indexes = client.GetIndexesClient();
var index = await indexes.GetAsync("my-index");

// Search
var results = await indexes.SearchAsync(index.Id, queryEmb);

Evaluations

var evals = client.GetEvaluationsClient();
var run = await evals.CreateRunAsync(new()
{
    Dataset = ...,
    Metrics = ["groundedness", "relevance"]
});

while (run.Status is "running") { /* poll */ }

Connections

Foundry projects can have configured connections (Azure AI Search, Cosmos, Blob, etc.):

var connections = client.GetConnectionsClient();
var conn = await connections.GetAsync("my-search-conn");

Use these in agents (RAG over a Search index).

Multi-project

Each Foundry project is isolated. App connects to one project; staging vs prod are different projects.

DI registration

builder.Services.AddSingleton<AIProjectClient>(sp =>
    new AIProjectClient(uri, new DefaultAzureCredential()));

builder.Services.AddSingleton<IChatClient>(sp =>
    sp.GetRequiredService<AIProjectClient>().GetChatClient("gpt-4o-mini").AsIChatClient());

Configuration

"AzureFoundry": {
  "ProjectEndpoint": "https://...",
  "ChatModel": "gpt-4o-mini",
  "EmbedModel": "text-embedding-3-small"
}

var endpoint = new Uri(builder.Configuration["AzureFoundry:ProjectEndpoint"]!);

Error handling

try { /* ... */ }
catch (RequestFailedException ex) when (ex.Status == 429) { /* rate limited */ }
catch (RequestFailedException ex) when (ex.Status == 401) { /* auth */ }

Senior considerations

  • One AIProjectClient per process — singleton.
  • DefaultAzureCredential chains correctly across dev / prod.
  • Per-environment projects: separate auth, configs.
  • Track project-level usage for cost.

Cross-references