@copilotkit/runtime 1.55.3 → 1.56.0

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";
@@ -56,9 +62,70 @@ interface CopilotRuntimeMiddlewares {
   openGenerativeUI?: OpenGenerativeUIConfig;
 }
 
+/**
+ * Context passed to agent factory functions for per-request agent resolution.
+ */
+export interface AgentFactoryContext {
+  /** The incoming HTTP request. */
+  request: Request;
+}
+
+/**
+ * A function that dynamically creates agents on a per-request basis.
+ * Useful for multi-tenant scenarios or request-scoped agent configuration.
+ */
+export type AgentsFactory = (
+  ctx: AgentFactoryContext,
+) => MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+
+/**
+ * Agents can be provided as:
+ * - A static record of agents
+ * - A Promise that resolves to a record of agents
+ * - A factory function that receives request context and returns agents (or a Promise of agents)
+ */
+export type AgentsConfig =
+  | MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>
+  | AgentsFactory;
+
+/**
+ * Resolve an AgentsConfig value to a concrete record of agents.
+ * If the config is a factory function, it is called with the given request context.
+ * Otherwise it is awaited directly (static record or Promise).
+ */
+export async function resolveAgents(
+  agents: AgentsConfig,
+  request?: Request,
+): Promise<Record<string, AbstractAgent>> {
+  if (typeof agents === "function") {
+    if (!request) {
+      throw new Error(
+        "Agent factory function requires a request context, but none was provided.",
+      );
+    }
+    return agents({ request });
+  }
+  return agents;
+}
+
 interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
-  /** Map of available agents (loaded lazily is fine). */
-  agents: MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+  /**
+   * Map of available agents, or a factory function for per-request agent resolution.
+   *
+   * Static record:
+   * ```ts
+   * agents: { support: new SupportAgent(), technical: new TechnicalAgent() }
+   * ```
+   *
+   * Factory function (called per-request):
+   * ```ts
+   * agents: ({ request }) => {
+   *   const tenantId = request.headers.get("x-tenant-id");
+   *   return { default: createAgentForTenant(tenantId) };
+   * }
+   * ```
+   */
+  agents: AgentsConfig;
   /** Optional transcription service for audio processing. */
   transcriptionService?: TranscriptionService;
   /** Optional *before* middleware – callback function or webhook URL. */
@@ -67,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 {
@@ -120,6 +189,8 @@ export interface CopilotRuntimeLike {
   identifyUser?: IdentifyUserCallback;
   mode: RuntimeMode;
   licenseChecker?: LicenseChecker;
+  debug: ResolvedDebugConfig;
+  debugLogger?: CopilotRuntimeLogger;
 }
 
 export interface CopilotSseRuntimeLike extends CopilotRuntimeLike {
@@ -147,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;
@@ -170,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",
+      });
+    }
   }
 }
 
@@ -326,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/get-runtime-info.ts

@@ -1,4 +1,9 @@
-import { CopilotRuntimeLike, isIntelligenceRuntime } from "../core/runtime";
+import type { AgentCapabilities } from "@ag-ui/core";
+import {
+  CopilotRuntimeLike,
+  isIntelligenceRuntime,
+  resolveAgents,
+} from "../core/runtime";
 import {
   AgentDescription,
   RuntimeInfo,
@@ -26,22 +31,42 @@ interface HandleGetRuntimeInfoParameters {
 
 export async function handleGetRuntimeInfo({
   runtime,
+  request,
 }: HandleGetRuntimeInfoParameters) {
   try {
-    const agents = await runtime.agents;
+    const agents = await resolveAgents(runtime.agents, request);
+
+    const agentEntries = await Promise.all(
+      Object.entries(agents).map(async ([name, agent]) => {
+        let capabilities: AgentCapabilities | undefined;
+        try {
+          capabilities = agent.getCapabilities
+            ? await agent.getCapabilities()
+            : undefined;
+        } catch (error) {
+          // Per-agent isolation: a single agent failing to report capabilities
+          // must not take down the entire /info endpoint.
+          console.warn(
+            `Failed to fetch capabilities for agent "${name}":`,
+            error instanceof Error ? error.message : error,
+          );
+          capabilities = undefined;
+        }
 
-    const agentsDict = Object.entries(agents).reduce(
-      (acc, [name, agent]) => {
-        acc[name] = {
+        const description: AgentDescription = {
           name,
           description: agent.description,
           className: agent.constructor.name,
+          ...(capabilities ? { capabilities } : {}),
         };
-        return acc;
-      },
-      {} as Record<string, AgentDescription>,
+
+        return [name, description] as const;
+      }),
     );
 
+    const agentsDict: Record<string, AgentDescription> =
+      Object.fromEntries(agentEntries);
+
     const runtimeInfo: RuntimeInfo = {
       version: VERSION,
       agents: agentsDict,

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

@@ -29,7 +29,7 @@ export async function handleConnectAgent({
   });
 
   try {
-    const agent = await cloneAgentForRequest(runtime, agentId);
+    const agent = await cloneAgentForRequest(runtime, agentId, request);
     if (agent instanceof Response) {
       return agent;
     }

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

@@ -30,7 +30,7 @@ export async function handleRunAgent({
   });
 
   try {
-    const agent = await cloneAgentForRequest(runtime, agentId);
+    const agent = await cloneAgentForRequest(runtime, agentId, request);
     if (agent instanceof Response) {
       return agent;
     }
@@ -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(

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

@@ -1,4 +1,5 @@
 import type { CopilotRuntimeLike } from "../core/runtime";
+import { resolveAgents } from "../core/runtime";
 import { EventType } from "@ag-ui/client";
 
 interface StopAgentParameters {
@@ -15,7 +16,7 @@ export async function handleStopAgent({
   threadId,
 }: StopAgentParameters) {
   try {
-    const agents = await runtime.agents;
+    const agents = await resolveAgents(runtime.agents, request);
 
     if (!agents[agentId]) {
       return new Response(

package/src/v2/runtime/handlers/intelligence/thread-names.ts

@@ -99,7 +99,7 @@ async function runTitleGenerationAttempt(params: {
   prompt: string;
 }): Promise<string | null> {
   const { runtime, request, agentId, threadId, prompt } = params;
-  const agent = await cloneAgentForRequest(runtime, agentId);
+  const agent = await cloneAgentForRequest(runtime, agentId, request);
   if (isHandlerResponse(agent)) {
     logger.warn(
       { agentId, threadId },

package/src/v2/runtime/handlers/shared/agent-utils.ts

@@ -5,7 +5,7 @@ import {
 } from "@ag-ui/client";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
 import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
-import { CopilotRuntimeLike } from "../../core/runtime";
+import { CopilotRuntimeLike, resolveAgents } from "../../core/runtime";
 import { OpenGenerativeUIMiddleware } from "../../open-generative-ui-middleware";
 import { extractForwardableHeaders } from "../header-utils";
 import { logger } from "@copilotkit/shared";
@@ -28,8 +28,9 @@ export interface ConnectRequestBody extends RunAgentInput {
 export async function cloneAgentForRequest(
   runtime: CopilotRuntimeLike,
   agentId: string,
+  request?: Request,
 ): Promise<AbstractAgent | Response> {
-  const agents = await runtime.agents;
+  const agents = await resolveAgents(runtime.agents, request);
 
   if (!agents[agentId]) {
     return new Response(

package/src/v2/runtime/handlers/shared/sse-response.ts

@@ -1,6 +1,11 @@
 import { BaseEvent } from "@ag-ui/client";
 import { EventEncoder } from "@ag-ui/encoder";
 import { Observable, Subscription } from "rxjs";
+import { ResolvedDebugConfig } from "@copilotkit/shared";
+import {
+  createLogger,
+  type CopilotRuntimeLogger,
+} from "../../../../lib/logger";
 import { telemetry } from "../../telemetry";
 
 interface CreateSseEventResponseParams {
@@ -8,17 +13,27 @@ interface CreateSseEventResponseParams {
   observableFactory: () =>
     | Promise<Observable<BaseEvent>>
     | Observable<BaseEvent>;
+  debug?: ResolvedDebugConfig;
+  /** Pre-created logger instance to avoid creating a new pino logger per request. */
+  logger?: CopilotRuntimeLogger;
 }
 
 export function createSseEventResponse({
   request,
   observableFactory,
+  debug,
+  logger,
 }: CreateSseEventResponseParams): Response {
   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" }))
+    : undefined;
+
   const closeStream = async () => {
     if (!streamClosed) {
       try {
@@ -50,10 +65,29 @@ export function createSseEventResponse({
 
     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") {
@@ -66,11 +100,23 @@ export function createSseEventResponse({
         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();
       },
     });
@@ -98,3 +144,26 @@ export function createSseEventResponse({
     },
   });
 }
+
+function summarizeEvent(event: BaseEvent): Record<string, unknown> {
+  const e = event as any;
+  const summary: Record<string, unknown> = {};
+
+  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;
+}

package/src/v2/runtime/handlers/sse/run.ts

@@ -1,4 +1,6 @@
 import { AbstractAgent, RunAgentInput } from "@ag-ui/client";
+import { ResolvedDebugConfig } from "@copilotkit/shared";
+import { type CopilotRuntimeLogger } from "../../../../lib/logger";
 import { CopilotRuntimeLike } from "../../core/runtime";
 import { createSseEventResponse } from "../shared/sse-response";
 
@@ -7,6 +9,9 @@ interface HandleSseRunParams {
   request: Request;
   agent: AbstractAgent;
   input: RunAgentInput;
+  debug?: ResolvedDebugConfig;
+  /** Pre-created logger instance to avoid creating a new pino logger per request. */
+  logger?: CopilotRuntimeLogger;
 }
 
 export function handleSseRun({
@@ -14,9 +19,13 @@ export function handleSseRun({
   request,
   agent,
   input,
+  debug,
+  logger,
 }: HandleSseRunParams): Response {
   return createSseEventResponse({
     request,
+    debug,
+    logger,
     observableFactory: () =>
       runtime.runner.run({
         threadId: input.threadId,