{"record":{"id":"665ba4c19fcb57e7","repo":"microsoft/semantic-kernel","slug":"azureai-agents-client-not-found","errorCode":null,"errorMessage":"AzureAI agents client not found.","messagePattern":"AzureAI agents client not found\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/AzureAI/Extensions/AgentDefinitionExtensions.cs","lineNumber":133,"sourceCode":"\n        // Use the agent connection as the first option\n        var connection = agentDefinition?.Model?.Connection;\n        if (connection is not null)\n        {\n            if (connection.ExtensionData.TryGetValue(Endpoint, out var value) && value is string endpoint)\n            {\n#pragma warning disable CA2000 // Dispose objects before losing scope, not relevant because the HttpClient is created and may be used elsewhere\n                var httpClient = HttpClientProvider.GetHttpClient(kernel.Services);\n#pragma warning restore CA2000 // Dispose objects before losing scope\n\n                var tokenCredential = kernel.Services.GetRequiredService<TokenCredential>();\n                return AzureAIAgent.CreateAgentsClient(endpoint, tokenCredential, httpClient);\n            }\n        }\n\n        // Return the client registered on the kernel\n        var client = kernel.GetAllServices<PersistentAgentsClient>().FirstOrDefault();\n        return client ?? throw new InvalidOperationException(\"AzureAI agents client not found.\");\n    }\n\n    /// <summary>\n    /// Return the <see cref=\"PersistentAgentsClient\"/> to be used with the specified <see cref=\"AgentDefinition\"/>.\n    /// </summary>\n    /// <param name=\"agentDefinition\">Agent definition which will be used to provide connection for the <see cref=\"PersistentAgentsClient\"/>.</param>\n    /// <param name=\"kernel\">Kernel instance which will be used to resolve a default <see cref=\"PersistentAgentsClient\"/>.</param>\n    public static AIProjectClient GetProjectsClient(this AgentDefinition agentDefinition, Kernel kernel)\n    {\n        Verify.NotNull(agentDefinition);\n\n        // Use the agent connection as the first option\n        var connection = agentDefinition?.Model?.Connection;\n        if (connection is not null)\n        {\n            if (connection.ExtensionData.TryGetValue(Endpoint, out var value) && value is string endpoint)\n            {\n#pragma warning disable CA2000 // Dispose objects before losing scope, not relevant because the HttpClient is created and may be used elsewhere","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/AzureAI/Extensions/AgentDefinitionExtensions.cs#L115-L151","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register a PersistentAgentsClient on the kernel: builder.Services.AddSingleton<PersistentAgentsClient>(client).","Or add an endpoint to the agent definition's model connection: { \"model\": { \"connection\": { \"endpoint\": \"https://<your>.services.ai.azure.com\" } } }.","Verify the kernel passed to CreateAsync is the same one with the registered client.","Ensure a TokenCredential is also registered if using the endpoint-based path."],"exampleFix":"// before\nvar kernel = new Kernel();\nawait factory.CreateAsync(kernel, definition); // throws: no client\n\n// after\nvar kernel = new Kernel();\nkernel.Services.AddSingleton<PersistentAgentsClient>(\n    new PersistentAgentsClient(endpoint, tokenCredential));\nawait factory.CreateAsync(kernel, definition);","handlingStrategy":"validation","validationCode":"bool hasClientInKernel = kernel.GetAllServices<PersistentAgentsClient>().Any();\nbool hasEndpointInDefinition = definition?.Model?.Connection?.ExtensionData\n    ?.ContainsKey(\"endpoint\") == true;\nif (!hasClientInKernel && !hasEndpointInDefinition)\n{\n    throw new InvalidOperationException(\n        \"No PersistentAgentsClient registered and no endpoint in definition.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    var client = definition.GetAgentsClient(kernel);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"AzureAI agents client not found\"))\n{\n    _logger.LogError(\"No PersistentAgentsClient registered on kernel.\");\n    throw;\n}","preventionTips":["Register PersistentAgentsClient on the kernel at startup via DI.","Include endpoint and TokenCredential in the agent definition as a fallback.","Validate kernel service registration in startup tests."],"tags":["azureai","configuration","di","agent-definition","invalidoperation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}