CopilotKit/CopilotKit · error · Error

Cannot extract agent name from message with role ${message.r

Error message

Cannot extract agent name from message with role ${message.role}

What it means

Internal helper that extracts the agent name from an AG-UI message. It only works on messages whose role is 'assistant'; any other role (user, tool, system, developer) is rejected because agent attribution only exists on assistant messages. Thrown during GraphQL message conversion when the code path expects an assistant message but receives something else.

Source

Thrown at packages/runtime/src/v1-deprecated/graphql/message-conversion/agui-to-gql.ts:8

import * as gql from "../types/converted/index";
import { MessageRole } from "../types/enums";
import * as agui from "@copilotkit/shared"; // named agui for clarity, but this only includes agui message types

// Helper function to extract agent name from message
function extractAgentName(message: agui.Message): string {
  if (message.role !== "assistant") {
    throw new Error(
      `Cannot extract agent name from message with role ${message.role}`,
    );
  }

  return message.agentName || "unknown";
}

// Type guard for agent state message
function isAgentStateMessage(message: agui.Message): boolean {
  return (
    message.role === "assistant" && "agentName" in message && "state" in message
  );
}

// Type guard for messages with image property
function hasImageProperty(
  message: agui.Message,
): message is agui.Message & { image: agui.ImageData } {

View on GitHub (pinned to 68fbe97d87)

Solutions

1. Verify the message role before passing it to code that expects assistant messages
2. Filter messages by role === 'assistant' before conversion
3. Set agentName explicitly on assistant messages when constructing them

Example fix

// before
const name = extractAgentName(msg); // msg.role === 'user' -> throws
// after
if (msg.role === "assistant") {
  const name = msg.agentName || "unknown";
}

const isAssistant = (m) => m.role === "assistant";

function isAssistantMessage(m: agui.Message): m is Extract<agui.Message, { role: "assistant" }> {
  return m.role === "assistant";
}

When it happens

Trigger: Calling agentName extraction (internally via aguiToGQL flows) on a message where message.role !== 'assistant', e.g. a user or tool message passed into a path that assumes assistant output.

Common situations: Custom message pipelines or misordered messages where a user/tool message is fed into assistant-only conversion logic; usually a bug in calling code rather than user config.

Related errors

• Unknown message type
• Cannot convert message with role ${message.role} to ResultMe
• Unknown message type
• Unknown message role
• Unknown message role: "${(message as any).role}" in message

AI-assisted analysis of CopilotKit/CopilotKit@68fbe97d87 (2026-08-27). Data as JSON: /api/errors/f676df208e7915d6. Report an issue: GitHub.