microsoft/semantic-kernel · error · InvalidOperationException

AzureAI agents client not found.

Error message

AzureAI agents client not found.

What it means

Thrown by AgentDefinitionExtensions.GetAgentsClient when no PersistentAgentsClient can be resolved for the agent definition. The method first checks for a connection with an endpoint in the definition's Model.Connection; if that's absent, it falls back to kernel.GetAllServices<PersistentAgentsClient>(). If neither yields a client, an InvalidOperationException is thrown.

Source

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

        // Use the agent connection as the first option
        var connection = agentDefinition?.Model?.Connection;
        if (connection is not null)
        {
            if (connection.ExtensionData.TryGetValue(Endpoint, out var value) && value is string endpoint)
            {
#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>();
                return AzureAIAgent.CreateAgentsClient(endpoint, tokenCredential, httpClient);
            }
        }

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

    /// <summary>
    /// Return the <see cref="PersistentAgentsClient"/> to be used with the specified <see cref="AgentDefinition"/>.
    /// </summary>
    /// <param name="agentDefinition">Agent definition which will be used to provide connection for the <see cref="PersistentAgentsClient"/>.</param>
    /// <param name="kernel">Kernel instance which will be used to resolve a default <see cref="PersistentAgentsClient"/>.</param>
    public static AIProjectClient GetProjectsClient(this AgentDefinition agentDefinition, Kernel kernel)
    {
        Verify.NotNull(agentDefinition);

        // Use the agent connection as the first option
        var connection = agentDefinition?.Model?.Connection;
        if (connection is not null)
        {
            if (connection.ExtensionData.TryGetValue(Endpoint, out var value) && value is string endpoint)
            {
#pragma warning disable CA2000 // Dispose objects before losing scope, not relevant because the HttpClient is created and may be used elsewhere

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Register a PersistentAgentsClient on the kernel: builder.Services.AddSingleton<PersistentAgentsClient>(client).
2. Or add an endpoint to the agent definition's model connection: { "model": { "connection": { "endpoint": "https://<your>.services.ai.azure.com" } } }.
3. Verify the kernel passed to CreateAsync is the same one with the registered client.
4. Ensure a TokenCredential is also registered if using the endpoint-based path.

Example fix

// before
var kernel = new Kernel();
await factory.CreateAsync(kernel, definition); // throws: no client

// after
var kernel = new Kernel();
kernel.Services.AddSingleton<PersistentAgentsClient>(
    new PersistentAgentsClient(endpoint, tokenCredential));
await factory.CreateAsync(kernel, definition);

bool hasClientInKernel = kernel.GetAllServices<PersistentAgentsClient>().Any();
bool hasEndpointInDefinition = definition?.Model?.Connection?.ExtensionData
    ?.ContainsKey("endpoint") == true;
if (!hasClientInKernel && !hasEndpointInDefinition)
{
    throw new InvalidOperationException(
        "No PersistentAgentsClient registered and no endpoint in definition.");
}

try
{
    var client = definition.GetAgentsClient(kernel);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("AzureAI agents client not found"))
{
    _logger.LogError("No PersistentAgentsClient registered on kernel.");
    throw;
}

When it happens

Trigger: Creating an Azure AI agent from a declarative definition where neither (a) the definition's Model.Connection.ExtensionData contains an 'endpoint' key, nor (b) a PersistentAgentsClient is registered as a kernel service. The factory cannot connect to Azure AI Agents without one of these.

Common situations: Forgot to register PersistentAgentsClient on the kernel via AddSingleton or builder.Services. Definition file missing the Model.Connection.Endpoint field. Using a connection type that doesn't expose ExtensionData['endpoint']. DI container misconfiguration. Wrong kernel instance passed to the factory.

Related errors

• Unable to create Azure AI tool definition because of unsuppo
• AzureAI project client not found.
• Invalid OpenAI client type '{connection.Type}' was specified
• Configuration not found, please setup the notebooks first us
• AZURE_OPENAI_ENDPOINT is not set.

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