microsoft/semantic-kernel · error · InvalidOperationException

AzureAI project client not found.

Error message

AzureAI project client not found.

What it means

Thrown by AgentDefinitionExtensions.GetProjectsClient when it cannot obtain an Azure AI Project client. The method first tries to build an AIProjectClient from the agent definition's Model.Connection endpoint; only if that connection (or its endpoint) is absent does it fall back to kernel.GetAllServices<AIProjectClient>(). If neither path yields a client, it throws InvalidOperationException. This is a startup/configuration error, not a transient network failure.

Source

Thrown at dotnet/src/Agents/AzureAI/Extensions/AgentDefinitionExtensions.cs:168

            {
#pragma warning disable CA2000 // Dispose objects before losing scope, not relevant because the HttpClient is created and may be used elsewhere
                var httpClient = HttpClientProvider.GetHttpClient(kernel.Services);
#pragma warning restore CA2000 // Dispose objects before losing scope

                var tokenCredential = kernel.Services.GetRequiredService<TokenCredential>();
                AIProjectClientOptions options =
                    new()
                    {
                        Transport = new HttpClientPipelineTransport(httpClient),
                        RetryPolicy = new ClientRetryPolicy(maxRetries: 0) // Disable retry policy if a custom HttpClient is provided.
                    };
                return new AIProjectClient(new Uri(endpoint), tokenCredential, options);
            }
        }

        // Return the client registered on the kernel
        var client = kernel.GetAllServices<AIProjectClient>().FirstOrDefault();
        return client ?? throw new InvalidOperationException("AzureAI project client not found.");
    }

    #region private
    private static CodeInterpreterToolResource? GetCodeInterpreterToolResource(this AgentDefinition agentDefinition)
    {
        Verify.NotNull(agentDefinition);

        CodeInterpreterToolResource? resource = null;

        var codeInterpreter = agentDefinition.GetFirstToolDefinition(CodeInterpreterType);
        if (codeInterpreter is not null)
        {
            var fileIds = codeInterpreter.GetFileIds();
            var dataSources = codeInterpreter.GetDataSources();
            if (fileIds is not null || dataSources is not null)
            {
                resource = new CodeInterpreterToolResource();
                if (fileIds is not null)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Register an AIProjectClient on the kernel: builder.Services.AddSingleton<AIProjectClient>(new AIProjectClient(new Uri(endpoint), credential));
2. Alternatively, set the connection endpoint in the agent definition model so GetProjectsClient builds the client itself.
3. Ensure a TokenCredential is also registered (kernel.Services.GetRequiredService<TokenCredential> is called on that path).
4. Verify the agent definition file's connection section is parsed correctly (check Model.Model.Connection?.ExtensionData for the 'endpoint' key).

Example fix

// before
var kernel = Kernel.CreateBuilder().Build();
// ... agent uses AzureAI tools -> throws 160

// after
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton(new AIProjectClient(new Uri(endpoint), tokenCredential));
var kernel = kernelBuilder.Build();

// Before calling code that uses AzureAI tools, verify a client is resolvable.
bool hasConnectionEndpoint =
    agentDefinition?.Model?.Connection?.ExtensionData.TryGetValue("endpoint", out _) ?? false;
bool hasRegisteredClient = kernel.GetAllServices<AIProjectClient>().Any();
if (!hasConnectionEndpoint && !hasRegisteredClient)
{
    throw new InvalidOperationException(
        "No AIProjectClient available. Register one on the kernel or set connection.endpoint.");
}

static bool HasProjectsClient(AgentDefinition def, Kernel kernel) =>
    (def?.Model?.Connection?.ExtensionData.TryGetValue("endpoint", out _) ?? false)
    || kernel.GetAllServices<AIProjectClient>().Any();

try { var client = agentDefinition.GetProjectsClient(kernel); }
catch (InvalidOperationException ex) when (ex.Message.Contains("project client not found"))
{ /* register AIProjectClient, or fail fast with actionable guidance */ }

When it happens

Trigger: Calling GetProjectsClient(agentDefinition, kernel) where agentDefinition.Model.Connection is null or lacks an 'endpoint' key, AND the Kernel has no AIProjectClient registered as a service. Also triggered when a TokenCredential is missing (that path throws earlier, but missing registration is the direct cause here).

Common situations: Developer forgot to register AIProjectClient on the kernel builder (e.g., missing AddAzureAIAgent / services.AddSingleton<AIProjectClient>). Agent YAML/JSON template missing the connection.endpoint field. Running in a DI container where the Azure AI services were never added. Misconfigured KernelFactory in tests.

Related errors

• AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.
• OPENAI_API_KEY is not set.
• OpenAI/Azure OpenAI configuration was not found.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ec7d2ce1e0d28cde. Report an issue: GitHub.