# Use your own LLM backend (factory mode)

> Use BuiltInAgent's factory mode to bring your own AI SDK, TanStack AI, or custom LLM backend.

You have an LLM backend (AI SDK, TanStack AI, or your own HTTP API) and want a
CopilotKit chat on top of it. Factory mode runs your backend inside
`BuiltInAgent`. You provide a factory function that calls your backend.
CopilotKit turns the stream into AG-UI events, manages the run lifecycle, and
wires the agent into the runtime.

## When to use Simple Mode vs Factory Mode [#when-to-use-simple-mode-vs-factory-mode]

| | Simple Mode | Factory Mode |
|---|---|---|
| **Setup** | Minimal: pass a model string | You own the LLM call and stream |
| **Model resolution** | Built-in (`"openai/gpt-6-luna"`) | You set up the model yourself |
| **Tools, MCP, state tools** | Automatically wired | You wire them in your factory |
| **Backend support** | Vercel AI SDK only | Any backend: AI SDK, TanStack AI, or custom |
| **Best for** | Quick setup, standard use cases | Full control, non-standard backends |

<Callout type="info">
If simple mode does what you need, use simple mode. Use factory mode when you need
control that simple mode doesn't offer.
</Callout>

To write the whole agent yourself instead of a factory, extend AG-UI's
`AbstractAgent`. See [Write your own AG-UI agent](/vue/mastra/backend/custom-ag-ui-agent).

## Quick Start [#quick-start]

Pick your backend:

<Tabs items={["AI SDK", "TanStack AI", "Custom"]}>
<Tab value="AI SDK">
```typescript title="src/copilotkit.ts"
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
  convertMessagesToVercelAISDKMessages,
} from "@copilotkit/runtime/v2";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const agent = new BuiltInAgent({
  type: "aisdk",
  factory: ({ input, abortSignal }) =>
    streamText({
      model: openai("gpt-6-luna"),
      messages: convertMessagesToVercelAISDKMessages(input.messages),
      abortSignal,
    }),
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default handler;
```
</Tab>
<Tab value="TanStack AI">
```typescript title="src/copilotkit.ts"
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
  convertInputToTanStackAI,
} from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-6-luna"),
      messages,
      systemPrompts,
      abortController,
    });
  },
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default handler;
```
</Tab>
<Tab value="Custom">
```typescript title="src/copilotkit.ts"
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { EventType, type BaseEvent } from "@ag-ui/client";

const agent = new BuiltInAgent({
  type: "custom",
  factory: async function* ({ input, abortSignal }) {
    const response = await fetch("https://your-llm-api.com/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ messages: input.messages }),
      signal: abortSignal,
    });

    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    const messageId = crypto.randomUUID();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      yield {
        type: EventType.TEXT_MESSAGE_CHUNK,
        role: "assistant",
        messageId,
        delta: decoder.decode(value),
      } as BaseEvent;
    }
  },
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});
export default handler;
```
</Tab>
</Tabs>

The frontend setup is the same as [BuiltInAgent](/vue/mastra/quickstart): configure the
CopilotKit provider and add a chat component.

Open the chat and send a message. The reply streams in from your backend.

## How It Works [#how-it-works]

Factory mode accepts a config with two fields:

- **`type`:** which backend you're using: `"aisdk"`, `"tanstack"`, or `"custom"`
- **`factory`:** a function that receives the raw request and returns a backend-native stream

The factory receives an `BuiltInAgentFactoryContext` (from `@copilotkit/runtime/v2`):

```typescript
interface BuiltInAgentFactoryContext {
  learnedSkills: BuiltInAgentLearnedSkills; // catalog and read-only AI SDK tools, empty when disabled
  input: RunAgentInput;        // messages, tools, state, context, threadId, runId, forwardedProps
  abortController: AbortController;  // for TanStack AI (requires AbortController)
  abortSignal: AbortSignal;          // preferred for AI SDK, fetch, and custom backends
}
```

CopilotKit handles everything else: `RUN_STARTED` and `RUN_FINISHED` lifecycle events, stream-to-AG-UI conversion, error handling, and abort/cancellation. Your factory never needs to emit lifecycle events.

<Callout type="warn" title="Don't call `.abort()` on the controller you were handed">
`abortController` is passed in for backends like TanStack AI that require a full
`AbortController`. Hand it to them and let them own it. If you abort it inside the
factory, the stream stops, but CopilotKit does not run the teardown for the run.
To cancel a run, call `abortRun()` on the agent. For anything that accepts a
signal (the AI SDK, `fetch`, a custom backend), pass `abortSignal` instead.
</Callout>

The `runner: new InMemoryAgentRunner()` in the examples above is the persistence
backend that stores threads in process memory. To understand the runner
abstraction and how to swap in durable persistence, see
[AgentRunner & persistence](/vue/mastra/backend/agent-runner).

<Callout type="info" title="Using CopilotKit Intelligence? Replace runner with intelligence">
  Intelligence stores the threads and runs for you, so remove `runner` and pass
  `intelligence` (and `identifyUser`) to `CopilotRuntime` instead. The custom
  agent and its `factory` do not change. See
  [An existing runtime that already has a runner](/vue/mastra/intelligence/quickstart#an-existing-runtime-that-already-has-a-runner).
</Callout>

The factory can be async. Return a `Promise` if you need to do setup before streaming:

```typescript
factory: async ({ input, abortSignal }) => {
  const apiKey = await getApiKeyFromVault();
  return streamText({ model: openai("gpt-6-luna", { apiKey }), ... });
}
```

## Examples [#examples]

### With Tools [#with-tools]

<Tabs items={["AI SDK", "TanStack AI", "Custom"]}>
<Tab value="AI SDK">
```typescript title="src/copilotkit.ts"
import {
  BuiltInAgent,
  convertMessagesToVercelAISDKMessages,
  convertToolsToVercelAITools,
} from "@copilotkit/runtime/v2";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const agent = new BuiltInAgent({
  type: "aisdk",
  factory: ({ input, abortSignal }) => {
    const tools = convertToolsToVercelAITools(input.tools);
    return streamText({
      model: openai("gpt-6-luna"),
      messages: convertMessagesToVercelAISDKMessages(input.messages),
      tools,
      abortSignal,
    });
  },
});
```

`convertToolsToVercelAITools` converts frontend-defined tools into AI SDK's
`ToolSet` format automatically.
</Tab>
<Tab value="TanStack AI">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
import { chat, toolDefinition } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { z } from "zod";

const getWeather = toolDefinition({
  name: "getWeather",
  description: "Get the weather for a city",
  inputSchema: z.object({ city: z.string() }),
}).server(async ({ city }) => ({ temp: 72, city }));

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts, tools } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-6-luna"),
      messages,
      systemPrompts,
      tools: [...tools, getWeather],
      abortController,
    });
  },
});
```

`convertInputToTanStackAI` also returns the frontend-defined tools as `tools`.
Pass them to `chat()` with your server tools, or the model never sees them.
</Tab>
<Tab value="Custom">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { EventType, type BaseEvent } from "@ag-ui/client";

const agent = new BuiltInAgent({
  type: "custom",
  factory: async function* ({ input }) {
    const messageId = crypto.randomUUID();
    const toolCallId = crypto.randomUUID();

    // The LLM decides to call a tool
    yield {
      type: EventType.TOOL_CALL_START,
      parentMessageId: messageId,
      toolCallId,
      toolCallName: "getWeather",
    } as BaseEvent;

    yield {
      type: EventType.TOOL_CALL_ARGS,
      toolCallId,
      delta: JSON.stringify({ city: "San Francisco" }),
    } as BaseEvent;

    yield {
      type: EventType.TOOL_CALL_END,
      toolCallId,
    } as BaseEvent;

    // Execute the tool and return the result
    yield {
      type: EventType.TOOL_CALL_RESULT,
      role: "tool",
      messageId: crypto.randomUUID(),
      toolCallId,
      content: JSON.stringify({ temp: 72, city: "San Francisco" }),
    } as BaseEvent;

    // Text response after the tool call
    yield {
      type: EventType.TEXT_MESSAGE_CHUNK,
      role: "assistant",
      messageId,
      delta: "The weather in San Francisco is 72°F.",
    } as BaseEvent;
  },
});
```

With `type: "custom"`, you yield AG-UI events directly. See the [AG-UI event reference](https://docs.ag-ui.com/concepts/events) for all available event types.
</Tab>
</Tabs>

### With Reasoning (Thinking Models) [#with-reasoning-thinking-models]

<Tabs items={["AI SDK", "TanStack AI"]}>
<Tab value="AI SDK">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent, convertMessagesToVercelAISDKMessages } from "@copilotkit/runtime/v2";
import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new BuiltInAgent({
  type: "aisdk",
  factory: ({ input, abortSignal }) =>
    streamText({
      model: anthropic("claude-sonnet-4-6"),
      providerOptions: {
        anthropic: {
          thinking: { type: "adaptive" },
          // `effort` replaces the fixed token budget used by the older
          // `{ type: "enabled", budgetTokens }` form.
          effort: "high",
        },
      },
      messages: convertMessagesToVercelAISDKMessages(input.messages),
      abortSignal,
    }),
});
```

Reasoning events (`REASONING_START`, `REASONING_MESSAGE_CONTENT`, `REASONING_END`) are automatically extracted from the AI SDK stream.

<Callout type="info">
Pick the model with reasoning **visibility** in mind. Some Anthropic models return no reasoning text by default, so the events above arrive empty. See Anthropic's [extended thinking docs](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) for the `display` setting.
</Callout>

Using `BuiltInAgent` without a custom factory? The same options go through its `providerOptions`. See [Advanced Configuration](/advanced-configuration#provider-specific-options).
</Tab>
<Tab value="TanStack AI">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { anthropicText } from "@tanstack/ai-anthropic";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts } = convertInputToTanStackAI(input);
    return chat({
      adapter: anthropicText("claude-sonnet-4-6"),
      messages,
      systemPrompts,
      modelOptions: {
        thinking: { type: "adaptive", display: "summarized" },
      },
      abortController,
    });
  },
});
```

Reasoning chunks from the model arrive as `REASONING_*` events.
</Tab>
</Tabs>

### With System Prompt, Context, and State [#with-system-prompt-context-and-state]

<Tabs items={["AI SDK", "TanStack AI"]}>
<Tab value="AI SDK">
```typescript title="src/copilotkit.ts"
import {
  BuiltInAgent,
  convertMessagesToVercelAISDKMessages,
} from "@copilotkit/runtime/v2";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const agent = new BuiltInAgent({
  type: "aisdk",
  factory: ({ input, abortSignal }) => {
    const systemParts: string[] = ["You are a helpful assistant."];

    // Add context supplied by the frontend
    if (input.context?.length) {
      for (const ctx of input.context) {
        systemParts.push(`${ctx.description}:\n${ctx.value}`);
      }
    }

    // Add shared application state
    if (input.state && Object.keys(input.state).length > 0) {
      systemParts.push(
        `Application State:\n${JSON.stringify(input.state, null, 2)}`,
      );
    }

    const messages = convertMessagesToVercelAISDKMessages(input.messages);
    messages.unshift({ role: "system", content: systemParts.join("\n\n") });

    return streamText({
      model: openai("gpt-6-luna"),
      messages,
      abortSignal,
    });
  },
});
```
</Tab>
<Tab value="TanStack AI">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    // convertInputToTanStackAI automatically extracts system/developer messages,
    // context, and state into the systemPrompts array
    const { messages, systemPrompts } = convertInputToTanStackAI(input);

    // Add your own system prompt at the beginning
    systemPrompts.unshift("You are a helpful assistant.");

    return chat({
      adapter: openaiText("gpt-6-luna"),
      messages,
      systemPrompts,
      abortController,
    });
  },
});
```

`convertInputToTanStackAI` handles system/developer messages, `input.context`, and `input.state` automatically. Prepend your own prompt if needed.
</Tab>
</Tabs>

### With forwardedProps [#with-forwardedprops]

Use `forwardedProps` only for non-secret, browser-controlled preferences. Validate
each value against backend-owned limits before it affects execution. Never use
these properties for credentials, tenant identity, authorization, or unrestricted
model and provider selection.

<Tabs items={["AI SDK", "TanStack AI"]}>
<Tab value="AI SDK">
```typescript title="src/copilotkit.ts"
import {
  BuiltInAgent,
  convertMessagesToVercelAISDKMessages,
} from "@copilotkit/runtime/v2";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const agent = new BuiltInAgent({
  type: "aisdk",
  factory: ({ input, abortSignal }) => {
    const props = (input.forwardedProps ?? {}) as Record<string, unknown>;

    const model = props.model === "openai/gpt-6-luna"
      ? openai("gpt-6-luna")
      : openai("gpt-6-luna");

    const temperature =
      typeof props.temperature === "number" &&
      props.temperature >= 0 && props.temperature <= 1
        ? props.temperature
        : 0.7;

    return streamText({
      model,
      temperature,
      messages: convertMessagesToVercelAISDKMessages(input.messages),
      abortSignal,
    });
  },
});
```
</Tab>
<Tab value="TanStack AI">
```typescript title="src/copilotkit.ts"
import { BuiltInAgent, convertInputToTanStackAI } from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { anthropicText } from "@tanstack/ai-anthropic";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const props = (input.forwardedProps ?? {}) as Record<string, unknown>;
    const { messages, systemPrompts } = convertInputToTanStackAI(input);

    const adapter =
      props.model === "anthropic/claude-sonnet-4-6"
        ? anthropicText("claude-sonnet-4-6")
        : openaiText("gpt-6-luna");

    const modelOptions: Record<string, unknown> = {};
    if (
      typeof props.temperature === "number" &&
      props.temperature >= 0 && props.temperature <= 1
    )
      modelOptions.temperature = props.temperature;

    return chat({
      adapter,
      messages,
      systemPrompts,
      modelOptions,
      abortController,
    });
  },
});
```
</Tab>
</Tabs>

The examples above accept only explicit model choices and a bounded temperature.
Forward those preferences from the frontend provider:

## Helper Utilities [#helper-utilities]

These utilities are exported from `@copilotkit/runtime/v2` to help convert between CopilotKit's input format and your backend's expected format:

| Utility | Description |
|---|---|
| `convertInputToTanStackAI(input)` | Converts `RunAgentInput` to `{ messages, systemPrompts, tools }` for TanStack AI's `chat()`. Handles system/developer messages, context, state, and frontend tools. |
| `convertMessagesToVercelAISDKMessages(messages)` | Converts AG-UI messages to Vercel AI SDK's `ModelMessage[]` format. |
| `convertToolsToVercelAITools(tools)` | Converts frontend-defined tools (JSON Schema) to AI SDK's `ToolSet`. |
| `convertToolDefinitionsToVercelAITools(tools)` | Converts `defineTool()` definitions (Standard Schema) to AI SDK's `ToolSet`. |
| `resolveModel(spec)` | Resolves `"openai/gpt-6-luna"` strings to AI SDK `LanguageModel` instances. |
