{"record":{"id":"8f3605f0a47129f6","repo":"microsoft/semantic-kernel","slug":"agent-with-name-agentid-type-not-found","errorCode":null,"errorMessage":"Agent with name {agentId.Type} not found.","messagePattern":"Agent with name (.+?) not found\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/Runtime/InProcess/InProcessRuntime.cs","lineNumber":423,"sourceCode":"        MessageContext messageContext = new(envelope.MessageId, combinedSource.Token)\n        {\n            Sender = envelope.Sender,\n            IsRpc = false\n        };\n\n        AgentId receiver = envelope.Receiver.Value;\n        IHostableAgent agent = await this.EnsureAgentAsync(receiver).ConfigureAwait(false);\n\n        return await agent.OnMessageAsync(envelope.Message, messageContext).ConfigureAwait(false);\n    }\n\n    private async ValueTask<IHostableAgent> EnsureAgentAsync(AgentId agentId)\n    {\n        if (!this.agentInstances.TryGetValue(agentId, out IHostableAgent? agent))\n        {\n            if (!this._agentFactories.TryGetValue(agentId.Type, out Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>>? factoryFunc))\n            {\n                throw new InvalidOperationException($\"Agent with name {agentId.Type} not found.\");\n            }\n\n            agent = await factoryFunc(agentId, this).ConfigureAwait(false);\n            this.agentInstances.Add(agentId, agent);\n        }\n\n        return this.agentInstances[agentId];\n    }\n\n    private async Task FinishAsync(CancellationToken token)\n    {\n        foreach (IHostableAgent agent in this.agentInstances.Values)\n        {\n            if (!token.IsCancellationRequested)\n            {\n                await agent.CloseAsync().ConfigureAwait(false);\n            }\n        }","sourceCodeStart":405,"sourceCodeEnd":441,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/Runtime/InProcess/InProcessRuntime.cs#L405-L441","documentation":"The InProcessRuntime threw this because it received a message (direct send, or a publish mapped through a subscription) whose target AgentId.Type has no registered factory. EnsureAgentAsync first checks the live agentInstances cache, then looks up _agentFactories by agentId.Type; if neither matches, it throws. In short: the runtime was asked to deliver to an agent type it was never told how to build.","triggerScenarios":"Calling runtime.SendMessageAsync(message, new AgentId(\"SomeType\", key)) before RegisterAgentFactoryAsync(\"SomeType\", ...). Or PublishMessageAsync to a TopicId whose TypePrefixSubscription/Subscription maps to an AgentType that was never registered. Also GetAgentMetadataAsync, SaveAgentStateAsync, LoadAgentStateAsync, and GetAgentAsync(lazy:false) on an unregistered AgentId.","commonSituations":"Typo or casing mismatch between the string used at RegisterAgentFactoryAsync and the AgentType at send time (the dictionary key is an exact match, case-sensitive). Registering the agent on one runtime instance but sending on another. Forgetting to await RegisterAgentFactoryAsync before publishing. Restoring state (LoadStateAsync) that references agent types no longer registered.","solutions":["Register the agent factory for that exact AgentType string before any send/publish: await runtime.RegisterAgentFactoryAsync(\"<type>\", (id, rt) => ...);","Verify the AgentType used in AgentId and in subscriptions matches the registered type character-for-character (watch case and whitespace).","Ensure subscriptions (AddSubscriptionAsync) map topics to agent types that are all registered; a publish will route through subscription.MapToAgent(topic) and hit EnsureAgentAsync.","Confirm you are calling send/publish on the same InProcessRuntime instance you registered factories on.","If loading persisted state, register every agent type referenced in the state before calling LoadStateAsync."],"exampleFix":"// before\nawait runtime.SendMessageAsync(msg, new AgentId(\"Assistant\", \"a1\"));\n// -> InvalidOperationException: Agent with name Assistant not found.\n\n// after - register the factory first, matching the type exactly\nawait runtime.RegisterAgentFactoryAsync(\"Assistant\",\n    (id, rt) => ValueTask.FromResult<IHostableAgent>(new MyAgent(id, rt)));\nawait runtime.SendMessageAsync(msg, new AgentId(\"Assistant\", \"a1\"));","handlingStrategy":"validation","validationCode":"// Before sending/publishing, confirm the target type is registered.\n// (Reflection-based check because _agentFactories is private; prefer tracking\n//  registered types yourself in a set as you call RegisterAgentFactoryAsync.)\nHashSet<string> registeredTypes = new();\n\nasync ValueTask Register(string type, Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>> factory)\n{\n    await runtime.RegisterAgentFactoryAsync(type, factory);\n    registeredTypes.Add(type);\n}\n\nasync Task SendSafe(object msg, AgentId recipient)\n{\n    if (!registeredTypes.Contains(recipient.Type))\n        throw new InvalidOperationException($\"Refusing to send: agent type '{recipient.Type}' is not registered.\");\n    await runtime.SendMessageAsync(msg, recipient);\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await runtime.SendMessageAsync(msg, recipient);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"not found\"))\n{\n    // agent type not registered; log recipient.Type and register or fail gracefully\n    logger.LogWarning(\"Agent type {Type} not registered: {Msg}\", recipient.Type, ex.Message);\n}","preventionTips":["Register every agent factory before calling StartAsync or any send/publish.","Keep a single source of truth for AgentType string constants to avoid typos and casing mismatches.","Register all agent types referenced by subscriptions and by any persisted state you load.","Use the same runtime instance for registration and for messaging."],"tags":["csharp","dotnet","semantic-kernel","agents","configuration","agent-runtime"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}