@copilotkit/runtime 1.55.2 → 1.55.3-canary.1776243725

package/src/v2/runtime/__tests__/get-runtime-info.test.ts

@@ -1,7 +1,7 @@
 import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
 import { CopilotRuntime } from "../core/runtime";
 import { TranscriptionService } from "../transcription-service/transcription-service";
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import type { AbstractAgent } from "@ag-ui/client";
 
 // Mock transcription service
@@ -117,6 +117,139 @@ describe("handleGetRuntimeInfo", () => {
     expect(data.a2uiEnabled).toBe(true);
   });
 
+  it("should include capabilities when agent implements getCapabilities", async () => {
+    const mockCapabilities = {
+      tools: { supported: true, clientProvided: true },
+      transport: { streaming: true },
+    };
+
+    const mockAgent = {
+      description: "Capable agent",
+      constructor: { name: "CapableAgent" },
+      getCapabilities: async () => mockCapabilities,
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        capableAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(data.agents.capableAgent.capabilities).toEqual(mockCapabilities);
+  });
+
+  it("should omit capabilities when agent does not implement getCapabilities", async () => {
+    const mockAgent = {
+      description: "Basic agent",
+      constructor: { name: "BasicAgent" },
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        basicAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(data.agents.basicAgent.capabilities).toBeUndefined();
+  });
+
+  it("should include empty capabilities object when getCapabilities returns {}", async () => {
+    const mockAgent = {
+      description: "Empty caps agent",
+      constructor: { name: "EmptyCapsAgent" },
+      getCapabilities: async () => ({}),
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        emptyAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    // {} is truthy, so it should be included in the response
+    expect(data.agents.emptyAgent.capabilities).toEqual({});
+  });
+
+  it("should isolate per-agent getCapabilities failures and log a warning", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const failingAgent = {
+      description: "Failing agent",
+      constructor: { name: "FailingAgent" },
+      getCapabilities: async () => {
+        throw new Error("capability fetch failed");
+      },
+    };
+
+    const healthyAgent = {
+      description: "Healthy agent",
+      constructor: { name: "HealthyAgent" },
+      getCapabilities: async () => ({
+        tools: { supported: true },
+      }),
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        failing: failingAgent as unknown as AbstractAgent,
+        healthy: healthyAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    // Failing agent should still appear but without capabilities
+    expect(data.agents.failing).toEqual({
+      name: "failing",
+      description: "Failing agent",
+      className: "FailingAgent",
+    });
+    expect(data.agents.failing.capabilities).toBeUndefined();
+
+    // Healthy agent should have its capabilities
+    expect(data.agents.healthy.capabilities).toEqual({
+      tools: { supported: true },
+    });
+
+    // Error should be logged, not silently swallowed
+    expect(warnSpy).toHaveBeenCalledWith(
+      'Failed to fetch capabilities for agent "failing":',
+      "capability fetch failed",
+    );
+
+    warnSpy.mockRestore();
+  });
+
   it("should return 500 error when runtime.agents throws an error", async () => {
     const runtime = {
       get agents(): Record<string, AbstractAgent> {

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

@@ -56,9 +56,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. */

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;
     }

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(