@copilotkit/runtime 1.70.3 → 1.71.1

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

@@ -1,348 +0,0 @@
-# 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                 | `@copilotkit/runtime/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/client` (HttpAgent)     | `new HttpAgent({ 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 "@copilotkit/runtime/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 "@copilotkit/runtime/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 "@copilotkit/runtime/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 { HttpAgent } from "@ag-ui/client";
-
-new LlamaIndexAgent({ url: "http://localhost:8000" });
-new HttpAgent({ url: "http://localhost:8000" });
-```
-
-Correct:
-
-```typescript
-new LlamaIndexAgent({ url: "http://localhost:8000/run" });
-new HttpAgent({ 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

@@ -1,49 +0,0 @@
-LangGraph — wired via `@copilotkit/runtime/langgraph`. Supports LangGraph Platform
-deployments and self-hosted LangGraph servers.
-
-## Install
-
-`LangGraphAgent` (and `LangGraphHttpAgent` for self-hosted AG-UI LangGraph servers)
-ship with `@copilotkit/runtime` — no separate install needed.
-
-## Minimal wire-up
-
-```typescript
-import {
-  CopilotRuntime,
-  createCopilotRuntimeHandler,
-} from "@copilotkit/runtime/v2";
-import { LangGraphAgent } from "@copilotkit/runtime/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

@@ -1,39 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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

@@ -1,73 +0,0 @@
-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.
-
-Per-tool filtering belongs to `@ag-ui/mcp-apps-middleware`. The runtime currently pins
-version `0.0.3`, which does not support `includeTools` or `excludeTools`. Supplying either
-key raises a configuration error instead of silently ignoring it; use a compatible
-middleware release when that upstream policy contract is available.
-
-## 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

@@ -1,41 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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`.