@copilotkit/runtime 1.9.2-next.2 → 1.9.2-next.20

package/src/lib/runtime/agui-action.ts

@@ -22,12 +22,16 @@ export function constructAGUIRemoteAction({
   agentStates,
   agent,
   metaEvents,
+  threadMetadata,
+  nodeName,
 }: {
   logger: Logger;
   messages: Message[];
   agentStates?: AgentStateInput[];
   agent: AbstractAgent;
   metaEvents?: MetaEventInput[];
+  threadMetadata?: Record<string, any>;
+  nodeName?: string;
 }) {
   const action = {
     name: agent.agentId,
@@ -67,9 +71,11 @@ export function constructAGUIRemoteAction({
         };
       });
 
-      const forwardedProps = metaEvents.length
-        ? { command: { resume: metaEvents[0]?.response } }
-        : undefined;
+      const forwardedProps = {
+        ...(metaEvents?.length ? { command: { resume: metaEvents[0]?.response } } : {}),
+        ...(threadMetadata ? { threadMetadata } : {}),
+        ...(nodeName ? { nodeName } : {}),
+      };
 
       return agent.legacy_to_be_removed_runAgentBridged({
         tools,

package/src/lib/runtime/copilot-runtime.ts

@@ -20,11 +20,14 @@ import {
   CopilotKitApiDiscoveryError,
   randomId,
   CopilotKitError,
-  CopilotKitRemoteEndpointDiscoveryError,
   CopilotKitAgentDiscoveryError,
   CopilotKitMisuseError,
   CopilotKitErrorCode,
   CopilotKitLowLevelError,
+  CopilotErrorHandler,
+  CopilotErrorEvent,
+  CopilotRequestContext,
+  ensureStructuredError,
 } from "@copilotkit/shared";
 import {
   CopilotServiceAdapter,
@@ -81,10 +84,13 @@ import {
   convertMCPToolsToActions,
   generateMcpToolInstructions,
 } from "./mcp-tools-utils";
+import { LangGraphAgent } from "./langgraph/langgraph-agent";
 // Define the function type alias here or import if defined elsewhere
 type CreateMCPClientFunction = (config: MCPEndpointConfig) => Promise<MCPClient>;
 // --- MCP Imports ---
 
+import { generateHelpfulErrorMessage } from "../streaming";
+
 export interface CopilotRuntimeRequest {
   serviceAdapter: CopilotServiceAdapter;
   messages: MessageInput[];
@@ -274,6 +280,25 @@ export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []
    * ```
    */
   createMCPClient?: CreateMCPClientFunction;
+
+  /**
+   * Optional error handler for comprehensive debugging and observability.
+   *
+   * **Requires publicApiKey**: Error handling only works when requests include a valid publicApiKey.
+   * This is a premium CopilotKit Cloud feature.
+   *
+   * @param errorEvent - Structured error event with rich debugging context
+   *
+   * @example
+   * ```typescript
+   * const runtime = new CopilotRuntime({
+   *   onError: (errorEvent) => {
+   *     debugDashboard.capture(errorEvent);
+   *   }
+   * });
+   * ```
+   */
+  onError?: CopilotErrorHandler;
 }
 
 export class CopilotRuntime<const T extends Parameter[] | [] = []> {
@@ -286,6 +311,8 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
   private delegateAgentProcessingToServiceAdapter: boolean;
   private observability?: CopilotObservabilityConfig;
   private availableAgents: Pick<AgentWithEndpoint, "name" | "id">[];
+  private onError?: CopilotErrorHandler;
+  private hasWarnedAboutError = false;
 
   // +++ MCP Properties +++
   private readonly mcpServersConfig?: MCPEndpointConfig[];
@@ -303,7 +330,21 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.remoteEndpoints.some((e) => e.type === EndpointType.LangGraphPlatform)
     ) {
       console.warn("Actions set in runtime instance will not be available for the agent");
+      console.warn(
+        `LangGraph Platform remote endpoints are deprecated in favor of the "agents" property`,
+      );
     }
+
+    // TODO: finalize
+    // if (
+    //   params?.agents &&
+    //   Object.values(params.agents).some((agent) => {
+    //     return agent instanceof AguiLangGraphAgent && !(agent instanceof LangGraphAgent);
+    //   })
+    // ) {
+    //   console.warn('LangGraph Agent class should be imported from @copilotkit/runtime. ')
+    // }
+
     this.actions = params?.actions || [];
     this.availableAgents = [];
 
@@ -320,6 +361,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.delegateAgentProcessingToServiceAdapter || false;
     this.observability = params?.observability_c;
     this.agents = params?.agents ?? {};
+    this.onError = params?.onError;
     // +++ MCP Initialization +++
     this.mcpServersConfig = params?.mcpServers;
     this.createMCPClientImpl = params?.createMCPClient;
@@ -452,6 +494,32 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
     // For storing streamed chunks if progressive logging is enabled
     const streamedChunks: any[] = [];
 
+    // Track request start
+    await this.error(
+      "request",
+      {
+        threadId,
+        runId,
+        source: "runtime",
+        request: {
+          operation: "processRuntimeRequest",
+          method: "POST",
+          url: url,
+          startTime: requestStartTime,
+        },
+        agent: agentSession ? { name: agentSession.agentName } : undefined,
+        messages: {
+          input: rawMessages,
+          messageCount: rawMessages.length,
+        },
+        technical: {
+          environment: process.env.NODE_ENV,
+        },
+      },
+      undefined,
+      publicApiKey,
+    );
+
     try {
       if (
         Object.keys(this.agents).length &&
@@ -675,17 +743,60 @@ please use an LLM adapter instead.`,
         }
       }
 
+      let structuredError: CopilotKitError;
+
       if (error instanceof CopilotKitError) {
-        throw error;
+        structuredError = error;
+      } else {
+        // Convert non-CopilotKitErrors to structured errors, but preserve already structured ones
+        structuredError = ensureStructuredError(error, (err) =>
+          this.convertStreamingErrorToStructured(err),
+        );
       }
 
-      // Convert non-CopilotKitErrors to structured errors
-      console.error("Error getting response:", error);
-      const structuredError = this.convertStreamingErrorToStructured(error);
+      // Track the error
+      await this.error(
+        "error",
+        {
+          threadId,
+          runId,
+          source: "runtime",
+          request: {
+            operation: "processRuntimeRequest",
+            method: "POST",
+            url: url,
+            startTime: requestStartTime,
+          },
+          response: {
+            endTime: Date.now(),
+            latency: Date.now() - requestStartTime,
+          },
+          agent: agentSession ? { name: agentSession.agentName } : undefined,
+          technical: {
+            environment: process.env.NODE_ENV,
+            stackTrace: error instanceof Error ? error.stack : undefined,
+          },
+        },
+        structuredError,
+        publicApiKey,
+      );
+
       throw structuredError;
     }
   }
 
+  async getAllAgents(graphqlContext: GraphQLContext): Promise<(AgentWithEndpoint | Agent)[]> {
+    const agentsWithEndpoints = await this.discoverAgentsFromEndpoints(graphqlContext);
+    const aguiAgents = this.discoverAgentsFromAgui();
+
+    this.availableAgents = [...agentsWithEndpoints, ...aguiAgents].map((a) => ({
+      name: a.name,
+      id: a.id,
+    }));
+
+    return [...agentsWithEndpoints, ...aguiAgents];
+  }
+
   async discoverAgentsFromEndpoints(graphqlContext: GraphQLContext): Promise<AgentWithEndpoint[]> {
     const agents: Promise<AgentWithEndpoint[]> = this.remoteEndpointDefinitions.reduce(
       async (acc: Promise<Agent[]>, endpoint) => {
@@ -767,60 +878,35 @@ please use an LLM adapter instead.`,
       },
       Promise.resolve([]),
     );
-    this.availableAgents = ((await agents) ?? []).map((a) => ({ name: a.name, id: a.id }));
 
     return agents;
   }
 
+  discoverAgentsFromAgui(): Agent[] {
+    return Object.entries(this.agents ?? []).map(([key, agent]: [string, AbstractAgent]) => ({
+      name: (agent as any).agentName ?? key,
+      id: agent.agentId ?? key,
+      description: agent.description ?? "",
+    }));
+  }
+
   async loadAgentState(
     graphqlContext: GraphQLContext,
     threadId: string,
     agentName: string,
   ): Promise<LoadAgentStateResponse> {
-    const agentsWithEndpoints = await this.discoverAgentsFromEndpoints(graphqlContext);
+    const agents = await this.getAllAgents(graphqlContext);
 
-    const agentWithEndpoint = agentsWithEndpoints.find((agent) => agent.name === agentName);
-    if (!agentWithEndpoint) {
+    const agent = agents.find((agent) => agent.name === agentName);
+    if (!agent) {
       throw new Error("Agent not found");
     }
 
-    if (agentWithEndpoint.endpoint.type === EndpointType.LangGraphPlatform) {
-      const propertyHeaders = graphqlContext.properties.authorization
-        ? { authorization: `Bearer ${graphqlContext.properties.authorization}` }
-        : null;
-
-      const client = new LangGraphClient({
-        apiUrl: agentWithEndpoint.endpoint.deploymentUrl,
-        apiKey: agentWithEndpoint.endpoint.langsmithApiKey,
-        defaultHeaders: { ...propertyHeaders },
-      });
-      let state: any = {};
-      try {
-        state = (await client.threads.getState(threadId)).values as any;
-      } catch (error) {}
-
-      if (Object.keys(state).length === 0) {
-        return {
-          threadId: threadId || "",
-          threadExists: false,
-          state: JSON.stringify({}),
-          messages: JSON.stringify([]),
-        };
-      } else {
-        const { messages, ...stateWithoutMessages } = state;
-        const copilotkitMessages = langchainMessagesToCopilotKit(messages);
-        return {
-          threadId: threadId || "",
-          threadExists: true,
-          state: JSON.stringify(stateWithoutMessages),
-          messages: JSON.stringify(copilotkitMessages),
-        };
-      }
-    } else if (
-      agentWithEndpoint.endpoint.type === EndpointType.CopilotKit ||
-      !("type" in agentWithEndpoint.endpoint)
+    if (
+      "endpoint" in agent &&
+      (agent.endpoint.type === EndpointType.CopilotKit || !("type" in agent.endpoint))
     ) {
-      const cpkEndpoint = agentWithEndpoint.endpoint as CopilotKitEndpoint;
+      const cpkEndpoint = agent.endpoint as CopilotKitEndpoint;
       const fetchUrl = `${cpkEndpoint.url}/agents/state`;
       try {
         const response = await fetchWithRetry(fetchUrl, {
@@ -836,10 +922,24 @@ please use an LLM adapter instead.`,
           if (response.status === 404) {
             throw new CopilotKitApiDiscoveryError({ url: fetchUrl });
           }
+
+          // Extract semantic error information from response body
+          let errorMessage = `HTTP ${response.status} error`;
+          try {
+            const errorBody = await response.text();
+            const parsedError = JSON.parse(errorBody);
+            if (parsedError.error && typeof parsedError.error === "string") {
+              errorMessage = parsedError.error;
+            }
+          } catch {
+            // If parsing fails, fall back to generic message
+          }
+
           throw new ResolvedCopilotKitError({
             status: response.status,
             url: fetchUrl,
             isRemoteEndpoint: true,
+            message: errorMessage,
           });
         }
 
@@ -856,9 +956,65 @@ please use an LLM adapter instead.`,
         }
         throw new CopilotKitLowLevelError({ error, url: fetchUrl });
       }
+    }
+
+    const propertyHeaders = graphqlContext.properties.authorization
+      ? { authorization: `Bearer ${graphqlContext.properties.authorization}` }
+      : null;
+
+    let state: any = {};
+    try {
+      let client: LangGraphClient | null;
+      if ("endpoint" in agent && agent.endpoint.type === EndpointType.LangGraphPlatform) {
+        client = new LangGraphClient({
+          apiUrl: agent.endpoint.deploymentUrl,
+          apiKey: agent.endpoint.langsmithApiKey,
+          defaultHeaders: { ...propertyHeaders },
+        });
+      } else {
+        const aguiAgent = graphqlContext._copilotkit.runtime.agents[agent.name] as LangGraphAgent;
+        if (!aguiAgent) {
+          throw new Error(`Agent: ${agent.name} could not be resolved`);
+        }
+        // @ts-expect-error -- both clients are the same
+        client = aguiAgent.client ?? null;
+      }
+
+      state = client ? ((await client.threads.getState(threadId)).values as any) : {};
+    } catch (error) {
+      // All errors from agent state loading are user configuration issues
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // Log user configuration errors at debug level to reduce noise
+      console.debug(`Agent '${agentName}' configuration issue: ${errorMessage}`);
+
+      // Throw a configuration error - all agent state loading failures are user setup issues
+      throw new ResolvedCopilotKitError({
+        status: 400,
+        message: `Agent '${agentName}' failed to execute: ${errorMessage}`,
+        code: CopilotKitErrorCode.CONFIGURATION_ERROR,
+      });
+    }
+
+    if (Object.keys(state).length === 0) {
+      return {
+        threadId: threadId || "",
+        threadExists: false,
+        state: JSON.stringify({}),
+        messages: JSON.stringify([]),
+      };
     } else {
-      throw new Error(`Unknown endpoint type: ${(agentWithEndpoint.endpoint as any).type}`);
+      const { messages, ...stateWithoutMessages } = state;
+      const copilotkitMessages = langchainMessagesToCopilotKit(messages);
+      return {
+        threadId: threadId || "",
+        threadExists: true,
+        state: JSON.stringify(stateWithoutMessages),
+        messages: JSON.stringify(copilotkitMessages),
+      };
     }
+
+    throw new Error(`Agent: ${agent.name} could not be resolved`);
   }
 
   private async processAgentRequest(
@@ -884,6 +1040,33 @@ please use an LLM adapter instead.`,
     // for backwards compatibility, deal with the case when no threadId is provided
     const threadId = threadIdFromRequest ?? agentSession.threadId;
 
+    // Track agent request start
+    await this.error(
+      "agent_state",
+      {
+        threadId,
+        source: "agent",
+        request: {
+          operation: "processAgentRequest",
+          method: "POST",
+          startTime: requestStartTime,
+        },
+        agent: {
+          name: agentName,
+          nodeName: nodeName,
+        },
+        messages: {
+          input: rawMessages,
+          messageCount: rawMessages.length,
+        },
+        technical: {
+          environment: process.env.NODE_ENV,
+        },
+      },
+      undefined,
+      publicApiKey,
+    );
+
     const serverSideActions = await this.getServerSideActions(request);
 
     const messages = convertGqlInputToMessages(rawMessages);
@@ -1011,9 +1194,7 @@ please use an LLM adapter instead.`,
       eventSource.stream(async (eventStream$) => {
         from(stream).subscribe({
           next: (event) => eventStream$.next(event),
-          error: (err) => {
-            console.error("Error in stream", err);
-
+          error: async (err) => {
             // Log error with observability if enabled
             if (this.observability?.enabled && publicApiKey) {
               try {
@@ -1035,8 +1216,39 @@ please use an LLM adapter instead.`,
               }
             }
 
-            // Convert network termination errors to structured errors
-            const structuredError = this.convertStreamingErrorToStructured(err);
+            // Preserve structured CopilotKit errors, only convert unstructured errors
+            const structuredError = ensureStructuredError(err, (error) =>
+              this.convertStreamingErrorToStructured(error),
+            );
+
+            // Track streaming errors
+            await this.error(
+              "error",
+              {
+                threadId,
+                source: "agent",
+                request: {
+                  operation: "processAgentRequest",
+                  method: "POST",
+                  startTime: requestStartTime,
+                },
+                response: {
+                  endTime: Date.now(),
+                  latency: Date.now() - requestStartTime,
+                },
+                agent: {
+                  name: agentName,
+                  nodeName: nodeName,
+                },
+                technical: {
+                  environment: process.env.NODE_ENV,
+                  stackTrace: err instanceof Error ? err.stack : undefined,
+                },
+              },
+              structuredError,
+              publicApiKey,
+            );
+
             eventStream$.error(structuredError);
             eventStream$.complete();
           },
@@ -1114,8 +1326,41 @@ please use an LLM adapter instead.`,
         }
       }
 
+      // Ensure error is structured
+      const structuredError = ensureStructuredError(error, (err) =>
+        this.convertStreamingErrorToStructured(err),
+      );
+
+      // Track the agent error
+      await this.error(
+        "error",
+        {
+          threadId,
+          source: "agent",
+          request: {
+            operation: "processAgentRequest",
+            method: "POST",
+            startTime: requestStartTime,
+          },
+          response: {
+            endTime: Date.now(),
+            latency: Date.now() - requestStartTime,
+          },
+          agent: {
+            name: agentName,
+            nodeName: nodeName,
+          },
+          technical: {
+            environment: process.env.NODE_ENV,
+            stackTrace: error instanceof Error ? error.stack : undefined,
+          },
+        },
+        structuredError,
+        publicApiKey,
+      );
+
       console.error("Error getting response:", error);
-      throw error;
+      throw structuredError;
     }
   }
 
@@ -1146,6 +1391,7 @@ please use an LLM adapter instead.`,
       frontendUrl: url,
       agents: this.agents,
       metaEvents: request.metaEvents,
+      nodeName: request.agentSession?.nodeName,
     });
 
     const configuredActions =
@@ -1231,53 +1477,108 @@ please use an LLM adapter instead.`,
   }
 
   private convertStreamingErrorToStructured(error: any): CopilotKitError {
-    // Handle network termination errors
-    if (
-      error?.message?.includes("terminated") ||
-      error?.cause?.code === "UND_ERR_SOCKET" ||
-      error?.message?.includes("other side closed") ||
-      error?.code === "UND_ERR_SOCKET"
-    ) {
-      return new CopilotKitError({
-        message:
-          "Connection to agent was unexpectedly terminated. This may be due to the agent service being restarted or network issues. Please try again.",
-        code: CopilotKitErrorCode.NETWORK_ERROR,
-      });
-    }
+    // Determine a more helpful error message based on context
+    let helpfulMessage = generateHelpfulErrorMessage(error, "agent streaming connection");
 
-    // Handle other network-related errors
+    // For network-related errors, use CopilotKitLowLevelError to preserve the original error
     if (
       error?.message?.includes("fetch failed") ||
       error?.message?.includes("ECONNREFUSED") ||
       error?.message?.includes("ENOTFOUND") ||
-      error?.message?.includes("ETIMEDOUT")
+      error?.message?.includes("ETIMEDOUT") ||
+      error?.message?.includes("terminated") ||
+      error?.cause?.code === "UND_ERR_SOCKET" ||
+      error?.message?.includes("other side closed") ||
+      error?.code === "UND_ERR_SOCKET"
     ) {
       return new CopilotKitLowLevelError({
         error: error instanceof Error ? error : new Error(String(error)),
         url: "agent streaming connection",
-        message:
-          "Network error occurred during agent streaming. Please check your connection and try again.",
+        message: helpfulMessage,
       });
     }
 
-    // Handle abort/cancellation errors (these are usually normal)
-    if (
-      error?.message?.includes("aborted") ||
-      error?.message?.includes("canceled") ||
-      error?.message?.includes("signal is aborted")
-    ) {
-      return new CopilotKitError({
-        message: "Agent request was cancelled",
-        code: CopilotKitErrorCode.UNKNOWN,
-      });
-    }
-
-    // Default: convert unknown streaming errors
+    // For all other errors, preserve the raw error in a basic CopilotKitError
     return new CopilotKitError({
-      message: `Agent streaming error: ${error?.message || String(error)}`,
+      message: helpfulMessage,
       code: CopilotKitErrorCode.UNKNOWN,
     });
   }
+
+  private async error(
+    type: CopilotErrorEvent["type"],
+    context: CopilotRequestContext,
+    error?: any,
+    publicApiKey?: string,
+  ): Promise<void> {
+    if (!this.onError) return;
+
+    // Just check if publicApiKey is defined (regardless of validity)
+    if (!publicApiKey) {
+      if (!this.hasWarnedAboutError) {
+        console.warn(
+          "CopilotKit: onError handler provided but requires publicApiKey to be defined for error handling to work.",
+        );
+        this.hasWarnedAboutError = true;
+      }
+      return;
+    }
+
+    try {
+      const errorEvent: CopilotErrorEvent = {
+        type,
+        timestamp: Date.now(),
+        context,
+        ...(error && { error }),
+      };
+
+      await this.onError(errorEvent);
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
+    }
+  }
+
+  /**
+   * Public method to handle GraphQL validation errors
+   * This allows the GraphQL resolver to send validation errors through the error system
+   */
+  public async errorGraphQLError(
+    error: { message: string; code: string; type: string },
+    context: {
+      operation: string;
+      cloudConfigPresent: boolean;
+      guardrailsEnabled: boolean;
+    },
+  ): Promise<void> {
+    if (!this.onError) return;
+
+    try {
+      await this.onError({
+        type: "error",
+        timestamp: Date.now(),
+        context: {
+          source: "runtime",
+          request: {
+            operation: context.operation,
+            startTime: Date.now(),
+          },
+          technical: {
+            environment: process.env.NODE_ENV,
+          },
+          metadata: {
+            errorType: "GraphQLValidationError",
+            cloudConfigPresent: context.cloudConfigPresent,
+            guardrailsEnabled: context.guardrailsEnabled,
+          },
+        },
+        error,
+      });
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
+    }
+  }
 }
 
 export function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[] {

package/src/lib/runtime/langgraph/langgraph-agent.ts

@@ -16,6 +16,7 @@ import {
   LangGraphAgent as AGUILangGraphAgent,
   type LangGraphAgentConfig,
   ProcessedEvents,
+  SchemaKeys,
 } from "@ag-ui/langgraph";
 import { Message as LangGraphMessage } from "@langchain/langgraph-sdk/dist/types.messages";
 
@@ -180,6 +181,7 @@ export class LangGraphAgent extends AGUILangGraphAgent {
       messages,
       tools,
     );
+
     return {
       ...rest,
       copilotkit: {
@@ -187,4 +189,14 @@ export class LangGraphAgent extends AGUILangGraphAgent {
       },
     };
   }
+
+  async getSchemaKeys(): Promise<SchemaKeys> {
+    const CONSTANT_KEYS = ["copilotkit"];
+    const schemaKeys = await super.getSchemaKeys();
+    return {
+      config: schemaKeys.config,
+      input: schemaKeys.input ? [...schemaKeys.input, ...CONSTANT_KEYS] : null,
+      output: schemaKeys.output ? [...schemaKeys.output, ...CONSTANT_KEYS] : null,
+    };
+  }
 }