microsoft/autogen · error · Exception

Agent with name {agentId.Type} not found.

Error message

Agent with name {agentId.Type} not found.

What it means

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.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs:29

namespace Microsoft.AutoGen.Core.Grpc;

internal sealed class AgentsContainer(IAgentRuntime hostingRuntime, IProtoSerializationRegistry serializationRegistry)
{
    private readonly IAgentRuntime hostingRuntime = hostingRuntime;
    private readonly IProtoSerializationRegistry serializationRegistry = serializationRegistry;

    private Dictionary<Contracts.AgentId, IHostableAgent> agentInstances = new();
    public Dictionary<string, ISubscriptionDefinition> Subscriptions = new();
    private Dictionary<AgentType, Func<Contracts.AgentId, IAgentRuntime, ValueTask<IHostableAgent>>> agentFactories = new();

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

            agent = await factoryFunc(agentId, this.hostingRuntime);

            // Just-in-Time register the message types so we can deserialize them
            agent.RegisterHandledMessageTypes(this.serializationRegistry);

            this.agentInstances.Add(agentId, agent);
        }

        return this.agentInstances[agentId];
    }

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

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register the missing agent type: host.RegisterAgentFactory(type, factory) (or the equivalent builder extension) before routing traffic to it.
2. Verify the sender is targeting the correct host/process — the type may be registered on a different worker.
3. Check RegisteredAgentTypes at startup and log/compare it against the types peers will send.
4. Align package/agent versions across processes so type names match.

Example fix

// before
// worker never registered the type; sender targets it
await host.EnsureAgentAsync(new AgentId("planner", "default")); // throws

// after
host.RegisterAgentFactory(new AgentType("planner"), (id, runtime) => new ValueTask<IHostableAgent>(new PlannerAgent(id, runtime)));
await host.EnsureAgentAsync(new AgentId("planner", "default"));

if (!host.RegisteredAgentTypes.Contains(agentId.Type))
{
    // register or reject before routing
    throw new InvalidOperationException($"Agent type {agentId.Type} not registered; known: {string.Join(", ", host.RegisteredAgentTypes)}");
}

static bool IsRegistered(GrpcAgentTypesHost host, string type) =>
    host.RegisteredAgentTypes.Contains(new AgentType(type));

try { var agent = await host.EnsureAgentAsync(agentId); }
catch (Exception ex) when (ex.Message.Contains("not found"))
{ /* register-on-demand or route to a different host */ }

When it happens

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

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

Related errors

• Agent factory with type {type} already exists.
• Agent with name {agentId.Type} not found.
• INVALID_ARGUMENT
• Agent type '{recipient.type}' does not exist.
• Agent with name {agent_id.type} not found.

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