{"record":{"id":"c117bbfb61353893","repo":"microsoft/autogen","slug":"agent-with-name-agentid-type-not-found-c117bb","errorCode":null,"errorMessage":"Agent with name {agentId.Type} not found.","messagePattern":"Agent with name (.+?) not found\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs","lineNumber":142,"sourceCode":"        return this.ExecuteTracedAsync(async () =>\n        {\n            MessageDelivery delivery = new MessageEnvelope(message, messageId, cancellationToken)\n                                            .WithSender(sender)\n                                            .ForSend(recepient, this.SendMessageServicer);\n\n            this.messageDeliveryQueue.Enqueue(delivery);\n\n            return await delivery.Future;\n        });\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 Exception($\"Agent with name {agentId.Type} not found.\");\n            }\n\n            agent = await factoryFunc(agentId, this);\n            this.agentInstances.Add(agentId, agent);\n        }\n\n        return this.agentInstances[agentId];\n    }\n\n    public async ValueTask<AgentId> GetAgentAsync(AgentId agentId, bool lazy = true)\n    {\n        if (!lazy)\n        {\n            await this.EnsureAgentAsync(agentId);\n        }\n\n        return agentId;\n    }","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs#L124-L160","documentation":"EnsureAgentAsync lazily materializes agents: it looks the AgentId up in the instance cache, then in the registered factory map. If no factory was registered for the agent's Type (the first component of AgentId / the subscription target), the runtime has no way to construct the agent and throws a generic Exception with the type name. This almost always means the agent type was never registered with the runtime before a message targeted it.","triggerScenarios":"Sending a message to new AgentId(\"ChatAgent\", key) when RegisterAgentFactoryAsync(\"ChatAgent\", ...) was never called; a TypePrefixSubscription/TypeSubscription mapping a topic to an agent type that is not registered; checkpoint/state loading (SaveAgentStateAsync or LoadStateAsync) referencing an agent whose type is no longer registered — note LoadStateAsync guards this case, but SaveAgentStateAsync calls EnsureAgentAsync directly.","commonSituations":"Forgetting to register the agent in the host startup (e.g. missing AddAgentAsync/<typeof(TAgent)> registration);renaming an agent class/type so the subscription maps to a stale type string;loading a saved checkpoint from a build where the agent type existed but the current build removed it;typo in the type string used in a subscription definition.","solutions":["Register a factory for the type before it receives messages: await runtime.RegisterAgentFactoryAsync(\"ChatAgent\", (id, rt) => ...).","If using the higher-level hosting helpers, verify the agent type is included at startup (agent worker registration) and matches the subscription's target type exactly.","If loading old state, make sure every agent type named in the checkpoint is still registered in the current build.","Check for type-name mismatches (case, namespace-qualified vs short name) between the subscription MapToAgent result and the registered type."],"exampleFix":"// before\nvar subscription = new TypeSubscription(\"ChatAgent\");\nawait runtime.AddSubscriptionAsync(subscription);\nawait runtime.PublishMessageAsync(msg, new TopicId(\"chat\")); // throws: no factory for \"ChatAgent\"\n\n// after\nvar subscription = new TypeSubscription(\"ChatAgent\");\nawait runtime.AddSubscriptionAsync(subscription);\nawait runtime.RegisterAgentFactoryAsync(\n    new AgentType(\"ChatAgent\"),\n    (agentId, rt) => ValueTask.FromResult<IHostableAgent>(new ChatAgent(agentId, rt)));\nawait runtime.PublishMessageAsync(msg, new TopicId(\"chat\"));","handlingStrategy":"validation","validationCode":"var registeredTypes = new HashSet<string>(StringComparer.Ordinal);\nawait runtime.RegisterAgentFactoryAsync(new AgentType(\"ChatAgent\"), factory);\nregisteredTypes.Add(\"ChatAgent\");\n\nvar target = new AgentId(\"ChatAgent\", \"worker\");\nif (!registeredTypes.Contains(target.Type))\n{\n    throw new InvalidOperationException($\"Agent type '{target.Type}' is not registered; skipping send.\");\n}\nawait runtime.SendMessageAsync(target, message);","typeGuard":"static bool IsRegisteredAgentType(HashSet<string> registered, AgentId id) => registered.Contains(id.Type);","tryCatchPattern":"try { await runtime.SendMessageAsync(target, message); }\ncatch (Exception ex) when (ex.Message.Contains(\"not found\"))\n{\n    logger.LogError(\"Agent type {Type} not registered; register it before sending\", target.Type);\n}","preventionTips":["Register all agent factories in one startup method that also records the type names in a set","Keep subscription target types and registered agent types in one constant/source-of-truth location","When loading saved state, validate every AgentId in the checkpoint against currently registered types first"],"tags":["csharp","runtime","agent-registration","configuration"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}