@copilotkit/runtime 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/lib/runtime/__tests__/mcp-tools-utils.test.ts

@@ -0,0 +1,464 @@
+import {
+  extractParametersFromSchema,
+  convertMCPToolsToActions,
+  generateMcpToolInstructions,
+  MCPTool,
+} from "../mcp-tools-utils";
+
+describe("MCP Tools Utils", () => {
+  describe("extractParametersFromSchema", () => {
+    it("should extract parameters from schema.parameters.properties", () => {
+      const tool: MCPTool = {
+        description: "Test tool",
+        schema: {
+          parameters: {
+            properties: {
+              name: { type: "string", description: "A name parameter" },
+              age: { type: "number", description: "An age parameter" },
+            },
+            required: ["name"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "name",
+        type: "string",
+        description: "A name parameter",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "age",
+        type: "number",
+        description: "An age parameter",
+        required: false,
+      });
+    });
+
+    it("should extract parameters from schema.parameters.jsonSchema", () => {
+      const tool: MCPTool = {
+        description: "Test tool with jsonSchema",
+        schema: {
+          parameters: {
+            jsonSchema: {
+              properties: {
+                title: { type: "string", description: "A title parameter" },
+                count: { type: "number", description: "A count parameter" },
+              },
+              required: ["title"],
+            },
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "title",
+        type: "string",
+        description: "A title parameter",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "count",
+        type: "number",
+        description: "A count parameter",
+        required: false,
+      });
+    });
+
+    it("should handle arrays with items", () => {
+      const tool: MCPTool = {
+        description: "Test tool with array parameters",
+        schema: {
+          parameters: {
+            properties: {
+              simpleArray: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of strings",
+              },
+              objectArray: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    value: { type: "number" },
+                  },
+                },
+                description: "Array of objects",
+              },
+            },
+            required: ["simpleArray"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "simpleArray",
+        type: "array<string>",
+        description: "Array of strings",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "objectArray",
+        type: "array",
+        description: "Array of objects Array of objects with properties: name, value",
+        required: false,
+      });
+    });
+
+    it("should handle enums", () => {
+      const tool: MCPTool = {
+        description: "Test tool with enum parameters",
+        schema: {
+          parameters: {
+            properties: {
+              status: {
+                type: "string",
+                enum: ["active", "inactive", "pending"],
+                description: "Status value",
+              },
+              priority: {
+                type: "number",
+                enum: [1, 2, 3],
+                description: "Priority level",
+              },
+            },
+            required: ["status"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "status",
+        type: "string",
+        description: "Status value Allowed values: active | inactive | pending",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "priority",
+        type: "number",
+        description: "Priority level Allowed values: 1 | 2 | 3",
+        required: false,
+      });
+    });
+
+    it("should handle nested objects", () => {
+      const tool: MCPTool = {
+        description: "Test tool with nested object parameters",
+        schema: {
+          parameters: {
+            properties: {
+              user: {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                  email: { type: "string" },
+                  preferences: {
+                    type: "object",
+                    properties: {
+                      theme: { type: "string" },
+                      notifications: { type: "boolean" },
+                    },
+                  },
+                },
+                description: "User object",
+              },
+            },
+            required: ["user"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        name: "user",
+        type: "object",
+        description: "User object Object with properties: name, email, preferences",
+        required: true,
+      });
+    });
+
+    it("should return empty array when no properties", () => {
+      const tool: MCPTool = {
+        description: "Test tool without properties",
+        schema: {
+          parameters: {},
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("generateMcpToolInstructions", () => {
+    it("should generate instructions with correct parameter schema from schema.parameters.properties", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+                age: { type: "number", description: "The age parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("testTool: A test tool");
+      expect(result).toContain("- name* (string) - The name parameter");
+      expect(result).toContain("- age (number) - The age parameter");
+    });
+
+    it("should generate instructions with correct parameter schema from schema.parameters.jsonSchema", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool with jsonSchema",
+          schema: {
+            parameters: {
+              jsonSchema: {
+                properties: {
+                  title: { type: "string", description: "The title parameter" },
+                  count: { type: "number", description: "The count parameter" },
+                },
+                required: ["title"],
+              },
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("testTool: A test tool with jsonSchema");
+      expect(result).toContain("- title* (string) - The title parameter");
+      expect(result).toContain("- count (number) - The count parameter");
+    });
+
+    it("should handle complex schemas with arrays and enums", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        complexTool: {
+          description: "A complex tool",
+          schema: {
+            parameters: {
+              properties: {
+                items: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string" },
+                      value: { type: "number" },
+                    },
+                  },
+                  description: "Array of items",
+                },
+                status: {
+                  type: "string",
+                  enum: ["active", "inactive"],
+                  description: "Status",
+                },
+              },
+              required: ["items"],
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("complexTool: A complex tool");
+      expect(result).toContain(
+        "- items* (array<object>) - Array of items Array of objects with properties: name, value",
+      );
+      expect(result).toContain("- status (string) - Status Allowed values: active | inactive");
+    });
+
+    it("should fallback to schema.properties for backward compatibility", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        backwardCompatTool: {
+          description: "A backward compatible tool",
+          schema: {
+            // Direct properties without nested parameters
+            properties: {
+              name: { type: "string", description: "The name parameter" },
+            },
+            required: ["name"],
+          } as any,
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("backwardCompatTool: A backward compatible tool");
+      expect(result).toContain("- name* (string) - The name parameter");
+    });
+
+    it("should show 'No parameters required' when no schema properties", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        noParamsTool: {
+          description: "A tool with no parameters",
+          schema: {
+            parameters: {},
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("noParamsTool: A tool with no parameters");
+      expect(result).toContain("No parameters required");
+    });
+
+    it("should handle tools with no schema", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        noSchemaTool: {
+          description: "A tool with no schema",
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("noSchemaTool: A tool with no schema");
+      expect(result).toContain("No parameters required");
+    });
+
+    it("should return empty string for empty tools map", () => {
+      const result = generateMcpToolInstructions({});
+      expect(result).toBe("");
+    });
+  });
+
+  describe("convertMCPToolsToActions", () => {
+    it("should convert MCP tools to CopilotKit actions", () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+                age: { type: "number", description: "The age parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => "test result",
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("testTool");
+      expect(result[0].description).toBe("A test tool");
+      expect(result[0].parameters).toHaveLength(2);
+      expect(result[0].parameters[0]).toEqual({
+        name: "name",
+        type: "string",
+        description: "The name parameter",
+        required: true,
+      });
+      expect(result[0].parameters[1]).toEqual({
+        name: "age",
+        type: "number",
+        description: "The age parameter",
+        required: false,
+      });
+    });
+
+    it("should handle tool execution correctly", async () => {
+      const mockExecute = jest.fn().mockResolvedValue("mock result");
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: mockExecute,
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      const executeResult = await action.handler({ name: "test" });
+      expect(executeResult).toBe("mock result");
+      expect(mockExecute).toHaveBeenCalledWith({ name: "test" });
+    });
+
+    it("should stringify non-string results", async () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => ({ result: "complex object" }),
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      const executeResult = await action.handler({ name: "test" });
+      expect(executeResult).toBe('{"result":"complex object"}');
+    });
+
+    it("should handle execution errors", async () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => {
+            throw new Error("Test error");
+          },
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      await expect(action.handler({ name: "test" })).rejects.toThrow(
+        "Execution failed for MCP tool 'testTool': Test error",
+      );
+    });
+  });
+});

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

@@ -0,0 +1,209 @@
+import { map } from "rxjs";
+import { LangGraphEventTypes } from "../../../../agents/langgraph/events";
+import { RawEvent } from "@ag-ui/core";
+import {
+  LangGraphAgent as AGUILangGraphAgent,
+  LangGraphHttpAgent,
+  type LangGraphAgentConfig,
+  ProcessedEvents,
+  SchemaKeys,
+  type State,
+  StateEnrichment,
+} from "@ag-ui/langgraph";
+import { Message as LangGraphMessage } from "@langchain/langgraph-sdk/dist/types.messages";
+import { ThreadState } from "@langchain/langgraph-sdk";
+
+interface CopilotKitStateEnrichment {
+  copilotkit: {
+    actions: StateEnrichment["ag-ui"]["tools"];
+    context: StateEnrichment["ag-ui"]["context"];
+  };
+}
+
+import { RunAgentInput, EventType, CustomEvent } from "@ag-ui/client";
+
+// Import and re-export from separate file to maintain API compatibility
+import { CustomEventNames, TextMessageEvents, ToolCallEvents, PredictStateTool } from "./consts";
+export { CustomEventNames };
+
+export class LangGraphAgent extends AGUILangGraphAgent {
+  constructor(config: LangGraphAgentConfig) {
+    super(config);
+  }
+
+  // @ts-ignore
+  public clone() {
+    return new LangGraphAgent(this.config);
+  }
+
+  dispatchEvent(event: ProcessedEvents) {
+    if (event.type === EventType.CUSTOM) {
+      // const event = processedEvent as unknown as CustomEvent;
+      const customEvent = event as unknown as CustomEvent;
+
+      if (customEvent.name === CustomEventNames.CopilotKitManuallyEmitMessage) {
+        this.subscriber.next({
+          type: EventType.TEXT_MESSAGE_START,
+          role: "assistant",
+          messageId: customEvent.value.message_id,
+          rawEvent: event,
+        });
+        this.subscriber.next({
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: customEvent.value.message_id,
+          delta: customEvent.value.message,
+          rawEvent: event,
+        });
+        this.subscriber.next({
+          type: EventType.TEXT_MESSAGE_END,
+          messageId: customEvent.value.message_id,
+          rawEvent: event,
+        });
+        return true;
+      }
+
+      if (customEvent.name === CustomEventNames.CopilotKitManuallyEmitToolCall) {
+        this.subscriber.next({
+          type: EventType.TOOL_CALL_START,
+          toolCallId: customEvent.value.id,
+          toolCallName: customEvent.value.name,
+          parentMessageId: customEvent.value.id,
+          rawEvent: event,
+        });
+        this.subscriber.next({
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: customEvent.value.id,
+          delta: customEvent.value.args,
+          rawEvent: event,
+        });
+        this.subscriber.next({
+          type: EventType.TOOL_CALL_END,
+          toolCallId: customEvent.value.id,
+          rawEvent: event,
+        });
+        return true;
+      }
+
+      if (customEvent.name === CustomEventNames.CopilotKitManuallyEmitIntermediateState) {
+        this.activeRun.manuallyEmittedState = customEvent.value;
+        this.dispatchEvent({
+          type: EventType.STATE_SNAPSHOT,
+          snapshot: this.getStateSnapshot({
+            values: this.activeRun.manuallyEmittedState,
+          } as ThreadState<State>),
+          rawEvent: event,
+        });
+        return true;
+      }
+
+      if (customEvent.name === CustomEventNames.CopilotKitExit) {
+        this.subscriber.next({
+          type: EventType.CUSTOM,
+          name: "Exit",
+          value: true,
+        });
+        return true;
+      }
+    }
+
+    // Intercept all text message and tool call events and check if should disable
+    const rawEvent = (event as ToolCallEvents | TextMessageEvents).rawEvent;
+    if (!rawEvent) {
+      this.subscriber.next(event);
+      return true;
+    }
+
+    const isMessageEvent =
+      event.type === EventType.TEXT_MESSAGE_START ||
+      event.type === EventType.TEXT_MESSAGE_CONTENT ||
+      event.type === EventType.TEXT_MESSAGE_END;
+    const isToolEvent =
+      event.type === EventType.TOOL_CALL_START ||
+      event.type === EventType.TOOL_CALL_ARGS ||
+      event.type === EventType.TOOL_CALL_END;
+    if ("copilotkit:emit-tool-calls" in (rawEvent.metadata || {})) {
+      if (rawEvent.metadata["copilotkit:emit-tool-calls"] === false && isToolEvent) {
+        return false;
+      }
+    }
+    if ("copilotkit:emit-messages" in (rawEvent.metadata || {})) {
+      if (rawEvent.metadata["copilotkit:emit-messages"] === false && isMessageEvent) {
+        return false;
+      }
+    }
+
+    this.subscriber.next(event);
+    return true;
+  }
+
+  // @ts-ignore
+  run(input: RunAgentInput) {
+    return super.run(input).pipe(
+      map((processedEvent) => {
+        // Turn raw event into emit state snapshot from tool call event
+        if (processedEvent.type === EventType.RAW) {
+          // Get the LangGraph event from the AGUI event.
+          const event = (processedEvent as RawEvent).event ?? (processedEvent as RawEvent).rawEvent;
+
+          const eventType = event.event;
+          const toolCallData = event.data?.chunk?.tool_call_chunks?.[0];
+          const toolCallUsedToPredictState = event.metadata?.[
+            "copilotkit:emit-intermediate-state"
+          ]?.some(
+            (predictStateTool: PredictStateTool) => predictStateTool.tool === toolCallData?.name,
+          );
+
+          if (eventType === LangGraphEventTypes.OnChatModelStream && toolCallUsedToPredictState) {
+            return {
+              type: EventType.CUSTOM,
+              name: "PredictState",
+              value: event.metadata["copilotkit:emit-intermediate-state"],
+            };
+          }
+        }
+
+        return processedEvent;
+      }),
+    );
+  }
+
+  langGraphDefaultMergeState(
+    state: State,
+    messages: LangGraphMessage[],
+    input: RunAgentInput,
+  ): State<StateEnrichment & CopilotKitStateEnrichment> {
+    const aguiMergedState = super.langGraphDefaultMergeState(state, messages, input);
+    const { tools: returnedTools, "ag-ui": agui } = aguiMergedState;
+    // tolerate undefined and de-duplicate by stable key (id | name | key)
+    const rawCombinedTools = [
+      ...((returnedTools as any[]) ?? []),
+      ...((agui?.tools as any[]) ?? []),
+    ];
+    const combinedTools = Array.from(
+      new Map(
+        rawCombinedTools.map((t: any) => [t?.id ?? t?.name ?? t?.key ?? JSON.stringify(t), t]),
+      ).values(),
+    );
+
+    return {
+      ...aguiMergedState,
+      copilotkit: {
+        actions: combinedTools,
+        context: agui?.context ?? [],
+      },
+    };
+  }
+
+  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,
+      context: schemaKeys.context ? [...schemaKeys.context, ...CONSTANT_KEYS] : null,
+    };
+  }
+}
+
+export { LangGraphHttpAgent };

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

@@ -0,0 +1,34 @@
+/**
+ * Constants for LangGraph integration.
+ * This file is separate from langgraph.agent.ts to avoid pulling in @ag-ui/langgraph
+ * when only these constants are needed.
+ */
+
+import {
+  TextMessageStartEvent,
+  TextMessageContentEvent,
+  TextMessageEndEvent,
+  ToolCallStartEvent,
+  ToolCallArgsEvent,
+  ToolCallEndEvent,
+} from "@ag-ui/client";
+
+export type TextMessageEvents =
+  | TextMessageStartEvent
+  | TextMessageContentEvent
+  | TextMessageEndEvent;
+
+export type ToolCallEvents = ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent;
+
+export enum CustomEventNames {
+  CopilotKitManuallyEmitMessage = "copilotkit_manually_emit_message",
+  CopilotKitManuallyEmitToolCall = "copilotkit_manually_emit_tool_call",
+  CopilotKitManuallyEmitIntermediateState = "copilotkit_manually_emit_intermediate_state",
+  CopilotKitExit = "copilotkit_exit",
+}
+
+export interface PredictStateTool {
+  tool: string;
+  state_key: string;
+  tool_argument: string;
+}

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

@@ -0,0 +1,2 @@
+export * from "./consts";
+export * from "./agent";