microsoft/semantic-kernel · error · InvalidOperationException

Agent with name is not of type .

Error message

Agent with name {agentId.Type} is not of type {typeof(TAgent).Name}.

What it means

TryGetUnderlyingAgentInstanceAsync<TAgent> resolves the agent via EnsureAgentAsync then attempts a runtime cast to TAgent; if the concrete agent is not assignable to TAgent it throws InvalidOperationException naming the registered type and the requested type. EnsureAgentAsync itself throws a different message ("Agent with name ... not found") when no factory exists, so this throw specifically means the agent exists but is the wrong type.

Solutions

1. Request the exact concrete type the factory produces; for orchestration-registered agents request the hostable actor type, not the original Agent.
2. Use TryGetUnderlyingAgentInstanceAsync<IHostableAgent> if you only need the hosted interface.
3. Check agent.Metadata first to determine the underlying type before the typed call.

Example fix

// before
var agent = await runtime.TryGetUnderlyingAgentInstanceAsync<MyAgent>(agentId); // actor is not MyAgent

// after
var hosted = await runtime.TryGetUnderlyingAgentInstanceAsync<IHostableAgent>(agentId);

AgentMetadata meta = await runtime.GetAgentMetadataAsync(agentId);
// Then request a type compatible with meta's underlying agent type.

// Request the most general hosted type first, then narrow.
IHostableAgent hosted = await runtime.TryGetUnderlyingAgentInstanceAsync<IHostableAgent>(agentId);
if (hosted is TAgent typed) { /* use typed */ }

try { return await runtime.TryGetUnderlyingAgentInstanceAsync<TAgent>(agentId); }
catch (InvalidOperationException) { /* wrong concrete type; fall back to IHostableAgent or fail */ }

When it happens

Trigger: Requesting TryGetUnderlyingAgentInstanceAsync<MyAgent>(id) when id was registered by a factory producing a different concrete type (e.g. a wrapper/wrapper-actor like a SequentialActor vs the original Agent); passing the wrong generic type argument.

Common situations: Confusing the orchestration 'actor' (IHostableAgent) registered by the runtime with the user-supplied Agent; generic type inferred incorrectly; inspecting an agent registered through an orchestration that wraps the original.

Related errors

• Agent with type already exists.
• Agent with name not found.
• Delivery of message was cancelled.
• Entry agent is not defined.
• Message must have a receiver to be sent.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/02ff2e30d55134ab. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Agents/Runtime/InProcess/InProcessRuntime.cs:180

    /// <inheritdoc/>
    public ValueTask<AgentId> GetAgentAsync(string agent, string key = AgentId.DefaultKey, bool lazy = true)
        => this.GetAgentAsync(new AgentId(agent, key), lazy);

    /// <inheritdoc/>
    public async ValueTask<AgentMetadata> GetAgentMetadataAsync(AgentId agentId)
    {
        IHostableAgent agent = await this.EnsureAgentAsync(agentId).ConfigureAwait(false);
        return agent.Metadata;
    }

    /// <inheritdoc/>
    public async ValueTask<TAgent> TryGetUnderlyingAgentInstanceAsync<TAgent>(AgentId agentId) where TAgent : IHostableAgent
    {
        IHostableAgent agent = await this.EnsureAgentAsync(agentId).ConfigureAwait(false);

        if (agent is not TAgent concreteAgent)
        {
            throw new InvalidOperationException($"Agent with name {agentId.Type} is not of type {typeof(TAgent).Name}.");
        }

        return concreteAgent;
    }

    /// <inheritdoc/>
    public async ValueTask LoadAgentStateAsync(AgentId agentId, JsonElement state)
    {
        IHostableAgent agent = await this.EnsureAgentAsync(agentId).ConfigureAwait(false);
        await agent.LoadStateAsync(state).ConfigureAwait(false);
    }

    /// <inheritdoc/>
    public async ValueTask<JsonElement> SaveAgentStateAsync(AgentId agentId)
    {
        IHostableAgent agent = await this.EnsureAgentAsync(agentId).ConfigureAwait(false);
        return await agent.SaveStateAsync().ConfigureAwait(false);
    }

View on GitHub (pinned to c028a0c7dc)