@copilotkit/runtime 1.55.3-canary.1776260990 → 1.56.0

package/dist/v2/runtime/handlers/shared/sse-response.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sse-response.cjs","names":["EventEncoder"],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-response.ts"],"sourcesContent":["import { BaseEvent } from \"@ag-ui/client\";\nimport { EventEncoder } from \"@ag-ui/encoder\";\nimport { Observable, Subscription } from \"rxjs\";\nimport { telemetry } from \"../../telemetry\";\n\ninterface CreateSseEventResponseParams {\n  request: Request;\n  observableFactory: () =>\n    | Promise<Observable<BaseEvent>>\n    | Observable<BaseEvent>;\n}\n\nexport function createSseEventResponse({\n  request,\n  observableFactory,\n}: CreateSseEventResponseParams): Response {\n  const stream = new TransformStream();\n  const writer = stream.writable.getWriter();\n  const encoder = new EventEncoder();\n  let streamClosed = false;\n\n  const closeStream = async () => {\n    if (!streamClosed) {\n      try {\n        await writer.close();\n        streamClosed = true;\n      } catch {\n        // Stream already closed.\n      }\n    }\n  };\n\n  const logError = (error: unknown) => {\n    console.error(\"Error running agent:\", error);\n    console.error(\n      \"Error stack:\",\n      error instanceof Error ? error.stack : \"No stack trace\",\n    );\n    console.error(\"Error details:\", {\n      name: error instanceof Error ? error.name : \"Unknown\",\n      message: error instanceof Error ? error.message : String(error),\n      cause: error instanceof Error ? error.cause : undefined,\n    });\n  };\n\n  let subscription: Subscription | undefined;\n\n  (async () => {\n    const observable = await observableFactory();\n\n    telemetry.capture(\"oss.runtime.agent_execution_stream_started\", {});\n\n    subscription = observable.subscribe({\n      next: async (event) => {\n        if (!request.signal.aborted && !streamClosed) {\n          try {\n            await writer.write(encoder.encode(event));\n          } catch (error) {\n            if (error instanceof Error && error.name === \"AbortError\") {\n              streamClosed = true;\n            }\n          }\n        }\n      },\n      error: async (error) => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_errored\", {\n          error: error instanceof Error ? error.message : String(error),\n        });\n        logError(error);\n        await closeStream();\n      },\n      complete: async () => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_ended\", {});\n        await closeStream();\n      },\n    });\n\n    // If the client disconnected before the subscription was created,\n    // unsubscribe immediately to avoid leaking the observable.\n    if (request.signal.aborted) {\n      subscription.unsubscribe();\n    }\n  })().catch(async (error) => {\n    logError(error);\n    await closeStream();\n  });\n\n  request.signal.addEventListener(\"abort\", () => {\n    subscription?.unsubscribe();\n  });\n\n  return new Response(stream.readable, {\n    status: 200,\n    headers: {\n      \"Content-Type\": \"text/event-stream\",\n      \"Cache-Control\": \"no-cache\",\n      Connection: \"keep-alive\",\n    },\n  });\n}\n"],"mappings":";;;;;;AAYA,SAAgB,uBAAuB,EACrC,SACA,qBACyC;CACzC,MAAM,SAAS,IAAI,iBAAiB;CACpC,MAAM,SAAS,OAAO,SAAS,WAAW;CAC1C,MAAM,UAAU,IAAIA,6BAAc;CAClC,IAAI,eAAe;CAEnB,MAAM,cAAc,YAAY;AAC9B,MAAI,CAAC,aACH,KAAI;AACF,SAAM,OAAO,OAAO;AACpB,kBAAe;UACT;;CAMZ,MAAM,YAAY,UAAmB;AACnC,UAAQ,MAAM,wBAAwB,MAAM;AAC5C,UAAQ,MACN,gBACA,iBAAiB,QAAQ,MAAM,QAAQ,iBACxC;AACD,UAAQ,MAAM,kBAAkB;GAC9B,MAAM,iBAAiB,QAAQ,MAAM,OAAO;GAC5C,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GAC/D,OAAO,iBAAiB,QAAQ,MAAM,QAAQ;GAC/C,CAAC;;CAGJ,IAAI;AAEJ,EAAC,YAAY;EACX,MAAM,aAAa,MAAM,mBAAmB;AAE5C,mCAAU,QAAQ,8CAA8C,EAAE,CAAC;AAEnE,iBAAe,WAAW,UAAU;GAClC,MAAM,OAAO,UAAU;AACrB,QAAI,CAAC,QAAQ,OAAO,WAAW,CAAC,aAC9B,KAAI;AACF,WAAM,OAAO,MAAM,QAAQ,OAAO,MAAM,CAAC;aAClC,OAAO;AACd,SAAI,iBAAiB,SAAS,MAAM,SAAS,aAC3C,gBAAe;;;GAKvB,OAAO,OAAO,UAAU;AACtB,qCAAU,QAAQ,8CAA8C,EAC9D,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EAC9D,CAAC;AACF,aAAS,MAAM;AACf,UAAM,aAAa;;GAErB,UAAU,YAAY;AACpB,qCAAU,QAAQ,4CAA4C,EAAE,CAAC;AACjE,UAAM,aAAa;;GAEtB,CAAC;AAIF,MAAI,QAAQ,OAAO,QACjB,cAAa,aAAa;KAE1B,CAAC,MAAM,OAAO,UAAU;AAC1B,WAAS,MAAM;AACf,QAAM,aAAa;GACnB;AAEF,SAAQ,OAAO,iBAAiB,eAAe;AAC7C,gBAAc,aAAa;GAC3B;AAEF,QAAO,IAAI,SAAS,OAAO,UAAU;EACnC,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,iBAAiB;GACjB,YAAY;GACb;EACF,CAAC"}
+{"version":3,"file":"sse-response.cjs","names":["EventEncoder","createLogger"],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-response.ts"],"sourcesContent":["import { BaseEvent } from \"@ag-ui/client\";\nimport { EventEncoder } from \"@ag-ui/encoder\";\nimport { Observable, Subscription } from \"rxjs\";\nimport { ResolvedDebugConfig } from \"@copilotkit/shared\";\nimport {\n  createLogger,\n  type CopilotRuntimeLogger,\n} from \"../../../../lib/logger\";\nimport { telemetry } from \"../../telemetry\";\n\ninterface CreateSseEventResponseParams {\n  request: Request;\n  observableFactory: () =>\n    | Promise<Observable<BaseEvent>>\n    | Observable<BaseEvent>;\n  debug?: ResolvedDebugConfig;\n  /** Pre-created logger instance to avoid creating a new pino logger per request. */\n  logger?: CopilotRuntimeLogger;\n}\n\nexport function createSseEventResponse({\n  request,\n  observableFactory,\n  debug,\n  logger,\n}: CreateSseEventResponseParams): Response {\n  const stream = new TransformStream();\n  const writer = stream.writable.getWriter();\n  const encoder = new EventEncoder();\n  let streamClosed = false;\n\n  const debugLogger = debug?.enabled\n    ? (logger ??\n      createLogger({ level: \"debug\", component: \"copilotkit-debug\" }))\n    : undefined;\n\n  const closeStream = async () => {\n    if (!streamClosed) {\n      try {\n        await writer.close();\n        streamClosed = true;\n      } catch {\n        // Stream already closed.\n      }\n    }\n  };\n\n  const logError = (error: unknown) => {\n    console.error(\"Error running agent:\", error);\n    console.error(\n      \"Error stack:\",\n      error instanceof Error ? error.stack : \"No stack trace\",\n    );\n    console.error(\"Error details:\", {\n      name: error instanceof Error ? error.name : \"Unknown\",\n      message: error instanceof Error ? error.message : String(error),\n      cause: error instanceof Error ? error.cause : undefined,\n    });\n  };\n\n  let subscription: Subscription | undefined;\n\n  (async () => {\n    const observable = await observableFactory();\n\n    telemetry.capture(\"oss.runtime.agent_execution_stream_started\", {});\n\n    if (debug?.lifecycle) {\n      debugLogger!.debug(\"SSE stream opened\");\n    }\n\n    let eventCount = 0;\n    let loggedEventCount = 0;\n\n    subscription = observable.subscribe({\n      next: async (event) => {\n        if (!request.signal.aborted && !streamClosed) {\n          try {\n            eventCount++;\n            if (debug?.events) {\n              loggedEventCount++;\n              if (debug.verbose) {\n                debugLogger!.debug({ event }, \"Event emitted\");\n              } else {\n                debugLogger!.debug(\n                  { type: event.type, ...summarizeEvent(event) },\n                  \"Event emitted\",\n                );\n              }\n            }\n            await writer.write(encoder.encode(event));\n          } catch (error) {\n            if (error instanceof Error && error.name === \"AbortError\") {\n              streamClosed = true;\n            }\n          }\n        }\n      },\n      error: async (error) => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_errored\", {\n          error: error instanceof Error ? error.message : String(error),\n        });\n        if (debug?.lifecycle) {\n          debugLogger!.debug(\n            { error: error instanceof Error ? error.message : String(error) },\n            \"SSE stream errored\",\n          );\n        }\n        logError(error);\n        await closeStream();\n      },\n      complete: async () => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_ended\", {});\n        if (debug?.lifecycle) {\n          debugLogger!.debug(\n            { eventCount, loggedEventCount },\n            \"SSE stream completed\",\n          );\n        }\n        await closeStream();\n      },\n    });\n\n    // If the client disconnected before the subscription was created,\n    // unsubscribe immediately to avoid leaking the observable.\n    if (request.signal.aborted) {\n      subscription.unsubscribe();\n    }\n  })().catch(async (error) => {\n    logError(error);\n    await closeStream();\n  });\n\n  request.signal.addEventListener(\"abort\", () => {\n    subscription?.unsubscribe();\n  });\n\n  return new Response(stream.readable, {\n    status: 200,\n    headers: {\n      \"Content-Type\": \"text/event-stream\",\n      \"Cache-Control\": \"no-cache\",\n      Connection: \"keep-alive\",\n    },\n  });\n}\n\nfunction summarizeEvent(event: BaseEvent): Record<string, unknown> {\n  const e = event as any;\n  const summary: Record<string, unknown> = {};\n\n  if (e.messageId) summary.messageId = e.messageId;\n  if (e.toolCallId) summary.toolCallId = e.toolCallId;\n  if (e.toolCallName) summary.toolCallName = e.toolCallName;\n  if (e.role) summary.role = e.role;\n  if (e.delta != null && typeof e.delta === \"string\")\n    summary.deltaLength = e.delta.length;\n  if (e.snapshot && typeof e.snapshot === \"object\")\n    summary.snapshotKeys = Object.keys(e.snapshot);\n  if (e.delta && Array.isArray(e.delta))\n    summary.operationCount = e.delta.length;\n  if (e.threadId) summary.threadId = e.threadId;\n  if (e.runId) summary.runId = e.runId;\n  if (e.message) summary.message = e.message;\n  if (e.code) summary.code = e.code;\n  if (e.stepName) summary.stepName = e.stepName;\n\n  return summary;\n}\n"],"mappings":"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"}

package/dist/v2/runtime/handlers/shared/sse-response.mjs

@@ -1,13 +1,18 @@
 import "reflect-metadata";
+import { createLogger } from "../../../../lib/logger.mjs";
 import telemetry from "../../telemetry/telemetry-client.mjs";
 import { EventEncoder } from "@ag-ui/encoder";
 
 //#region src/v2/runtime/handlers/shared/sse-response.ts
-function createSseEventResponse({ request, observableFactory }) {
+function createSseEventResponse({ request, observableFactory, debug, logger }) {
 	const stream = new TransformStream();
 	const writer = stream.writable.getWriter();
 	const encoder = new EventEncoder();
 	let streamClosed = false;
+	const debugLogger = debug?.enabled ? logger ?? createLogger({
+		level: "debug",
+		component: "copilotkit-debug"
+	}) : void 0;
 	const closeStream = async () => {
 		if (!streamClosed) try {
 			await writer.close();
@@ -27,9 +32,21 @@ function createSseEventResponse({ request, observableFactory }) {
 	(async () => {
 		const observable = await observableFactory();
 		telemetry.capture("oss.runtime.agent_execution_stream_started", {});
+		if (debug?.lifecycle) debugLogger.debug("SSE stream opened");
+		let eventCount = 0;
+		let loggedEventCount = 0;
 		subscription = observable.subscribe({
 			next: async (event) => {
 				if (!request.signal.aborted && !streamClosed) try {
+					eventCount++;
+					if (debug?.events) {
+						loggedEventCount++;
+						if (debug.verbose) debugLogger.debug({ event }, "Event emitted");
+						else debugLogger.debug({
+							type: event.type,
+							...summarizeEvent(event)
+						}, "Event emitted");
+					}
 					await writer.write(encoder.encode(event));
 				} catch (error) {
 					if (error instanceof Error && error.name === "AbortError") streamClosed = true;
@@ -37,11 +54,16 @@ function createSseEventResponse({ request, observableFactory }) {
 			},
 			error: async (error) => {
 				telemetry.capture("oss.runtime.agent_execution_stream_errored", { error: error instanceof Error ? error.message : String(error) });
+				if (debug?.lifecycle) debugLogger.debug({ error: error instanceof Error ? error.message : String(error) }, "SSE stream errored");
 				logError(error);
 				await closeStream();
 			},
 			complete: async () => {
 				telemetry.capture("oss.runtime.agent_execution_stream_ended", {});
+				if (debug?.lifecycle) debugLogger.debug({
+					eventCount,
+					loggedEventCount
+				}, "SSE stream completed");
 				await closeStream();
 			}
 		});
@@ -62,6 +84,23 @@ function createSseEventResponse({ request, observableFactory }) {
 		}
 	});
 }
+function summarizeEvent(event) {
+	const e = event;
+	const summary = {};
+	if (e.messageId) summary.messageId = e.messageId;
+	if (e.toolCallId) summary.toolCallId = e.toolCallId;
+	if (e.toolCallName) summary.toolCallName = e.toolCallName;
+	if (e.role) summary.role = e.role;
+	if (e.delta != null && typeof e.delta === "string") summary.deltaLength = e.delta.length;
+	if (e.snapshot && typeof e.snapshot === "object") summary.snapshotKeys = Object.keys(e.snapshot);
+	if (e.delta && Array.isArray(e.delta)) summary.operationCount = e.delta.length;
+	if (e.threadId) summary.threadId = e.threadId;
+	if (e.runId) summary.runId = e.runId;
+	if (e.message) summary.message = e.message;
+	if (e.code) summary.code = e.code;
+	if (e.stepName) summary.stepName = e.stepName;
+	return summary;
+}
 
 //#endregion
 export { createSseEventResponse };

package/dist/v2/runtime/handlers/shared/sse-response.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sse-response.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-response.ts"],"sourcesContent":["import { BaseEvent } from \"@ag-ui/client\";\nimport { EventEncoder } from \"@ag-ui/encoder\";\nimport { Observable, Subscription } from \"rxjs\";\nimport { telemetry } from \"../../telemetry\";\n\ninterface CreateSseEventResponseParams {\n  request: Request;\n  observableFactory: () =>\n    | Promise<Observable<BaseEvent>>\n    | Observable<BaseEvent>;\n}\n\nexport function createSseEventResponse({\n  request,\n  observableFactory,\n}: CreateSseEventResponseParams): Response {\n  const stream = new TransformStream();\n  const writer = stream.writable.getWriter();\n  const encoder = new EventEncoder();\n  let streamClosed = false;\n\n  const closeStream = async () => {\n    if (!streamClosed) {\n      try {\n        await writer.close();\n        streamClosed = true;\n      } catch {\n        // Stream already closed.\n      }\n    }\n  };\n\n  const logError = (error: unknown) => {\n    console.error(\"Error running agent:\", error);\n    console.error(\n      \"Error stack:\",\n      error instanceof Error ? error.stack : \"No stack trace\",\n    );\n    console.error(\"Error details:\", {\n      name: error instanceof Error ? error.name : \"Unknown\",\n      message: error instanceof Error ? error.message : String(error),\n      cause: error instanceof Error ? error.cause : undefined,\n    });\n  };\n\n  let subscription: Subscription | undefined;\n\n  (async () => {\n    const observable = await observableFactory();\n\n    telemetry.capture(\"oss.runtime.agent_execution_stream_started\", {});\n\n    subscription = observable.subscribe({\n      next: async (event) => {\n        if (!request.signal.aborted && !streamClosed) {\n          try {\n            await writer.write(encoder.encode(event));\n          } catch (error) {\n            if (error instanceof Error && error.name === \"AbortError\") {\n              streamClosed = true;\n            }\n          }\n        }\n      },\n      error: async (error) => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_errored\", {\n          error: error instanceof Error ? error.message : String(error),\n        });\n        logError(error);\n        await closeStream();\n      },\n      complete: async () => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_ended\", {});\n        await closeStream();\n      },\n    });\n\n    // If the client disconnected before the subscription was created,\n    // unsubscribe immediately to avoid leaking the observable.\n    if (request.signal.aborted) {\n      subscription.unsubscribe();\n    }\n  })().catch(async (error) => {\n    logError(error);\n    await closeStream();\n  });\n\n  request.signal.addEventListener(\"abort\", () => {\n    subscription?.unsubscribe();\n  });\n\n  return new Response(stream.readable, {\n    status: 200,\n    headers: {\n      \"Content-Type\": \"text/event-stream\",\n      \"Cache-Control\": \"no-cache\",\n      Connection: \"keep-alive\",\n    },\n  });\n}\n"],"mappings":";;;;;AAYA,SAAgB,uBAAuB,EACrC,SACA,qBACyC;CACzC,MAAM,SAAS,IAAI,iBAAiB;CACpC,MAAM,SAAS,OAAO,SAAS,WAAW;CAC1C,MAAM,UAAU,IAAI,cAAc;CAClC,IAAI,eAAe;CAEnB,MAAM,cAAc,YAAY;AAC9B,MAAI,CAAC,aACH,KAAI;AACF,SAAM,OAAO,OAAO;AACpB,kBAAe;UACT;;CAMZ,MAAM,YAAY,UAAmB;AACnC,UAAQ,MAAM,wBAAwB,MAAM;AAC5C,UAAQ,MACN,gBACA,iBAAiB,QAAQ,MAAM,QAAQ,iBACxC;AACD,UAAQ,MAAM,kBAAkB;GAC9B,MAAM,iBAAiB,QAAQ,MAAM,OAAO;GAC5C,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GAC/D,OAAO,iBAAiB,QAAQ,MAAM,QAAQ;GAC/C,CAAC;;CAGJ,IAAI;AAEJ,EAAC,YAAY;EACX,MAAM,aAAa,MAAM,mBAAmB;AAE5C,YAAU,QAAQ,8CAA8C,EAAE,CAAC;AAEnE,iBAAe,WAAW,UAAU;GAClC,MAAM,OAAO,UAAU;AACrB,QAAI,CAAC,QAAQ,OAAO,WAAW,CAAC,aAC9B,KAAI;AACF,WAAM,OAAO,MAAM,QAAQ,OAAO,MAAM,CAAC;aAClC,OAAO;AACd,SAAI,iBAAiB,SAAS,MAAM,SAAS,aAC3C,gBAAe;;;GAKvB,OAAO,OAAO,UAAU;AACtB,cAAU,QAAQ,8CAA8C,EAC9D,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EAC9D,CAAC;AACF,aAAS,MAAM;AACf,UAAM,aAAa;;GAErB,UAAU,YAAY;AACpB,cAAU,QAAQ,4CAA4C,EAAE,CAAC;AACjE,UAAM,aAAa;;GAEtB,CAAC;AAIF,MAAI,QAAQ,OAAO,QACjB,cAAa,aAAa;KAE1B,CAAC,MAAM,OAAO,UAAU;AAC1B,WAAS,MAAM;AACf,QAAM,aAAa;GACnB;AAEF,SAAQ,OAAO,iBAAiB,eAAe;AAC7C,gBAAc,aAAa;GAC3B;AAEF,QAAO,IAAI,SAAS,OAAO,UAAU;EACnC,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,iBAAiB;GACjB,YAAY;GACb;EACF,CAAC"}
+{"version":3,"file":"sse-response.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-response.ts"],"sourcesContent":["import { BaseEvent } from \"@ag-ui/client\";\nimport { EventEncoder } from \"@ag-ui/encoder\";\nimport { Observable, Subscription } from \"rxjs\";\nimport { ResolvedDebugConfig } from \"@copilotkit/shared\";\nimport {\n  createLogger,\n  type CopilotRuntimeLogger,\n} from \"../../../../lib/logger\";\nimport { telemetry } from \"../../telemetry\";\n\ninterface CreateSseEventResponseParams {\n  request: Request;\n  observableFactory: () =>\n    | Promise<Observable<BaseEvent>>\n    | Observable<BaseEvent>;\n  debug?: ResolvedDebugConfig;\n  /** Pre-created logger instance to avoid creating a new pino logger per request. */\n  logger?: CopilotRuntimeLogger;\n}\n\nexport function createSseEventResponse({\n  request,\n  observableFactory,\n  debug,\n  logger,\n}: CreateSseEventResponseParams): Response {\n  const stream = new TransformStream();\n  const writer = stream.writable.getWriter();\n  const encoder = new EventEncoder();\n  let streamClosed = false;\n\n  const debugLogger = debug?.enabled\n    ? (logger ??\n      createLogger({ level: \"debug\", component: \"copilotkit-debug\" }))\n    : undefined;\n\n  const closeStream = async () => {\n    if (!streamClosed) {\n      try {\n        await writer.close();\n        streamClosed = true;\n      } catch {\n        // Stream already closed.\n      }\n    }\n  };\n\n  const logError = (error: unknown) => {\n    console.error(\"Error running agent:\", error);\n    console.error(\n      \"Error stack:\",\n      error instanceof Error ? error.stack : \"No stack trace\",\n    );\n    console.error(\"Error details:\", {\n      name: error instanceof Error ? error.name : \"Unknown\",\n      message: error instanceof Error ? error.message : String(error),\n      cause: error instanceof Error ? error.cause : undefined,\n    });\n  };\n\n  let subscription: Subscription | undefined;\n\n  (async () => {\n    const observable = await observableFactory();\n\n    telemetry.capture(\"oss.runtime.agent_execution_stream_started\", {});\n\n    if (debug?.lifecycle) {\n      debugLogger!.debug(\"SSE stream opened\");\n    }\n\n    let eventCount = 0;\n    let loggedEventCount = 0;\n\n    subscription = observable.subscribe({\n      next: async (event) => {\n        if (!request.signal.aborted && !streamClosed) {\n          try {\n            eventCount++;\n            if (debug?.events) {\n              loggedEventCount++;\n              if (debug.verbose) {\n                debugLogger!.debug({ event }, \"Event emitted\");\n              } else {\n                debugLogger!.debug(\n                  { type: event.type, ...summarizeEvent(event) },\n                  \"Event emitted\",\n                );\n              }\n            }\n            await writer.write(encoder.encode(event));\n          } catch (error) {\n            if (error instanceof Error && error.name === \"AbortError\") {\n              streamClosed = true;\n            }\n          }\n        }\n      },\n      error: async (error) => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_errored\", {\n          error: error instanceof Error ? error.message : String(error),\n        });\n        if (debug?.lifecycle) {\n          debugLogger!.debug(\n            { error: error instanceof Error ? error.message : String(error) },\n            \"SSE stream errored\",\n          );\n        }\n        logError(error);\n        await closeStream();\n      },\n      complete: async () => {\n        telemetry.capture(\"oss.runtime.agent_execution_stream_ended\", {});\n        if (debug?.lifecycle) {\n          debugLogger!.debug(\n            { eventCount, loggedEventCount },\n            \"SSE stream completed\",\n          );\n        }\n        await closeStream();\n      },\n    });\n\n    // If the client disconnected before the subscription was created,\n    // unsubscribe immediately to avoid leaking the observable.\n    if (request.signal.aborted) {\n      subscription.unsubscribe();\n    }\n  })().catch(async (error) => {\n    logError(error);\n    await closeStream();\n  });\n\n  request.signal.addEventListener(\"abort\", () => {\n    subscription?.unsubscribe();\n  });\n\n  return new Response(stream.readable, {\n    status: 200,\n    headers: {\n      \"Content-Type\": \"text/event-stream\",\n      \"Cache-Control\": \"no-cache\",\n      Connection: \"keep-alive\",\n    },\n  });\n}\n\nfunction summarizeEvent(event: BaseEvent): Record<string, unknown> {\n  const e = event as any;\n  const summary: Record<string, unknown> = {};\n\n  if (e.messageId) summary.messageId = e.messageId;\n  if (e.toolCallId) summary.toolCallId = e.toolCallId;\n  if (e.toolCallName) summary.toolCallName = e.toolCallName;\n  if (e.role) summary.role = e.role;\n  if (e.delta != null && typeof e.delta === \"string\")\n    summary.deltaLength = e.delta.length;\n  if (e.snapshot && typeof e.snapshot === \"object\")\n    summary.snapshotKeys = Object.keys(e.snapshot);\n  if (e.delta && Array.isArray(e.delta))\n    summary.operationCount = e.delta.length;\n  if (e.threadId) summary.threadId = e.threadId;\n  if (e.runId) summary.runId = e.runId;\n  if (e.message) summary.message = e.message;\n  if (e.code) summary.code = e.code;\n  if (e.stepName) summary.stepName = e.stepName;\n\n  return summary;\n}\n"],"mappings":"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"}

package/dist/v2/runtime/handlers/sse/run.cjs

@@ -2,9 +2,11 @@ require("reflect-metadata");
 const require_sse_response = require('../shared/sse-response.cjs');
 
 //#region src/v2/runtime/handlers/sse/run.ts
-function handleSseRun({ runtime, request, agent, input }) {
+function handleSseRun({ runtime, request, agent, input, debug, logger }) {
 	return require_sse_response.createSseEventResponse({
 		request,
+		debug,
+		logger,
 		observableFactory: () => runtime.runner.run({
 			threadId: input.threadId,
 			agent,

package/dist/v2/runtime/handlers/sse/run.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.cjs","names":["createSseEventResponse"],"sources":["../../../../../src/v2/runtime/handlers/sse/run.ts"],"sourcesContent":["import { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { CopilotRuntimeLike } from \"../../core/runtime\";\nimport { createSseEventResponse } from \"../shared/sse-response\";\n\ninterface HandleSseRunParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n  input: RunAgentInput;\n}\n\nexport function handleSseRun({\n  runtime,\n  request,\n  agent,\n  input,\n}: HandleSseRunParams): Response {\n  return createSseEventResponse({\n    request,\n    observableFactory: () =>\n      runtime.runner.run({\n        threadId: input.threadId,\n        agent,\n        input,\n      }),\n  });\n}\n"],"mappings":";;;;AAWA,SAAgB,aAAa,EAC3B,SACA,SACA,OACA,SAC+B;AAC/B,QAAOA,4CAAuB;EAC5B;EACA,yBACE,QAAQ,OAAO,IAAI;GACjB,UAAU,MAAM;GAChB;GACA;GACD,CAAC;EACL,CAAC"}
+{"version":3,"file":"run.cjs","names":["createSseEventResponse"],"sources":["../../../../../src/v2/runtime/handlers/sse/run.ts"],"sourcesContent":["import { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { ResolvedDebugConfig } from \"@copilotkit/shared\";\nimport { type CopilotRuntimeLogger } from \"../../../../lib/logger\";\nimport { CopilotRuntimeLike } from \"../../core/runtime\";\nimport { createSseEventResponse } from \"../shared/sse-response\";\n\ninterface HandleSseRunParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n  input: RunAgentInput;\n  debug?: ResolvedDebugConfig;\n  /** Pre-created logger instance to avoid creating a new pino logger per request. */\n  logger?: CopilotRuntimeLogger;\n}\n\nexport function handleSseRun({\n  runtime,\n  request,\n  agent,\n  input,\n  debug,\n  logger,\n}: HandleSseRunParams): Response {\n  return createSseEventResponse({\n    request,\n    debug,\n    logger,\n    observableFactory: () =>\n      runtime.runner.run({\n        threadId: input.threadId,\n        agent,\n        input,\n      }),\n  });\n}\n"],"mappings":";;;;AAgBA,SAAgB,aAAa,EAC3B,SACA,SACA,OACA,OACA,OACA,UAC+B;AAC/B,QAAOA,4CAAuB;EAC5B;EACA;EACA;EACA,yBACE,QAAQ,OAAO,IAAI;GACjB,UAAU,MAAM;GAChB;GACA;GACD,CAAC;EACL,CAAC"}

package/dist/v2/runtime/handlers/sse/run.mjs

@@ -2,9 +2,11 @@ import "reflect-metadata";
 import { createSseEventResponse } from "../shared/sse-response.mjs";
 
 //#region src/v2/runtime/handlers/sse/run.ts
-function handleSseRun({ runtime, request, agent, input }) {
+function handleSseRun({ runtime, request, agent, input, debug, logger }) {
 	return createSseEventResponse({
 		request,
+		debug,
+		logger,
 		observableFactory: () => runtime.runner.run({
 			threadId: input.threadId,
 			agent,

package/dist/v2/runtime/handlers/sse/run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/sse/run.ts"],"sourcesContent":["import { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { CopilotRuntimeLike } from \"../../core/runtime\";\nimport { createSseEventResponse } from \"../shared/sse-response\";\n\ninterface HandleSseRunParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n  input: RunAgentInput;\n}\n\nexport function handleSseRun({\n  runtime,\n  request,\n  agent,\n  input,\n}: HandleSseRunParams): Response {\n  return createSseEventResponse({\n    request,\n    observableFactory: () =>\n      runtime.runner.run({\n        threadId: input.threadId,\n        agent,\n        input,\n      }),\n  });\n}\n"],"mappings":";;;;AAWA,SAAgB,aAAa,EAC3B,SACA,SACA,OACA,SAC+B;AAC/B,QAAO,uBAAuB;EAC5B;EACA,yBACE,QAAQ,OAAO,IAAI;GACjB,UAAU,MAAM;GAChB;GACA;GACD,CAAC;EACL,CAAC"}
+{"version":3,"file":"run.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/sse/run.ts"],"sourcesContent":["import { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { ResolvedDebugConfig } from \"@copilotkit/shared\";\nimport { type CopilotRuntimeLogger } from \"../../../../lib/logger\";\nimport { CopilotRuntimeLike } from \"../../core/runtime\";\nimport { createSseEventResponse } from \"../shared/sse-response\";\n\ninterface HandleSseRunParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n  input: RunAgentInput;\n  debug?: ResolvedDebugConfig;\n  /** Pre-created logger instance to avoid creating a new pino logger per request. */\n  logger?: CopilotRuntimeLogger;\n}\n\nexport function handleSseRun({\n  runtime,\n  request,\n  agent,\n  input,\n  debug,\n  logger,\n}: HandleSseRunParams): Response {\n  return createSseEventResponse({\n    request,\n    debug,\n    logger,\n    observableFactory: () =>\n      runtime.runner.run({\n        threadId: input.threadId,\n        agent,\n        input,\n      }),\n  });\n}\n"],"mappings":";;;;AAgBA,SAAgB,aAAa,EAC3B,SACA,SACA,OACA,OACA,OACA,UAC+B;AAC/B,QAAO,uBAAuB;EAC5B;EACA;EACA;EACA,yBACE,QAAQ,OAAO,IAAI;GACjB,UAAU,MAAM;GAChB;GACA;GACD,CAAC;EACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/runtime",
-  "version": "1.55.3-canary.1776260990",
+  "version": "1.56.0",
   "private": false,
   "keywords": [
     "ai",
@@ -76,11 +76,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@ag-ui/a2ui-middleware": "0.0.4",
+    "@ag-ui/a2ui-middleware": "0.0.5",
     "@ag-ui/client": "0.0.52",
     "@ag-ui/core": "0.0.52",
     "@ag-ui/encoder": "0.0.52",
-    "@ag-ui/langgraph": "0.0.27",
+    "@ag-ui/langgraph": "0.0.29",
     "@ag-ui/mcp-apps-middleware": "0.0.3",
     "@ai-sdk/anthropic": "^3.0.49",
     "@ai-sdk/google": "^3.0.33",
@@ -115,7 +115,7 @@
     "uuid": "^10.0.0",
     "ws": "^8.18.0",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.55.3-canary.1776260990"
+    "@copilotkit/shared": "1.56.0"
   },
   "devDependencies": {
     "@copilotkit/aimock": "^1.10.0",

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

@@ -23,6 +23,7 @@ import {
   getZodParameters,
   type PartialBy,
   isTelemetryDisabled,
+  type DebugConfig,
 } from "@copilotkit/shared";
 import type { RunAgentInput } from "@ag-ui/core";
 import { aguiToGQL } from "../../graphql/message-conversion/agui-to-gql";
@@ -292,6 +293,19 @@ export interface CopilotRuntimeConstructorParams_BASE<
 
   onStopGeneration?: OnStopGenerationHandler;
 
+  /**
+   * Enable debug logging for the runtime event pipeline.
+   * Pass `true` for full output, or an object for granular control:
+   *
+   * ```ts
+   * const runtime = new CopilotRuntime({
+   *   debug: true,
+   *   // or: debug: { events: true, lifecycle: true, verbose: false }
+   * });
+   * ```
+   */
+  debug?: DebugConfig;
+
   // /** Optional transcription service for audio processing. */
   // transcriptionService?: CopilotRuntimeOptionsVNext["transcriptionService"];
   // /** Optional *before* middleware – callback function or webhook URL. */
@@ -377,6 +391,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       agents: mergedAgents,
       runner,
       licenseToken: params?.licenseToken,
+      debug: params?.debug,
       // TODO: add support for transcriptionService from CopilotRuntimeOptionsVNext once it is ready
       // transcriptionService: params?.transcriptionService,
 

package/src/v2/runtime/__tests__/debug-sse-response.test.ts

@@ -0,0 +1,302 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Observable, of } from "rxjs";
+import { BaseEvent, EventType } from "@ag-ui/client";
+import type { ResolvedDebugConfig } from "@copilotkit/shared";
+
+const mockDebug = vi.fn();
+
+vi.mock("pino", () => ({
+  default: vi.fn(() => ({
+    child: vi.fn(() => ({ debug: mockDebug })),
+    debug: mockDebug,
+  })),
+}));
+
+vi.mock("pino-pretty", () => ({ default: vi.fn() }));
+
+vi.mock("../../telemetry", () => ({
+  telemetry: { capture: vi.fn() },
+}));
+
+import pino from "pino";
+import { createSseEventResponse } from "../handlers/shared/sse-response";
+
+function createTestObservable(events: BaseEvent[]): Observable<BaseEvent> {
+  return of(...events);
+}
+
+function createMockRequest(): Request {
+  return new Request("https://example.com/agent/test/run", {
+    method: "POST",
+  });
+}
+
+async function drainResponse(response: Response): Promise<void> {
+  const reader = response.body!.getReader();
+  while (true) {
+    const { done } = await reader.read();
+    if (done) break;
+  }
+}
+
+describe("createSseEventResponse debug logging", () => {
+  beforeEach(() => {
+    mockDebug.mockClear();
+  });
+
+  it("does not log when debug is undefined", async () => {
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([]),
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).not.toHaveBeenCalled();
+  });
+
+  it("logs lifecycle message on stream open", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: "t-1",
+      runId: "r-1",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith("SSE stream opened");
+  });
+
+  it("logs lifecycle completion with total eventCount even when event logging is off", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.RUN_STARTED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith(
+      { eventCount: 2, loggedEventCount: 0 },
+      "SSE stream completed",
+    );
+  });
+
+  it("logs lifecycle completion with matching eventCount and loggedEventCount when events enabled", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.RUN_STARTED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith(
+      { eventCount: 2, loggedEventCount: 2 },
+      "SSE stream completed",
+    );
+  });
+
+  it("logs events in summary mode when verbose is false", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: false,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: "msg-1",
+      role: "assistant",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls.length).toBeGreaterThanOrEqual(1);
+
+    const [summaryArg] = eventEmittedCalls[0];
+    expect(summaryArg).toHaveProperty("type", EventType.TEXT_MESSAGE_START);
+    expect(summaryArg).toHaveProperty("messageId", "msg-1");
+    // In summary mode the full event object is not passed directly
+    expect(summaryArg).not.toHaveProperty("event");
+  });
+
+  it("logs events in verbose mode with full event object", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: true,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: "msg-1",
+      role: "assistant",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls.length).toBeGreaterThanOrEqual(1);
+
+    const [verboseArg] = eventEmittedCalls[0];
+    expect(verboseArg).toHaveProperty("event");
+    expect(verboseArg.event).toEqual(event);
+  });
+
+  it("uses a pre-created logger instead of calling createLogger when one is provided", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const externalDebug = vi.fn();
+    const externalLogger = { debug: externalDebug } as any;
+
+    // Clear the pino mock call count so we can assert it was NOT called again
+    const pinoMock = pino as unknown as ReturnType<typeof vi.fn>;
+    pinoMock.mockClear();
+
+    const event: BaseEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: "t-1",
+      runId: "r-1",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+      logger: externalLogger,
+    });
+
+    await drainResponse(response);
+
+    // The external logger should have been used for lifecycle messages
+    expect(externalDebug).toHaveBeenCalledWith("SSE stream opened");
+    expect(externalDebug).toHaveBeenCalledWith(
+      { eventCount: 1, loggedEventCount: 0 },
+      "SSE stream completed",
+    );
+
+    // pino should NOT have been called – the pre-created logger was reused
+    expect(pinoMock).not.toHaveBeenCalled();
+  });
+
+  it("does not log events when events is disabled", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: "msg-1",
+        role: "assistant",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls).toHaveLength(0);
+
+    // Only lifecycle calls should be present
+    const lifecycleCalls = mockDebug.mock.calls.filter(
+      (call) =>
+        call[call.length - 1] === "SSE stream opened" ||
+        call[call.length - 1] === "SSE stream completed",
+    );
+    expect(lifecycleCalls.length).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/v2/runtime/core/runtime.ts

@@ -9,6 +9,11 @@ import {
   createLicenseChecker,
   type LicenseChecker,
 } from "@copilotkit/license-verifier";
+import {
+  type ResolvedDebugConfig,
+  resolveDebugConfig,
+  type DebugConfig,
+} from "@copilotkit/shared";
 import { AbstractAgent } from "@ag-ui/client";
 import type { MCPClientConfig } from "@ag-ui/mcp-apps-middleware";
 import { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware";
@@ -17,6 +22,7 @@ import type {
   BeforeRequestMiddleware,
   AfterRequestMiddleware,
 } from "./middleware";
+import { createLogger, type CopilotRuntimeLogger } from "../../../lib/logger";
 import { TranscriptionService } from "../transcription-service/transcription-service";
 import { AgentRunner } from "../runner/agent-runner";
 import { InMemoryAgentRunner } from "../runner/in-memory";
@@ -128,6 +134,8 @@ interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
   afterRequestMiddleware?: AfterRequestMiddleware;
   /** Signed license token for server-side feature verification. Falls back to COPILOTKIT_LICENSE_TOKEN env var. */
   licenseToken?: string;
+  /** Enable debug logging for the event pipeline. */
+  debug?: DebugConfig;
 }
 
 export interface CopilotRuntimeUser {
@@ -181,6 +189,8 @@ export interface CopilotRuntimeLike {
   identifyUser?: IdentifyUserCallback;
   mode: RuntimeMode;
   licenseChecker?: LicenseChecker;
+  debug: ResolvedDebugConfig;
+  debugLogger?: CopilotRuntimeLogger;
 }
 
 export interface CopilotSseRuntimeLike extends CopilotRuntimeLike {
@@ -208,6 +218,8 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
   public mcpApps: CopilotRuntimeOptions["mcpApps"];
   public openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"];
   public licenseChecker?: LicenseChecker;
+  public debug: ResolvedDebugConfig;
+  public debugLogger?: CopilotRuntimeLogger;
 
   abstract readonly intelligence?: CopilotKitIntelligence;
   abstract readonly mode: RuntimeMode;
@@ -231,6 +243,13 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
     this.mcpApps = mcpApps;
     this.openGenerativeUI = openGenerativeUI;
     this.runner = runner;
+    this.debug = resolveDebugConfig(options.debug);
+    if (this.debug.enabled) {
+      this.debugLogger = createLogger({
+        level: "debug",
+        component: "copilotkit-debug",
+      });
+    }
   }
 }
 
@@ -387,4 +406,12 @@ export class CopilotRuntime implements CopilotRuntimeLike {
   get licenseChecker() {
     return this.delegate.licenseChecker;
   }
+
+  get debug(): ResolvedDebugConfig {
+    return this.delegate.debug;
+  }
+
+  get debugLogger(): CopilotRuntimeLogger | undefined {
+    return this.delegate.debugLogger;
+  }
 }

package/src/v2/runtime/handlers/handle-run.ts

@@ -55,6 +55,13 @@ export async function handleRunAgent({
     agent.setState(input.state);
     agent.threadId = input.threadId;
 
+    if (runtime.debug?.lifecycle && runtime.debugLogger) {
+      runtime.debugLogger.debug(
+        { agentName: agentId, threadId: input.threadId },
+        "Agent run started",
+      );
+    }
+
     if (isIntelligenceRuntime(runtime)) {
       return handleIntelligenceRun({
         runtime,
@@ -65,7 +72,14 @@ export async function handleRunAgent({
       });
     }
 
-    return handleSseRun({ runtime, request, agent, input });
+    return handleSseRun({
+      runtime,
+      request,
+      agent,
+      input,
+      debug: runtime.debug,
+      logger: runtime.debugLogger,
+    });
   } catch (error) {
     console.error("Error running agent:", error);
     console.error(