microsoft/semantic-kernel · error · InvalidOperationException

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

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.

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)

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 {type} already exists.
• Entry agent is not defined.
• Unable to transform output to {typeof(TOutput)}.
• Runtime is already running.
• Runtime is already stopping.

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