@copilotkit/runtime 0.0.0-test-custom-tag-prerelease-1-20250108200215

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

@@ -0,0 +1,412 @@
+/**
+ * <Callout type="info">
+ *   This is the reference for the `CopilotRuntime` class. For more information and example code snippets, please see [Concept: Copilot Runtime](/concepts/copilot-runtime).
+ * </Callout>
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { CopilotRuntime } from "@copilotkit/runtime";
+ *
+ * const copilotKit = new CopilotRuntime();
+ * ```
+ */
+
+import { Action, actionParametersToJsonSchema, Parameter, randomId } from "@copilotkit/shared";
+import { CopilotServiceAdapter, RemoteChain, RemoteChainParameters } from "../../service-adapters";
+import { MessageInput } from "../../graphql/inputs/message.input";
+import { ActionInput } from "../../graphql/inputs/action.input";
+import { RuntimeEventSource } from "../../service-adapters/events";
+import { convertGqlInputToMessages } from "../../service-adapters/conversion";
+import { Message } from "../../graphql/types/converted";
+import { ForwardedParametersInput } from "../../graphql/inputs/forwarded-parameters.input";
+import {
+  isLangGraphAgentAction,
+  LangGraphAgentAction,
+  EndpointType,
+  setupRemoteActions,
+  EndpointDefinition,
+  CopilotKitEndpoint,
+  LangGraphPlatformEndpoint,
+} from "./remote-actions";
+import { GraphQLContext } from "../integrations/shared";
+import { AgentSessionInput } from "../../graphql/inputs/agent-session.input";
+import { from } from "rxjs";
+import { AgentStateInput } from "../../graphql/inputs/agent-state.input";
+import { ActionInputAvailability } from "../../graphql/types/enums";
+
+interface CopilotRuntimeRequest {
+  serviceAdapter: CopilotServiceAdapter;
+  messages: MessageInput[];
+  actions: ActionInput[];
+  agentSession?: AgentSessionInput;
+  agentStates?: AgentStateInput[];
+  outputMessagesPromise: Promise<Message[]>;
+  threadId?: string;
+  runId?: string;
+  publicApiKey?: string;
+  graphqlContext: GraphQLContext;
+  forwardedParameters?: ForwardedParametersInput;
+  url?: string;
+}
+
+interface CopilotRuntimeResponse {
+  threadId: string;
+  runId?: string;
+  eventSource: RuntimeEventSource;
+  serverSideActions: Action<any>[];
+  actionInputsWithoutAgents: ActionInput[];
+}
+
+type ActionsConfiguration<T extends Parameter[] | [] = []> =
+  | Action<T>[]
+  | ((ctx: { properties: any; url?: string }) => Action<T>[]);
+
+interface OnBeforeRequestOptions {
+  threadId?: string;
+  runId?: string;
+  inputMessages: Message[];
+  properties: any;
+  url?: string;
+}
+
+type OnBeforeRequestHandler = (options: OnBeforeRequestOptions) => void | Promise<void>;
+
+interface OnAfterRequestOptions {
+  threadId: string;
+  runId?: string;
+  inputMessages: Message[];
+  outputMessages: Message[];
+  properties: any;
+  url?: string;
+}
+
+type OnAfterRequestHandler = (options: OnAfterRequestOptions) => void | Promise<void>;
+
+interface Middleware {
+  /**
+   * A function that is called before the request is processed.
+   */
+  onBeforeRequest?: OnBeforeRequestHandler;
+
+  /**
+   * A function that is called after the request is processed.
+   */
+  onAfterRequest?: OnAfterRequestHandler;
+}
+
+export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []> {
+  /**
+   * Middleware to be used by the runtime.
+   *
+   * ```ts
+   * onBeforeRequest: (options: {
+   *   threadId?: string;
+   *   runId?: string;
+   *   inputMessages: Message[];
+   *   properties: any;
+   * }) => void | Promise<void>;
+   * ```
+   *
+   * ```ts
+   * onAfterRequest: (options: {
+   *   threadId?: string;
+   *   runId?: string;
+   *   inputMessages: Message[];
+   *   outputMessages: Message[];
+   *   properties: any;
+   * }) => void | Promise<void>;
+   * ```
+   */
+  middleware?: Middleware;
+
+  /*
+   * A list of server side actions that can be executed.
+   */
+  actions?: ActionsConfiguration<T>;
+
+  /*
+   * Deprecated: Use `remoteEndpoints`.
+   */
+  remoteActions?: CopilotKitEndpoint[];
+
+  /*
+   * A list of remote actions that can be executed.
+   */
+  remoteEndpoints?: EndpointDefinition[];
+
+  /*
+   * An array of LangServer URLs.
+   */
+  langserve?: RemoteChainParameters[];
+}
+
+export class CopilotRuntime<const T extends Parameter[] | [] = []> {
+  public actions: ActionsConfiguration<T>;
+  public remoteEndpointDefinitions: EndpointDefinition[];
+  private langserve: Promise<Action<any>>[] = [];
+  private onBeforeRequest?: OnBeforeRequestHandler;
+  private onAfterRequest?: OnAfterRequestHandler;
+
+  constructor(params?: CopilotRuntimeConstructorParams<T>) {
+    this.actions = params?.actions || [];
+
+    for (const chain of params?.langserve || []) {
+      const remoteChain = new RemoteChain(chain);
+      this.langserve.push(remoteChain.toAction());
+    }
+
+    this.remoteEndpointDefinitions = params?.remoteEndpoints ?? params?.remoteActions ?? [];
+
+    this.onBeforeRequest = params?.middleware?.onBeforeRequest;
+    this.onAfterRequest = params?.middleware?.onAfterRequest;
+  }
+
+  async processRuntimeRequest(request: CopilotRuntimeRequest): Promise<CopilotRuntimeResponse> {
+    const {
+      serviceAdapter,
+      messages: rawMessages,
+      actions: clientSideActionsInput,
+      threadId,
+      runId,
+      outputMessagesPromise,
+      graphqlContext,
+      forwardedParameters,
+      agentSession,
+      url,
+    } = request;
+
+    const eventSource = new RuntimeEventSource();
+
+    try {
+      if (agentSession) {
+        return await this.processAgentRequest(request);
+      }
+
+      const messages = rawMessages.filter((message) => !message.agentStateMessage);
+
+      const inputMessages = convertGqlInputToMessages(messages);
+      const serverSideActions = await this.getServerSideActions(request);
+
+      const serverSideActionsInput: ActionInput[] = serverSideActions.map((action) => ({
+        name: action.name,
+        description: action.description,
+        jsonSchema: JSON.stringify(actionParametersToJsonSchema(action.parameters)),
+      }));
+
+      const actionInputs = flattenToolCallsNoDuplicates([
+        ...serverSideActionsInput,
+        ...clientSideActionsInput.filter(
+          // Filter remote actions from CopilotKit core loop
+          (action) => action.available !== ActionInputAvailability.remote,
+        ),
+      ]);
+
+      await this.onBeforeRequest?.({
+        threadId,
+        runId,
+        inputMessages,
+        properties: graphqlContext.properties,
+        url,
+      });
+
+      const result = await serviceAdapter.process({
+        messages: inputMessages,
+        actions: actionInputs,
+        threadId,
+        runId,
+        eventSource,
+        forwardedParameters,
+      });
+
+      outputMessagesPromise
+        .then((outputMessages) => {
+          this.onAfterRequest?.({
+            threadId: result.threadId,
+            runId: result.runId,
+            inputMessages,
+            outputMessages,
+            properties: graphqlContext.properties,
+            url,
+          });
+        })
+        .catch((_error) => {});
+
+      return {
+        threadId: result.threadId,
+        runId: result.runId,
+        eventSource,
+        serverSideActions,
+        actionInputsWithoutAgents: actionInputs.filter(
+          (action) =>
+            // TODO-AGENTS: do not exclude ALL server side actions
+            !serverSideActions.find((serverSideAction) => serverSideAction.name == action.name),
+          // !isLangGraphAgentAction(
+          //   serverSideActions.find((serverSideAction) => serverSideAction.name == action.name),
+          // ),
+        ),
+      };
+    } catch (error) {
+      console.error("Error getting response:", error);
+      eventSource.sendErrorMessageToChat();
+      throw error;
+    }
+  }
+
+  private async processAgentRequest(
+    request: CopilotRuntimeRequest,
+  ): Promise<CopilotRuntimeResponse> {
+    const { messages: rawMessages, outputMessagesPromise, graphqlContext, agentSession } = request;
+    const { threadId, agentName, nodeName } = agentSession;
+    const serverSideActions = await this.getServerSideActions(request);
+
+    const messages = convertGqlInputToMessages(rawMessages);
+
+    const agent = serverSideActions.find(
+      (action) => action.name === agentName && isLangGraphAgentAction(action),
+    ) as LangGraphAgentAction;
+
+    if (!agent) {
+      throw new Error(`Agent ${agentName} not found`);
+    }
+
+    const serverSideActionsInput: ActionInput[] = serverSideActions
+      .filter((action) => !isLangGraphAgentAction(action))
+      .map((action) => ({
+        name: action.name,
+        description: action.description,
+        jsonSchema: JSON.stringify(actionParametersToJsonSchema(action.parameters)),
+      }));
+
+    const actionInputsWithoutAgents = flattenToolCallsNoDuplicates([
+      ...serverSideActionsInput,
+      ...request.actions,
+    ]);
+
+    await this.onBeforeRequest?.({
+      threadId,
+      runId: undefined,
+      inputMessages: messages,
+      properties: graphqlContext.properties,
+    });
+    try {
+      const eventSource = new RuntimeEventSource();
+      const stream = await agent.langGraphAgentHandler({
+        name: agentName,
+        threadId,
+        nodeName,
+        actionInputsWithoutAgents,
+      });
+
+      eventSource.stream(async (eventStream$) => {
+        from(stream).subscribe({
+          next: (event) => eventStream$.next(event),
+          error: (err) => console.error("Error in stream", err),
+          complete: () => eventStream$.complete(),
+        });
+      });
+
+      outputMessagesPromise
+        .then((outputMessages) => {
+          this.onAfterRequest?.({
+            threadId,
+            runId: undefined,
+            inputMessages: messages,
+            outputMessages,
+            properties: graphqlContext.properties,
+          });
+        })
+        .catch((_error) => {});
+
+      return {
+        threadId,
+        runId: undefined,
+        eventSource,
+        serverSideActions: [],
+        actionInputsWithoutAgents,
+      };
+    } catch (error) {
+      console.error("Error getting response:", error);
+      throw error;
+    }
+  }
+
+  private async getServerSideActions(request: CopilotRuntimeRequest): Promise<Action<any>[]> {
+    const { messages: rawMessages, graphqlContext, agentStates, url } = request;
+    const inputMessages = convertGqlInputToMessages(rawMessages);
+    const langserveFunctions: Action<any>[] = [];
+
+    for (const chainPromise of this.langserve) {
+      try {
+        const chain = await chainPromise;
+        langserveFunctions.push(chain);
+      } catch (error) {
+        console.error("Error loading langserve chain:", error);
+      }
+    }
+
+    const remoteEndpointDefinitions = this.remoteEndpointDefinitions.map(
+      (endpoint) =>
+        ({
+          ...endpoint,
+          type: resolveEndpointType(endpoint),
+        }) as EndpointDefinition,
+    );
+
+    const remoteActions = await setupRemoteActions({
+      remoteEndpointDefinitions,
+      graphqlContext,
+      messages: inputMessages,
+      agentStates,
+      frontendUrl: url,
+    });
+
+    const configuredActions =
+      typeof this.actions === "function"
+        ? this.actions({ properties: graphqlContext.properties, url })
+        : this.actions;
+
+    return [...configuredActions, ...langserveFunctions, ...remoteActions];
+  }
+}
+
+export function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[] {
+  let allTools: ActionInput[] = [];
+  const allToolNames: string[] = [];
+  for (const tool of toolsByPriority) {
+    if (!allToolNames.includes(tool.name)) {
+      allTools.push(tool);
+      allToolNames.push(tool.name);
+    }
+  }
+  return allTools;
+}
+
+// The two functions below are "factory functions", meant to create the action objects that adhere to the expected interfaces
+export function copilotKitEndpoint(config: Omit<CopilotKitEndpoint, "type">): CopilotKitEndpoint {
+  return {
+    ...config,
+    type: EndpointType.CopilotKit,
+  };
+}
+
+export function langGraphPlatformEndpoint(
+  config: Omit<LangGraphPlatformEndpoint, "type">,
+): LangGraphPlatformEndpoint {
+  return {
+    ...config,
+    type: EndpointType.LangGraphPlatform,
+  };
+}
+
+export function resolveEndpointType(endpoint: EndpointDefinition) {
+  if (!endpoint.type) {
+    if ("langsmithApiKey" in endpoint && "deploymentUrl" in endpoint && "agents" in endpoint) {
+      return EndpointType.LangGraphPlatform;
+    } else {
+      return EndpointType.CopilotKit;
+    }
+  }
+
+  return endpoint.type;
+}

package/src/lib/runtime/remote-action-constructors.ts

@@ -0,0 +1,304 @@
+import { createHash } from "node:crypto";
+import {
+  CopilotKitEndpoint,
+  LangGraphAgentHandlerParams,
+  RemoteActionInfoResponse,
+  LangGraphPlatformEndpoint,
+} from "./remote-actions";
+import { GraphQLContext } from "../integrations";
+import { Logger } from "pino";
+import { Message } from "../../graphql/types/converted";
+import { AgentStateInput } from "../../graphql/inputs/agent-state.input";
+import { Observable, ReplaySubject } from "rxjs";
+import { RuntimeEvent } from "../../service-adapters/events";
+import telemetry from "../telemetry-client";
+import { RemoteLangGraphEventSource } from "../../agents/langgraph/event-source";
+import { Action } from "@copilotkit/shared";
+import { LangGraphEvent } from "../../agents/langgraph/events";
+import { execute } from "./remote-lg-action";
+
+export function constructLGCRemoteAction({
+  endpoint,
+  graphqlContext,
+  logger,
+  messages,
+  agentStates,
+}: {
+  endpoint: LangGraphPlatformEndpoint;
+  graphqlContext: GraphQLContext;
+  logger: Logger;
+  messages: Message[];
+  agentStates?: AgentStateInput[];
+}) {
+  const agents = endpoint.agents.map((agent) => ({
+    name: agent.name,
+    description: agent.description,
+    parameters: [],
+    handler: async (_args: any) => {},
+    langGraphAgentHandler: async ({
+      name,
+      actionInputsWithoutAgents,
+      threadId,
+      nodeName,
+      additionalMessages = [],
+    }: LangGraphAgentHandlerParams): Promise<Observable<RuntimeEvent>> => {
+      logger.debug({ actionName: agent.name }, "Executing LangGraph Platform agent");
+
+      telemetry.capture("oss.runtime.remote_action_executed", {
+        agentExecution: true,
+        type: "langgraph-platform",
+        agentsAmount: endpoint.agents.length,
+        hashedLgcKey: createHash("sha256").update(endpoint.langsmithApiKey).digest("hex"),
+      });
+
+      let state = {};
+      if (agentStates) {
+        const jsonState = agentStates.find((state) => state.agentName === name)?.state;
+        if (jsonState) {
+          state = JSON.parse(jsonState);
+        }
+      }
+
+      try {
+        const response = await execute({
+          logger,
+          deploymentUrl: endpoint.deploymentUrl,
+          langsmithApiKey: endpoint.langsmithApiKey,
+          agent,
+          threadId,
+          nodeName,
+          messages: [...messages, ...additionalMessages],
+          state,
+          properties: graphqlContext.properties,
+          actions: actionInputsWithoutAgents.map((action) => ({
+            name: action.name,
+            description: action.description,
+            parameters: JSON.parse(action.jsonSchema) as string,
+          })),
+        });
+
+        const eventSource = new RemoteLangGraphEventSource();
+        streamResponse(response, eventSource.eventStream$);
+        return eventSource.processLangGraphEvents();
+      } catch (error) {
+        logger.error(
+          { url: endpoint.deploymentUrl, status: 500, body: error.message },
+          "Failed to execute LangGraph Platform agent",
+        );
+        throw new Error("Failed to execute LangGraph Platform agent");
+      }
+    },
+  }));
+
+  return [...agents];
+}
+
+export function constructRemoteActions({
+  json,
+  url,
+  onBeforeRequest,
+  graphqlContext,
+  logger,
+  messages,
+  agentStates,
+}: {
+  json: RemoteActionInfoResponse;
+  url: string;
+  onBeforeRequest?: CopilotKitEndpoint["onBeforeRequest"];
+  graphqlContext: GraphQLContext;
+  logger: Logger;
+  messages: Message[];
+  agentStates?: AgentStateInput[];
+}): Action<any>[] {
+  const totalAgents = Array.isArray(json["agents"]) ? json["agents"].length : 0;
+
+  const actions = json["actions"].map((action) => ({
+    name: action.name,
+    description: action.description,
+    parameters: action.parameters,
+    handler: async (args: any) => {
+      logger.debug({ actionName: action.name, args }, "Executing remote action");
+
+      const headers = createHeaders(onBeforeRequest, graphqlContext);
+      telemetry.capture("oss.runtime.remote_action_executed", {
+        agentExecution: false,
+        type: "self-hosted",
+        agentsAmount: totalAgents,
+      });
+
+      try {
+        const response = await fetch(`${url}/actions/execute`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            name: action.name,
+            arguments: args,
+            properties: graphqlContext.properties,
+          }),
+        });
+
+        if (!response.ok) {
+          logger.error(
+            { url, status: response.status, body: await response.text() },
+            "Failed to execute remote action",
+          );
+          return "Failed to execute remote action";
+        }
+
+        const requestResult = await response.json();
+
+        const result = requestResult["result"];
+        logger.debug({ actionName: action.name, result }, "Executed remote action");
+        return result;
+      } catch (error) {
+        logger.error(
+          { error: error.message ? error.message : error + "" },
+          "Failed to execute remote action",
+        );
+        return "Failed to execute remote action";
+      }
+    },
+  }));
+
+  const agents = totalAgents
+    ? json["agents"].map((agent) => ({
+        name: agent.name,
+        description: agent.description,
+        parameters: [],
+        handler: async (_args: any) => {},
+
+        langGraphAgentHandler: async ({
+          name,
+          actionInputsWithoutAgents,
+          threadId,
+          nodeName,
+          additionalMessages = [],
+        }: LangGraphAgentHandlerParams): Promise<Observable<RuntimeEvent>> => {
+          logger.debug({ actionName: agent.name }, "Executing remote agent");
+
+          const headers = createHeaders(onBeforeRequest, graphqlContext);
+          telemetry.capture("oss.runtime.remote_action_executed", {
+            agentExecution: true,
+            type: "self-hosted",
+            agentsAmount: json["agents"].length,
+          });
+
+          let state = {};
+          if (agentStates) {
+            const jsonState = agentStates.find((state) => state.agentName === name)?.state;
+            if (jsonState) {
+              state = JSON.parse(jsonState);
+            }
+          }
+
+          const response = await fetch(`${url}/agents/execute`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+              name,
+              threadId,
+              nodeName,
+              messages: [...messages, ...additionalMessages],
+              state,
+              properties: graphqlContext.properties,
+              actions: actionInputsWithoutAgents.map((action) => ({
+                name: action.name,
+                description: action.description,
+                parameters: JSON.parse(action.jsonSchema),
+              })),
+            }),
+          });
+
+          if (!response.ok) {
+            logger.error(
+              { url, status: response.status, body: await response.text() },
+              "Failed to execute remote agent",
+            );
+            throw new Error("Failed to execute remote agent");
+          }
+
+          const eventSource = new RemoteLangGraphEventSource();
+          streamResponse(response.body!, eventSource.eventStream$);
+          return eventSource.processLangGraphEvents();
+        },
+      }))
+    : [];
+
+  return [...actions, ...agents];
+}
+
+async function streamResponse(
+  response: ReadableStream<Uint8Array>,
+  eventStream$: ReplaySubject<LangGraphEvent>,
+) {
+  const reader = response.getReader();
+  const decoder = new TextDecoder();
+  let buffer = [];
+
+  function flushBuffer() {
+    const currentBuffer = buffer.join("");
+    if (currentBuffer.trim().length === 0) {
+      return;
+    }
+    const parts = currentBuffer.split("\n");
+    if (parts.length === 0) {
+      return;
+    }
+
+    const lastPartIsComplete = currentBuffer.endsWith("\n");
+
+    // truncate buffer
+    buffer = [];
+
+    if (!lastPartIsComplete) {
+      // put back the last part
+      buffer.push(parts.pop());
+    }
+
+    parts
+      .map((part) => part.trim())
+      .filter((part) => part != "")
+      .forEach((part) => {
+        eventStream$.next(JSON.parse(part));
+      });
+  }
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (!done) {
+        buffer.push(decoder.decode(value, { stream: true }));
+      }
+
+      flushBuffer();
+
+      if (done) {
+        break;
+      }
+    }
+  } catch (error) {
+    console.error("Error in stream", error);
+    eventStream$.error(error);
+    return;
+  }
+  eventStream$.complete();
+}
+
+export function createHeaders(
+  onBeforeRequest: CopilotKitEndpoint["onBeforeRequest"],
+  graphqlContext: GraphQLContext,
+) {
+  const headers = {
+    "Content-Type": "application/json",
+  };
+
+  if (onBeforeRequest) {
+    const { headers: additionalHeaders } = onBeforeRequest({ ctx: graphqlContext });
+    if (additionalHeaders) {
+      Object.assign(headers, additionalHeaders);
+    }
+  }
+
+  return headers;
+}