{"record":{"id":"6ee487a75fd19de3","repo":"microsoft/autogen","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":"Exception","httpStatus":null,"severity":"error","filePath":"dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs","lineNumber":29,"sourceCode":"\nnamespace Microsoft.AutoGen.Core.Grpc;\n\ninternal sealed class AgentsContainer(IAgentRuntime hostingRuntime, IProtoSerializationRegistry serializationRegistry)\n{\n    private readonly IAgentRuntime hostingRuntime = hostingRuntime;\n    private readonly IProtoSerializationRegistry serializationRegistry = serializationRegistry;\n\n    private Dictionary<Contracts.AgentId, IHostableAgent> agentInstances = new();\n    public Dictionary<string, ISubscriptionDefinition> Subscriptions = new();\n    private Dictionary<AgentType, Func<Contracts.AgentId, IAgentRuntime, ValueTask<IHostableAgent>>> agentFactories = new();\n\n    public async ValueTask<IHostableAgent> EnsureAgentAsync(Contracts.AgentId agentId)\n    {\n        if (!this.agentInstances.TryGetValue(agentId, out IHostableAgent? agent))\n        {\n            if (!this.agentFactories.TryGetValue(agentId.Type, out Func<Contracts.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.hostingRuntime);\n\n            // Just-in-Time register the message types so we can deserialize them\n            agent.RegisterHandledMessageTypes(this.serializationRegistry);\n\n            this.agentInstances.Add(agentId, agent);\n        }\n\n        return this.agentInstances[agentId];\n    }\n\n    public async ValueTask<Contracts.AgentId> GetAgentAsync(Contracts.AgentId agentId, bool lazy = true)\n    {\n        if (!lazy)\n        {\n            await this.EnsureAgentAsync(agentId);","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs#L11-L47","documentation":"GrpcAgentTypesHost.EnsureAgentAsync throws a plain Exception when asked to materialize an agent whose type has no registered factory. The host only knows how to create agents whose factories were registered via RegisterAgentFactory; a lookup for any other type fails before instantiation.","triggerScenarios":"The gRPC runtime receives an RpcRequest whose Target type was never registered on this host (sender and receiver disagree on agent types); calling EnsureAgentAsync directly for an unregistered AgentType; lazy registration where TrySetAgentInstance/StartupAsync used lazy=true and no factory was ever added for that type.","commonSituations":"Deploying worker processes with different agent sets than the sender expects; forgetting to register an agent type in the host builder before traffic arrives; typos/case differences in agent type names between services; version skew where a new agent type exists upstream but not on the worker running this code.","solutions":["Register the missing agent type: host.RegisterAgentFactory(type, factory) (or the equivalent builder extension) before routing traffic to it.","Verify the sender is targeting the correct host/process — the type may be registered on a different worker.","Check RegisteredAgentTypes at startup and log/compare it against the types peers will send.","Align package/agent versions across processes so type names match."],"exampleFix":"// before\n// worker never registered the type; sender targets it\nawait host.EnsureAgentAsync(new AgentId(\"planner\", \"default\")); // throws\n\n// after\nhost.RegisterAgentFactory(new AgentType(\"planner\"), (id, runtime) => new ValueTask<IHostableAgent>(new PlannerAgent(id, runtime)));\nawait host.EnsureAgentAsync(new AgentId(\"planner\", \"default\"));","handlingStrategy":"validation","validationCode":"if (!host.RegisteredAgentTypes.Contains(agentId.Type))\n{\n    // register or reject before routing\n    throw new InvalidOperationException($\"Agent type {agentId.Type} not registered; known: {string.Join(\", \", host.RegisteredAgentTypes)}\");\n}","typeGuard":"static bool IsRegistered(GrpcAgentTypesHost host, string type) =>\n    host.RegisteredAgentTypes.Contains(new AgentType(type));","tryCatchPattern":"try { var agent = await host.EnsureAgentAsync(agentId); }\ncatch (Exception ex) when (ex.Message.Contains(\"not found\"))\n{ /* register-on-demand or route to a different host */ }","preventionTips":["Log RegisteredAgentTypes at startup and diff it against the set peers will target.","Register all agent factories during host startup, before opening the gRPC channel to traffic."],"tags":["grpc","agent-registration","runtime","distributed"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}