@copilotkit/runtime 1.71.0 → 1.71.2

package/skills/runtime/references/built-in-agent-factory-modes.md

@@ -1,232 +0,0 @@
-BuiltInAgent Factory Modes — cookbook for TanStack AI, AI SDK, and custom AG-UI factories.
-
-## The AgentFactoryContext
-
-```typescript
-// packages/runtime/src/agent/index.ts
-export interface AgentFactoryContext {
-  input: RunAgentInput; // messages, tools, forwardedProps, context
-  abortController: AbortController; // prefer abortSignal
-  abortSignal: AbortSignal; // pass to AI SDK / fetch / custom
-}
-```
-
-Rule of thumb:
-
-- Prefer `abortSignal` for AI SDK, fetch, custom backends.
-- Use `abortController` for TanStack AI (its `chat()` takes the controller, not the signal).
-- NEVER call `ctx.abortController.abort()` inside the factory — use
-  `agent.abortRun()` from outside.
-
-## TanStack AI factory (preferred)
-
-```typescript
-import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
-import { chat } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-new BuiltInAgent({
-  type: "tanstack",
-  factory: ({ input, abortController }) => {
-    const { messages, systemPrompts } = convertInputToTanStackAI(input);
-    systemPrompts.unshift("You are a helpful assistant.");
-    return chat({
-      adapter: openaiText("gpt-4o"),
-      messages,
-      systemPrompts,
-      tools: [
-        /* TanStack AI toolDefinition()s */
-      ],
-      abortController,
-    });
-  },
-});
-```
-
-### TanStack AI + forwardedProps
-
-```typescript
-new BuiltInAgent({
-  type: "tanstack",
-  factory: ({ input, abortController }) => {
-    const { messages, systemPrompts } = convertInputToTanStackAI(input);
-    const fwd = input.forwardedProps as
-      | { model?: string; temperature?: number }
-      | undefined;
-    return chat({
-      adapter: openaiText(fwd?.model ?? "gpt-4o"),
-      messages,
-      systemPrompts,
-      modelOptions: { temperature: fwd?.temperature ?? 0.2 },
-      abortController,
-    });
-  },
-});
-```
-
-## AI SDK factory (use when reasoning events are required)
-
-```typescript
-import {
-  BuiltInAgent,
-  convertMessagesToVercelAISDKMessages,
-  convertToolsToVercelAITools,
-} from "@copilotkit/runtime/v2";
-import { streamText, stepCountIs } from "ai";
-import { openai } from "@ai-sdk/openai";
-
-new BuiltInAgent({
-  type: "aisdk",
-  factory: ({ input, abortSignal }) => {
-    const messages = convertMessagesToVercelAISDKMessages(input.messages, {
-      forwardSystemMessages: true,
-    });
-    const tools = convertToolsToVercelAITools(input.tools);
-    return streamText({
-      model: openai("gpt-4o"),
-      messages,
-      tools,
-      abortSignal,
-      stopWhen: stepCountIs(5),
-    });
-  },
-});
-```
-
-The `BuiltInAgentAISDKFactoryConfig` contract requires an object with a `fullStream`
-async iterable — this is exactly what `streamText()` returns.
-
-## AI SDK + reasoning (Anthropic thinking)
-
-```typescript
-import { anthropic } from "@ai-sdk/anthropic";
-import { streamText } from "ai";
-import {
-  BuiltInAgent,
-  convertMessagesToVercelAISDKMessages,
-} from "@copilotkit/runtime/v2";
-
-new BuiltInAgent({
-  type: "aisdk",
-  factory: ({ input, abortSignal }) =>
-    streamText({
-      model: anthropic("claude-sonnet-4-6"),
-      messages: convertMessagesToVercelAISDKMessages(input.messages),
-      providerOptions: {
-        anthropic: { thinking: { type: "enabled", budgetTokens: 10000 } },
-      },
-      abortSignal,
-    }),
-});
-```
-
-TanStack AI silently drops reasoning events — only AI SDK surfaces them.
-
-## Custom factory (raw AG-UI events)
-
-```typescript
-import { BuiltInAgent } from "@copilotkit/runtime/v2";
-import type { BaseEvent } from "@ag-ui/client";
-import { EventType } from "@ag-ui/client";
-
-new BuiltInAgent({
-  type: "custom",
-  factory: async function* ({ input, abortSignal }): AsyncIterable<BaseEvent> {
-    // Check abortSignal.aborted on every iteration — agent.abortRun() signals
-    // cancellation via this flag, but the generator must consult it to stop yielding.
-    if (abortSignal.aborted) return;
-
-    const messageId = crypto.randomUUID();
-    yield {
-      type: EventType.TEXT_MESSAGE_START,
-      messageId,
-      role: "assistant",
-    } as any;
-
-    for (const delta of ["Hello", ", ", "world."]) {
-      if (abortSignal.aborted) return; // honor cancellation between yields
-      yield {
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId,
-        delta,
-      } as any;
-    }
-
-    yield { type: EventType.TEXT_MESSAGE_END, messageId } as any;
-  },
-});
-```
-
-A custom factory that never checks `abortSignal.aborted` (or registers an
-`addEventListener("abort", …)` handler to break its loop) is non-cancellable —
-`agent.abortRun()` will flip the flag but the generator will keep yielding until it
-exhausts its own source. Pass `abortSignal` through to any underlying `fetch` /
-streaming API as well so the upstream request is torn down.
-
-## Manual state-tool wiring (Factory Mode only)
-
-Simple Mode auto-injects `AGUISendStateSnapshot` / `AGUISendStateDelta`. In Factory Mode
-you must register them by hand for shared-state updates to reach the LLM. The AI SDK
-factory works out of the box because `defineTool` output adapts through
-`convertToolDefinitionsToVercelAITools`:
-
-```typescript
-import {
-  BuiltInAgent,
-  convertMessagesToVercelAISDKMessages,
-  convertToolDefinitionsToVercelAITools,
-  defineTool,
-} from "@copilotkit/runtime/v2";
-import { streamText } from "ai";
-import { openai } from "@ai-sdk/openai";
-import { z } from "zod";
-
-const sendStateSnapshot = defineTool({
-  name: "AGUISendStateSnapshot",
-  description: "Replace the entire application state with a new snapshot",
-  parameters: z.object({
-    snapshot: z.any().describe("The complete new state object"),
-  }),
-  execute: async ({ snapshot }) => ({ success: true, snapshot }),
-});
-const sendStateDelta = defineTool({
-  name: "AGUISendStateDelta",
-  description:
-    "Apply incremental updates to application state using JSON Patch operations",
-  // MUST mirror the Simple-Mode auto-injected schema (src/agent/index.ts:1140-1176)
-  // or the frontend's state handler won't recognize the payload.
-  parameters: z.object({
-    delta: z
-      .array(
-        z.object({
-          op: z.enum(["add", "replace", "remove"]),
-          path: z.string(),
-          value: z.any().optional(),
-        }),
-      )
-      .describe("Array of JSON Patch operations"),
-  }),
-  execute: async ({ delta }) => ({ success: true, delta }),
-});
-
-new BuiltInAgent({
-  type: "aisdk",
-  factory: ({ input, abortSignal }) =>
-    streamText({
-      model: openai("gpt-4o"),
-      messages: convertMessagesToVercelAISDKMessages(input.messages),
-      tools: convertToolDefinitionsToVercelAITools([
-        sendStateSnapshot,
-        sendStateDelta,
-      ]),
-      abortSignal,
-    }),
-});
-```
-
-For TanStack AI factories, `defineTool` output is NOT a TanStack tool — passing it to
-`chat({ tools })` does not work. Either switch to the AI SDK factory above, or redefine
-the tools with `toolDefinition()` from `@tanstack/ai`.
-
-Source: `packages/runtime/src/agent/index.ts`,
-`docs/content/docs/integrations/built-in-agent/custom-agent.mdx`.

package/skills/runtime/references/built-in-agent-helper-utilities.md

@@ -1,123 +0,0 @@
-BuiltInAgent helper utilities — exported from `@copilotkit/runtime/v2`.
-
-## convertInputToTanStackAI
-
-```typescript
-import { convertInputToTanStackAI } from "@copilotkit/runtime/v2";
-
-// signature (simplified):
-// convertInputToTanStackAI(input: RunAgentInput): {
-//   messages: TanStackAIMessage[];
-//   systemPrompts: string[];
-// }
-```
-
-Converts the AG-UI `RunAgentInput` into TanStack AI's `chat()` inputs. System messages in
-the input are collected into the `systemPrompts` array (not the `messages` array). Unshift
-your own system prompt onto `systemPrompts` before calling `chat()`:
-
-```typescript
-const { messages, systemPrompts } = convertInputToTanStackAI(input);
-systemPrompts.unshift("You are a helpful assistant.");
-return chat({ adapter, messages, systemPrompts, abortController });
-```
-
-Source: `packages/runtime/src/agent/converters/tanstack.ts:156`.
-
-## convertMessagesToVercelAISDKMessages
-
-```typescript
-import { convertMessagesToVercelAISDKMessages } from "@copilotkit/runtime/v2";
-
-// signature:
-// convertMessagesToVercelAISDKMessages(
-//   messages: Message[],
-//   options?: { forwardSystemMessages?: boolean; forwardDeveloperMessages?: boolean }
-// ): ModelMessage[]
-```
-
-Converts AG-UI `Message[]` to the Vercel AI SDK's `ModelMessage[]`. Handles multimodal
-content (text, image, audio/video/document, and legacy `binary`). By default drops
-`role: "system"` and `role: "developer"` messages — set the options to opt in.
-
-```typescript
-const messages = convertMessagesToVercelAISDKMessages(input.messages, {
-  forwardSystemMessages: true,
-});
-```
-
-Source: `packages/runtime/src/agent/index.ts:435`.
-
-## convertToolsToVercelAITools
-
-```typescript
-import { convertToolsToVercelAITools } from "@copilotkit/runtime/v2";
-
-// signature:
-// convertToolsToVercelAITools(tools: RunAgentInput["tools"]): ToolSet
-```
-
-Converts AG-UI `input.tools` (tools registered on the frontend — their parameters are plain
-JSON Schema) into the AI SDK's `ToolSet`. Throws `Invalid JSON schema for tool ${name}`
-when a tool's parameters aren't a JSON schema object. The resulting tools have no
-`execute` — the AI SDK emits tool-call events and the frontend handles them.
-
-```typescript
-const tools = convertToolsToVercelAITools(input.tools);
-return streamText({ model, messages, tools, abortSignal });
-```
-
-Source: `packages/runtime/src/agent/index.ts:599`.
-
-## convertToolDefinitionsToVercelAITools
-
-```typescript
-import { convertToolDefinitionsToVercelAITools } from "@copilotkit/runtime/v2";
-
-// signature:
-// convertToolDefinitionsToVercelAITools(tools: ToolDefinition[]): ToolSet
-```
-
-Converts server-side `ToolDefinition[]` (Standard Schema V1 parameters + `execute`
-function) into an AI SDK `ToolSet`. Zod schemas pass through directly; non-Zod Standard
-Schema V1 parameters (Valibot, ArkType, ...) are converted to JSON Schema via
-`schemaToJsonSchema` and wrapped with `jsonSchema()` from `ai`.
-
-```typescript
-import { defineTool } from "@copilotkit/runtime/v2";
-import { z } from "zod";
-
-const searchTool = defineTool({
-  name: "search",
-  description: "Search the web.",
-  parameters: z.object({ query: z.string() }),
-  execute: async ({ query }) => ({ results: [] }),
-});
-
-const tools = convertToolDefinitionsToVercelAITools([searchTool]);
-return streamText({ model, messages, tools, abortSignal });
-```
-
-Source: `packages/runtime/src/agent/index.ts:633`.
-
-## resolveModel
-
-```typescript
-import { resolveModel } from "@copilotkit/runtime/v2";
-
-// signature:
-// resolveModel(spec: ModelSpecifier, apiKey?: string): LanguageModel
-```
-
-Resolves a `"provider/model"` (or `"provider:model"`) string to a `LanguageModel`. If
-`spec` is already a `LanguageModel`, it's returned as-is. Throws
-`Invalid model string "..."` when the provider separator is missing.
-
-Supported providers: `openai`, `anthropic`, `google`/`gemini`/`google-gemini`, `vertex`.
-Unknown providers throw `Unknown provider "..." in "...". Supported: openai, anthropic, google (gemini).`
-
-```typescript
-const model = resolveModel("openai/gpt-4o", process.env.OPENAI_API_KEY);
-```
-
-Source: `packages/runtime/src/agent/index.ts:176-249`.

package/skills/runtime/references/built-in-agent-model-identifiers.md

@@ -1,58 +0,0 @@
-BuiltInAgent model identifiers — the full set of `"provider/model"` strings that
-`resolveModel` accepts out of the box.
-
-## Shape
-
-`"provider/model"` or `"provider:model"` — both separators are normalized. Case-insensitive on the provider segment.
-
-```typescript
-new BuiltInAgent({ model: "openai/gpt-4o" });
-new BuiltInAgent({ model: "anthropic:claude-sonnet-4-6" });
-```
-
-## Supported providers
-
-| Provider                              | Env var             | Notes                              |
-| ------------------------------------- | ------------------- | ---------------------------------- |
-| `openai`                              | `OPENAI_API_KEY`    | Lazily creates `@ai-sdk/openai`    |
-| `anthropic`                           | `ANTHROPIC_API_KEY` | Lazily creates `@ai-sdk/anthropic` |
-| `google` / `gemini` / `google-gemini` | `GOOGLE_API_KEY`    | `@ai-sdk/google` under the hood    |
-| `vertex`                              | (GCP auth)          | `@ai-sdk/google-vertex`            |
-
-Pass `apiKey` on the constructor to override env vars.
-
-## Pinned identifiers in the union type
-
-These are the concrete strings typed in `BuiltInAgentModel`:
-
-```
-openai/gpt-5            openai/gpt-5-mini
-openai/gpt-4.1          openai/gpt-4.1-mini        openai/gpt-4.1-nano
-openai/gpt-4o           openai/gpt-4o-mini
-openai/o3               openai/o3-mini             openai/o4-mini
-
-anthropic/claude-sonnet-4-6   anthropic/claude-sonnet-4-5
-anthropic/claude-opus-4-8     anthropic/claude-haiku-4-5
-
-google/gemini-2.5-pro   google/gemini-2.5-flash    google/gemini-2.5-flash-lite
-```
-
-Any other valid model id is still accepted — the type is
-`BuiltInAgentModel = "openai/gpt-5" | ... | (string & {})`, and the AI SDK provider will
-accept any id it knows about. The pinned union is for autocomplete, not an exhaustive allowlist.
-
-## Passing a LanguageModel instance directly
-
-Instead of a string, pass a pre-configured `LanguageModel`:
-
-```typescript
-import { BuiltInAgent } from "@copilotkit/runtime/v2";
-import { createOpenAI } from "@ai-sdk/openai";
-
-const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
-new BuiltInAgent({ model: openai("gpt-4o") });
-```
-
-This bypasses `resolveModel` entirely.
-
-Source: `packages/runtime/src/agent/index.ts:82-109, 176-249`.