@copilotkit/runtime 1.57.3 → 1.58.0-canary.thread-id-propagation

package/skills/runtime/references/wiring-external-agents.md

@@ -0,0 +1,348 @@
+# CopilotKit — Wire External Agent Frameworks
+
+`CopilotRuntime` takes any `AbstractAgent` subclass. Every framework below ships a
+ready-made subclass you construct and hand to `agents: { ... }`.
+
+| Framework                 | Package                     | Construct                                                                                                                    |
+| ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Mastra                    | `@ag-ui/mastra`             | `MastraAgent.getLocalAgents({ mastra, resourceId? })` (record; `resourceId` required only when the agent has Memory enabled) |
+| LangGraph                 | `@ag-ui/langgraph`          | `new LangGraphAgent({ deploymentUrl, graphId })`                                                                             |
+| CrewAI Crews              | `@ag-ui/crewai`             | `new CrewAIAgent({ url })`                                                                                                   |
+| CrewAI Flows              | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| PydanticAI                | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| Google ADK                | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| LlamaIndex                | `@ag-ui/llamaindex`         | `new LlamaIndexAgent({ url: ".../run" })` (`/run` suffix)                                                                    |
+| Agno                      | `@ag-ui/agno`               | `new AgnoAgent({ url: ".../agui" })` (`/agui` suffix)                                                                        |
+| AWS Strands               | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| Microsoft Agent Framework | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| AG2                       | `@ag-ui/client` (HttpAgent) | `new HttpAgent({ url })`                                                                                                     |
+| A2A                       | `@ag-ui/a2a`                | `new A2AAgent({ a2aClient })` (pre-built `A2AClient`, not a URL)                                                             |
+
+MCP Apps is NOT a framework — it's a runtime middleware:
+`new CopilotRuntime({ agents, mcpApps: { servers: [...] } })`. See
+[wiring-mcp-apps-middleware.md](wiring-mcp-apps-middleware.md).
+
+## Setup
+
+Generic shape for every framework:
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { HttpAgent } from "@ag-ui/client";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new HttpAgent({ url: process.env.AGENT_URL! }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Core Patterns
+
+### Mastra (local agents)
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { MastraAgent } from "@ag-ui/mastra";
+import { mastra } from "./mastra";
+
+const runtime = new CopilotRuntime({
+  // resourceId scopes Mastra Memory's working-memory buckets. Required when
+  // the Mastra agent has Memory enabled (the runtime always supplies a
+  // threadId, so Memory-enabled agents effectively always need it). Agents
+  // without Memory can omit it — `examples/integrations/mastra` calls
+  // `getLocalAgents({ mastra })` with no resourceId. See wiring-mastra.md.
+  agents: MastraAgent.getLocalAgents({ mastra, resourceId: "default" }),
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+See [wiring-mastra.md](wiring-mastra.md).
+
+### LangGraph
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { LangGraphAgent } from "@ag-ui/langgraph";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    supportAgent: new LangGraphAgent({
+      deploymentUrl: process.env.LANGGRAPH_URL!,
+      graphId: "support",
+      langsmithApiKey: process.env.LANGSMITH_API_KEY,
+    }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+See [wiring-langgraph.md](wiring-langgraph.md).
+
+### Multi-framework single runtime
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { LangGraphAgent } from "@ag-ui/langgraph";
+import { CrewAIAgent } from "@ag-ui/crewai";
+import { HttpAgent } from "@ag-ui/client";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    research: new LangGraphAgent({
+      deploymentUrl: process.env.LANGGRAPH_URL!,
+      graphId: "research",
+    }),
+    writer: new CrewAIAgent({ url: process.env.CREWAI_URL! }),
+    translator: new HttpAgent({ url: process.env.PYDANTIC_AI_URL! }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+### MCP Apps (runtime middleware, not an agent)
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+  BuiltInAgent,
+} from "@copilotkit/runtime/v2";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new BuiltInAgent({ model: "openai/gpt-4o" }),
+  },
+  mcpApps: {
+    servers: [{ type: "http", url: "https://mcp.example.com/mcp" }],
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Common Mistakes
+
+### HIGH Using runtimeUrl as the agent URL
+
+Wrong:
+
+```typescript
+import { LangGraphAgent } from "@ag-ui/langgraph";
+
+new LangGraphAgent({ deploymentUrl: "/api/copilotkit", graphId: "agent" });
+```
+
+Correct:
+
+```typescript
+new LangGraphAgent({
+  deploymentUrl: process.env.LANGGRAPH_URL!,
+  graphId: "agent",
+});
+```
+
+External agents take their own upstream URL — the framework's server or deployment. The
+CopilotKit runtime URL (`/api/copilotkit`) is the frontend↔runtime hop, not the
+runtime↔agent hop.
+
+Source: `docs/integrations/langgraph/quickstart.mdx:355`.
+
+### HIGH Wrapping MastraAgent.getLocalAgents in a key
+
+Wrong:
+
+```typescript
+new CopilotRuntime({
+  agents: {
+    mastra: MastraAgent.getLocalAgents({ mastra, resourceId: "default" }),
+  },
+});
+```
+
+Correct:
+
+```typescript
+new CopilotRuntime({
+  agents: MastraAgent.getLocalAgents({ mastra, resourceId: "default" }),
+});
+```
+
+`MastraAgent.getLocalAgents` already returns a `Record<string, AbstractAgent>`. Wrapping
+it turns the record into a nested value on one key, which fails the registry's shape check.
+
+Source: `docs/integrations/mastra/quickstart.mdx:213-220`.
+
+### MEDIUM Missing /run or /agui suffix on LlamaIndex / Agno
+
+Wrong:
+
+```typescript
+import { LlamaIndexAgent } from "@ag-ui/llamaindex";
+import { AgnoAgent } from "@ag-ui/agno";
+
+new LlamaIndexAgent({ url: "http://localhost:8000" });
+new AgnoAgent({ url: "http://localhost:8000" });
+```
+
+Correct:
+
+```typescript
+new LlamaIndexAgent({ url: "http://localhost:8000/run" });
+new AgnoAgent({ url: "http://localhost:8000/agui" });
+```
+
+LlamaIndex requires a `/run` suffix, Agno requires `/agui`. The generic HttpAgent fallback
+would 404 without these.
+
+Source: `docs/integrations/llamaindex/quickstart.mdx:258`;
+`docs/integrations/agno/quickstart.mdx:215`.
+
+### MEDIUM Passing a URL to A2AAgent instead of an A2AClient
+
+Wrong:
+
+```typescript
+import { A2AAgent } from "@ag-ui/a2a";
+
+new A2AAgent({ url: "https://a2a.example" } as any);
+```
+
+Correct:
+
+```typescript
+import { A2AAgent } from "@ag-ui/a2a";
+import { A2AClient } from "@a2a-js/sdk/client";
+
+const a2aClient = new A2AClient("https://a2a.example");
+new A2AAgent({ a2aClient });
+```
+
+`A2AAgent` expects a pre-built `A2AClient` instance — A2A has its own handshake that
+the client handles.
+
+Source: `examples/integrations/a2a-a2ui/app/api/copilotkit/[[...slug]]/route.tsx:12`.
+
+### HIGH Treating MCP Apps as an agent
+
+Wrong:
+
+```typescript
+new CopilotRuntime({
+  agents: {
+    mcpApps: new MCPAppsAgent({
+      /* ... */
+    } as any),
+  } as any,
+});
+```
+
+Correct:
+
+```typescript
+new CopilotRuntime({
+  agents: {
+    /* your real agents */
+  },
+  mcpApps: {
+    servers: [{ type: "http", url: "https://mcp.example.com/mcp" }],
+  },
+});
+```
+
+MCP Apps is runtime-level middleware auto-applied to all agents. Configure via
+`runtime.mcpApps`, not `agents`.
+
+Source: `packages/runtime/src/v2/runtime/core/runtime.ts:39-63`.
+
+### MEDIUM Passing a framework `client` instead of its Agent wrapper
+
+Wrong:
+
+```typescript
+import { mastraClient } from "./mastra"; // a Mastra client object
+
+new CopilotRuntime({
+  agents: { default: mastraClient as any },
+});
+```
+
+Correct:
+
+```typescript
+import { MastraAgent } from "@ag-ui/mastra";
+import { mastra } from "./mastra";
+
+new CopilotRuntime({
+  agents: MastraAgent.getLocalAgents({ mastra, resourceId: "default" }),
+});
+```
+
+`CopilotRuntime` expects `AbstractAgent` subclasses. Framework SDK clients are not
+AbstractAgent instances — always pass the `@ag-ui/<framework>` wrapper or `HttpAgent`.
+
+Source: `packages/runtime/src/v2/runtime/core/runtime.ts:111-128`.
+
+## References
+
+- [Mastra](wiring-mastra.md)
+- [LangGraph](wiring-langgraph.md)
+- [CrewAI Crews](wiring-crewai-crews.md)
+- [CrewAI Flows](wiring-crewai-flows.md)
+- [PydanticAI](wiring-pydantic-ai.md)
+- [Google ADK](wiring-adk.md)
+- [LlamaIndex](wiring-llamaindex.md)
+- [Agno](wiring-agno.md)
+- [AWS Strands](wiring-aws-strands.md)
+- [Microsoft Agent Framework](wiring-ms-agent-framework.md)
+- [AG2](wiring-ag2.md)
+- [A2A](wiring-a2a.md)
+- [MCP Apps middleware](wiring-mcp-apps-middleware.md)
+
+## See also
+
+- `copilotkit/setup-endpoint` — mount the runtime that fronts these agents
+- `copilotkit/built-in-agent` — alternative when you want an in-tree agent
+- `copilotkit/agent-runners` — runner choice is independent of framework

package/skills/runtime/references/wiring-langgraph.md

@@ -0,0 +1,50 @@
+LangGraph — wired via `@ag-ui/langgraph`. Supports LangGraph Platform deployments and
+self-hosted LangGraph servers.
+
+## Install
+
+```bash
+pnpm add @ag-ui/langgraph
+```
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { LangGraphAgent } from "@ag-ui/langgraph";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new LangGraphAgent({
+      deploymentUrl: process.env.LANGGRAPH_URL!,
+      graphId: "agent",
+      langsmithApiKey: process.env.LANGSMITH_API_KEY, // optional
+    }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Config fields
+
+| Field             | Notes                                                                 |
+| ----------------- | --------------------------------------------------------------------- |
+| `deploymentUrl`   | Base URL of the LangGraph Platform deployment (or self-hosted server) |
+| `graphId`         | The graph name registered with the deployment (e.g. `"agent"`)        |
+| `langsmithApiKey` | Optional — enables LangSmith tracing                                  |
+
+## Gotcha — `deploymentUrl` is NOT the CopilotKit runtime URL
+
+The most common mistake is setting `deploymentUrl` to `/api/copilotkit`. That is the
+frontend↔runtime URL, not the LangGraph server. Use the actual LangGraph deployment URL.
+
+Source: `docs/content/docs/integrations/langgraph/quickstart.mdx:355`.

package/skills/runtime/references/wiring-llamaindex.md

@@ -0,0 +1,39 @@
+LlamaIndex — wired via `@ag-ui/llamaindex`. Requires a `/run` URL suffix.
+
+## Install
+
+```bash
+pnpm add @ag-ui/llamaindex
+```
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { LlamaIndexAgent } from "@ag-ui/llamaindex";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new LlamaIndexAgent({
+      url: process.env.LLAMAINDEX_URL ?? "http://localhost:8000/run",
+    }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Gotcha — the `/run` suffix is mandatory
+
+LlamaIndex's AG-UI adapter mounts its workflow endpoint at `/run`. Pointing `url` at the
+server root (`http://localhost:8000`) returns 404. Always include `/run`.
+
+Source: `docs/content/docs/integrations/llamaindex/quickstart.mdx:258`.

package/skills/runtime/references/wiring-mastra.md

@@ -0,0 +1,70 @@
+Mastra — local-first TypeScript agent framework wired via `@ag-ui/mastra`.
+
+## Install
+
+```bash
+pnpm add @ag-ui/mastra
+# plus your Mastra SDK:
+pnpm add @mastra/core
+```
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { MastraAgent } from "@ag-ui/mastra";
+import { Mastra } from "@mastra/core";
+import { weatherAgent } from "./agents/weather"; // your Mastra agent
+
+const mastra = new Mastra({
+  agents: { weather: weatherAgent },
+});
+
+const runtime = new CopilotRuntime({
+  agents: MastraAgent.getLocalAgents({
+    mastra,
+    // Required ONLY when your Mastra agent has Memory enabled AND a threadId
+    // is supplied (the runtime always supplies a threadId, so Memory-enabled
+    // agents effectively always need this). Passing an empty string throws
+    // AGENT_MEMORY_MISSING_RESOURCE_ID on every turn. Agents without Memory
+    // can omit resourceId — e.g. the in-tree `examples/integrations/mastra`
+    // quickstart calls `MastraAgent.getLocalAgents({ mastra })` with no
+    // resourceId. Pick a stable per-user identifier in production; a literal
+    // "default" is fine as a placeholder for single-tenant demos.
+    resourceId: "default",
+  }),
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Remote Mastra server
+
+If Mastra is running as a separate HTTP service, the simplest wiring is the
+generic `HttpAgent` from `@ag-ui/client` — it speaks the AG-UI protocol that
+Mastra's HTTP server already emits:
+
+```typescript
+import { HttpAgent } from "@ag-ui/client";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    weather: new HttpAgent({ url: `${process.env.MASTRA_URL!}/weather` }),
+  },
+});
+```
+
+## Gotcha — do NOT wrap the record
+
+`getLocalAgents` already returns `Record<string, AbstractAgent>`. Wrapping it in a key
+(`{ mastra: getLocalAgents(...) }`) breaks the registry.
+
+Source: `docs/content/docs/integrations/mastra/quickstart.mdx:213-220`.

package/skills/runtime/references/wiring-mcp-apps-middleware.md

@@ -0,0 +1,68 @@
+MCP Apps — runtime-level middleware that auto-applies to all agents. NOT an agent.
+
+MCP Apps lets any agent in the runtime access tools from external MCP servers. It is
+configured on `CopilotRuntime` directly, not as an entry in `agents`.
+
+## Install
+
+MCP support is provided by the runtime directly — no extra package install for the
+middleware itself. Your MCP servers are separate services you point at.
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+  BuiltInAgent,
+} from "@copilotkit/runtime/v2";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new BuiltInAgent({ model: "openai/gpt-4o", maxSteps: 5 }),
+  },
+  mcpApps: {
+    servers: [
+      {
+        type: "http",
+        url: "https://mcp.example.com/mcp",
+      },
+      {
+        type: "http",
+        url: "https://another-mcp.example.com/mcp",
+        agentId: "default", // scope this server to one agent only
+      },
+    ],
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Per-agent scoping
+
+Each server entry accepts an optional `agentId`. When set, the server's tools are only
+exposed to that agent. Omit it to expose to all agents.
+
+## Gotcha — do NOT put MCP under agents
+
+```typescript
+// WRONG
+new CopilotRuntime({
+  agents: {
+    mcpApps: new MCPAppsAgent({
+      /* ... */
+    }),
+  } as any,
+});
+```
+
+There is no `MCPAppsAgent`. MCP Apps is runtime middleware and belongs on the top-level
+`CopilotRuntime` options.
+
+Source: `packages/runtime/src/v2/runtime/core/runtime.ts:39-63`.

package/skills/runtime/references/wiring-ms-agent-framework.md

@@ -0,0 +1,41 @@
+Microsoft Agent Framework — wired via the bare `HttpAgent` from `@ag-ui/client`.
+Both Python and .NET variants use the same HTTP bridge.
+
+## Install
+
+```bash
+pnpm add @ag-ui/client
+```
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { HttpAgent } from "@ag-ui/client";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new HttpAgent({
+      url: process.env.MS_AGENT_URL!, // Python or .NET AG-UI endpoint
+    }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Gotcha — pick the right endpoint path
+
+Microsoft Agent Framework ships both Python and .NET adapters. The AG-UI mount path
+depends on which adapter you chose and how you configured it — follow the framework's
+quickstart to find the exact URL. `HttpAgent` simply forwards.
+
+Source: `docs/content/docs/integrations/microsoft-agent-framework/quickstart.mdx`.

package/skills/runtime/references/wiring-pydantic-ai.md

@@ -0,0 +1,45 @@
+PydanticAI — wired via the bare `HttpAgent` from `@ag-ui/client`.
+
+## Install
+
+```bash
+pnpm add @ag-ui/client
+```
+
+## Minimal wire-up
+
+```typescript
+import {
+  CopilotRuntime,
+  createCopilotRuntimeHandler,
+} from "@copilotkit/runtime/v2";
+import { HttpAgent } from "@ag-ui/client";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    default: new HttpAgent({
+      url: process.env.PYDANTIC_AI_URL ?? "http://localhost:8000/",
+    }),
+  },
+});
+
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+export default { fetch: handler };
+```
+
+## Server side
+
+On the Python side, PydanticAI exposes an AG-UI-compliant endpoint via its built-in
+ASGI adapter. The URL you pass to `HttpAgent` is that endpoint (e.g. an FastAPI route
+that returns a streaming response of AG-UI events).
+
+## Gotcha — no suffix required
+
+Unlike LlamaIndex (`/run`) and Agno (`/agui`), PydanticAI does not mandate a specific
+sub-path. Whatever path your Python server mounts the AG-UI app at — use that.
+
+Source: `docs/content/docs/integrations/pydantic-ai/quickstart.mdx`.