microsoft/autogen · error · Exception

Agent with name {agentId.Type} not found.

Error message

Agent with name {agentId.Type} not found.

What it means

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.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs:142

        return this.ExecuteTracedAsync(async () =>
        {
            MessageDelivery delivery = new MessageEnvelope(message, messageId, cancellationToken)
                                            .WithSender(sender)
                                            .ForSend(recepient, this.SendMessageServicer);

            this.messageDeliveryQueue.Enqueue(delivery);

            return await delivery.Future;
        });
    }

    private async ValueTask<IHostableAgent> EnsureAgentAsync(AgentId agentId)
    {
        if (!this.agentInstances.TryGetValue(agentId, out IHostableAgent? agent))
        {
            if (!this.agentFactories.TryGetValue(agentId.Type, out Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>>? factoryFunc))
            {
                throw new Exception($"Agent with name {agentId.Type} not found.");
            }

            agent = await factoryFunc(agentId, this);
            this.agentInstances.Add(agentId, agent);
        }

        return this.agentInstances[agentId];
    }

    public async ValueTask<AgentId> GetAgentAsync(AgentId agentId, bool lazy = true)
    {
        if (!lazy)
        {
            await this.EnsureAgentAsync(agentId);
        }

        return agentId;
    }

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register a factory for the type before it receives messages: await runtime.RegisterAgentFactoryAsync("ChatAgent", (id, rt) => ...).
2. 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.
3. If loading old state, make sure every agent type named in the checkpoint is still registered in the current build.
4. Check for type-name mismatches (case, namespace-qualified vs short name) between the subscription MapToAgent result and the registered type.

Example fix

// before
var subscription = new TypeSubscription("ChatAgent");
await runtime.AddSubscriptionAsync(subscription);
await runtime.PublishMessageAsync(msg, new TopicId("chat")); // throws: no factory for "ChatAgent"

// after
var subscription = new TypeSubscription("ChatAgent");
await runtime.AddSubscriptionAsync(subscription);
await runtime.RegisterAgentFactoryAsync(
    new AgentType("ChatAgent"),
    (agentId, rt) => ValueTask.FromResult<IHostableAgent>(new ChatAgent(agentId, rt)));
await runtime.PublishMessageAsync(msg, new TopicId("chat"));

var registeredTypes = new HashSet<string>(StringComparer.Ordinal);
await runtime.RegisterAgentFactoryAsync(new AgentType("ChatAgent"), factory);
registeredTypes.Add("ChatAgent");

var target = new AgentId("ChatAgent", "worker");
if (!registeredTypes.Contains(target.Type))
{
    throw new InvalidOperationException($"Agent type '{target.Type}' is not registered; skipping send.");
}
await runtime.SendMessageAsync(target, message);

static bool IsRegisteredAgentType(HashSet<string> registered, AgentId id) => registered.Contains(id.Type);

try { await runtime.SendMessageAsync(target, message); }
catch (Exception ex) when (ex.Message.Contains("not found"))
{
    logger.LogError("Agent type {Type} not registered; register it before sending", target.Type);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• The content has more than one choice. Please try another inp
• Only one choice is supported in streaming response
• Agent with name {agentId.Type} not found.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/c117bbfb61353893. Report an issue: GitHub.