ima2-gen 2.0.5 → 2.0.13

package/node_modules/ai/docs/03-agents/06-memory.mdx

@@ -0,0 +1,222 @@
+---
+title: Memory
+description: Add persistent memory to your agent using provider-defined tools, memory providers, or a custom tool.
+---
+
+# Memory
+
+Memory lets your agent save information and recall it later. Without memory, every conversation starts fresh. With memory, your agent builds context over time, recalls previous interactions, and adapts to the user.
+
+## Three Approaches
+
+You can add memory to your agent with the AI SDK in three ways, each with different tradeoffs:
+
+| Approach                                          | Effort | Flexibility | Provider Lock-in           |
+| ------------------------------------------------- | ------ | ----------- | -------------------------- |
+| [Provider-Defined Tools](#provider-defined-tools) | Low    | Medium      | Yes                        |
+| [Memory Providers](#memory-providers)             | Low    | Low         | Depends on memory provider |
+| [Custom Tool](#custom-tool)                       | High   | High        | No                         |
+
+## Provider-Defined Tools
+
+[Provider-defined tools](/docs/foundations/tools#types-of-tools) are tools where the provider specifies the tool's `inputSchema` and `description`, but you provide the `execute` function. The model has been trained to use these tools, which can result in better performance compared to custom tools.
+
+### Anthropic Memory Tool
+
+The [Anthropic Memory Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) gives Claude a structured interface for managing a `/memories` directory. Claude reads its memory before starting tasks, creates and updates files as it works, and references them in future conversations.
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { ToolLoopAgent } from 'ai';
+
+const memory = anthropic.tools.memory_20250818({
+  execute: async action => {
+    // `action` contains `command`, `path`, and other fields
+    // depending on the command (view, create, str_replace,
+    // insert, delete, rename).
+    // Implement your storage backend here.
+    // Return the result as a string.
+  },
+});
+
+const agent = new ToolLoopAgent({
+  model: 'anthropic/claude-haiku-4.5',
+  tools: { memory },
+});
+
+const result = await agent.generate({
+  prompt: 'Remember that my favorite editor is Neovim',
+});
+```
+
+The tool receives structured commands (`view`, `create`, `str_replace`, `insert`, `delete`, `rename`), each with a `path` scoped to `/memories`. Your `execute` function maps these to your storage backend (the filesystem, a database, or any other persistence layer).
+
+**When to use this**: you want memory with minimal implementation effort and are already using Anthropic models. The tradeoff is provider lock-in, since this tool only works with Claude.
+
+## Memory Providers
+
+Another approach is to use a provider that has memory built in. These providers wrap an external memory service and expose it through the AI SDK's standard interface. Memory storage, retrieval, and injection happen transparently, and you do not define any tools yourself.
+
+### Letta
+
+[Letta](https://letta.com) provides agents with persistent long-term memory. You create an agent on Letta's platform (cloud or self-hosted), configure its memory there, and use the AI SDK provider to interact with it. Letta's agent runtime handles memory management (core memory, archival memory, recall).
+
+```bash
+pnpm add @letta-ai/vercel-ai-sdk-provider
+```
+
+```ts
+import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
+import { ToolLoopAgent } from 'ai';
+
+const agent = new ToolLoopAgent({
+  model: lettaCloud(),
+  providerOptions: {
+    letta: {
+      agent: { id: 'your-agent-id' },
+    },
+  },
+});
+
+const result = await agent.generate({
+  prompt: 'Remember that my favorite editor is Neovim',
+});
+```
+
+You can also use Letta's built-in memory tools alongside custom tools:
+
+```ts
+import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
+import { ToolLoopAgent } from 'ai';
+
+const agent = new ToolLoopAgent({
+  model: lettaCloud(),
+  tools: {
+    core_memory_append: lettaCloud.tool('core_memory_append'),
+    memory_insert: lettaCloud.tool('memory_insert'),
+    memory_replace: lettaCloud.tool('memory_replace'),
+  },
+  providerOptions: {
+    letta: {
+      agent: { id: 'your-agent-id' },
+    },
+  },
+});
+
+const stream = agent.stream({
+  prompt: 'What do you remember about me?',
+});
+```
+
+See the [Letta provider documentation](/providers/community-providers/letta) for full setup and configuration.
+
+### Mem0
+
+[Mem0](https://mem0.ai) adds a memory layer on top of any supported LLM provider. It automatically extracts memories from conversations, stores them, and retrieves relevant ones for future prompts.
+
+```bash
+pnpm add @mem0/vercel-ai-provider
+```
+
+```ts
+import { createMem0 } from '@mem0/vercel-ai-provider';
+import { ToolLoopAgent } from 'ai';
+
+const mem0 = createMem0({
+  provider: 'openai',
+  mem0ApiKey: process.env.MEM0_API_KEY,
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const agent = new ToolLoopAgent({
+  model: mem0('gpt-4.1', { user_id: 'user-123' }),
+});
+
+const { text } = await agent.generate({
+  prompt: 'Remember that my favorite editor is Neovim',
+});
+```
+
+Mem0 works across multiple LLM providers (OpenAI, Anthropic, Google, Groq, Cohere). You can also manage memories explicitly:
+
+```ts
+import { addMemories, retrieveMemories } from '@mem0/vercel-ai-provider';
+
+await addMemories(messages, { user_id: 'user-123' });
+const context = await retrieveMemories(prompt, { user_id: 'user-123' });
+```
+
+See the [Mem0 provider documentation](/providers/community-providers/mem0) for full setup and configuration.
+
+### Supermemory
+
+[Supermemory](https://supermemory.ai) is a long-term memory platform that adds persistent, self-growing memory to your AI applications. It provides tools that handle saving and retrieving memories automatically through semantic search.
+
+```bash
+pnpm add @supermemory/tools
+```
+
+```ts
+__PROVIDER_IMPORT__;
+import { supermemoryTools } from '@supermemory/tools/ai-sdk';
+import { ToolLoopAgent } from 'ai';
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!),
+});
+
+const result = await agent.generate({
+  prompt: 'Remember that my favorite editor is Neovim',
+});
+```
+
+Supermemory works with any AI SDK provider. The tools give the model `addMemory` and `searchMemories` operations that handle storage and retrieval.
+
+See the [Supermemory provider documentation](/providers/community-providers/supermemory) for full setup and configuration.
+
+### Hindsight
+
+[Hindsight](/providers/community-providers/hindsight) provides agents with persistent memory through five tools: `retain`, `recall`, `reflect`, `getMentalModel`, and `getDocument`. It can be self-hosted with Docker or used as a cloud service.
+
+```bash
+pnpm add @vectorize-io/hindsight-ai-sdk @vectorize-io/hindsight-client
+```
+
+```ts
+__PROVIDER_IMPORT__;
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';
+import { ToolLoopAgent, stepCountIs } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const client = new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL });
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: createHindsightTools({ client, bankId: 'user-123' }),
+  stopWhen: stepCountIs(10),
+  instructions: 'You are a helpful assistant with long-term memory.',
+});
+
+const result = await agent.generate({
+  prompt: 'Remember that my favorite editor is Neovim',
+});
+```
+
+The `bankId` identifies the memory store and is typically a user ID. In multi-user apps, call `createHindsightTools` inside your request handler so each request gets the right bank. Hindsight works with any AI SDK provider.
+
+See the [Hindsight provider documentation](/providers/community-providers/hindsight) for full setup and configuration.
+
+**When to use memory providers**: these providers are a good fit when you want memory without building any storage infrastructure. The tradeoff is that the provider controls memory behavior, so you have less visibility into what gets stored and how it is retrieved. You also take on a dependency on an external service.
+
+## Custom Tool
+
+Building your own memory tool from scratch is the most flexible approach. You control the storage format, the interface, and the retrieval logic. This requires the most upfront work but gives you full ownership of how memory works, with no provider lock-in and no external dependencies.
+
+There are two common patterns:
+
+- **Structured actions**: you define explicit operations (`view`, `create`, `update`, `search`) and handle structured input yourself. Safe by design since you control every operation.
+- **Bash-backed**: you give the model a sandboxed bash environment to compose shell commands (`cat`, `grep`, `sed`, `echo`) for flexible memory access. More powerful but requires command validation for safety.
+
+For a full walkthrough of implementing a custom memory tool with a bash-backed interface, AST-based command validation, and filesystem persistence, see the **[Build a Custom Memory Tool](/cookbook/guides/custom-memory-tool)** recipe.

package/node_modules/ai/docs/03-agents/06-subagents.mdx

@@ -0,0 +1,362 @@
+---
+title: Subagents
+description: Delegate context-heavy tasks to specialized subagents while keeping the main agent focused.
+---
+
+# Subagents
+
+A subagent is an agent that a parent agent can invoke. The parent delegates work via a tool, and the subagent executes autonomously before returning a result.
+
+## How It Works
+
+1. **Define a subagent** with its own model, instructions, and tools
+2. **Create a tool that calls it** for the main agent to use
+3. **Subagent runs independently with its own context window**
+4. **Return a result** (optionally streaming progress to the UI)
+5. **Control what the model sees** using `toModelOutput` to summarize
+
+## When to Use Subagents
+
+Subagents add latency and complexity. Use them when the benefits outweigh the costs:
+
+| Use Subagents When                              | Avoid Subagents When           |
+| ----------------------------------------------- | ------------------------------ |
+| Tasks require exploring large amounts of tokens | Tasks are simple and focused   |
+| You need to parallelize independent research    | Sequential processing suffices |
+| Context would grow beyond model limits          | Context stays manageable       |
+| You want to isolate tool access by capability   | All tools can safely coexist   |
+
+## Why Use Subagents?
+
+### Offloading Context-Heavy Tasks
+
+Some tasks require exploring large amounts of information—reading files, searching codebases, or researching topics. Running these in the main agent consumes context quickly, making the agent less coherent over time.
+
+With subagents, you can:
+
+- Spin up a dedicated agent that uses hundreds of thousands of tokens
+- Have it return only a focused summary (perhaps 1,000 tokens)
+- Keep your main agent's context clean and coherent
+
+The subagent does the heavy lifting while the main agent stays focused on orchestration.
+
+### Parallelizing Independent Work
+
+For tasks like exploring a codebase, you can spawn multiple subagents to research different areas simultaneously. Each returns a summary, and the main agent synthesizes the findings—without paying the context cost of all that exploration.
+
+### Specialized Orchestration
+
+A less common but valid pattern is using a main agent purely for orchestration, delegating to specialized subagents for different types of work. For example:
+
+- An exploration subagent with read-only tools for researching codebases
+- A coding subagent with file editing tools
+- An integration subagent with tools for a specific platform or API
+
+This creates a clear separation of concerns, though context offloading and parallelization are the more common motivations for subagents.
+
+## Basic Subagent Without Streaming
+
+The simplest subagent pattern requires no special machinery. Your main agent has a tool that calls another agent in its `execute` function:
+
+```ts
+import { ToolLoopAgent, tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+// Define a subagent for research tasks
+const researchSubagent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a research agent.
+Summarize your findings in your final response.`,
+  tools: {
+    read: readFileTool, // defined elsewhere
+    search: searchTool, // defined elsewhere
+  },
+});
+
+// Create a tool that delegates to the subagent
+const researchTool = tool({
+  description: 'Research a topic or question in depth.',
+  inputSchema: z.object({
+    task: z.string().describe('The research task to complete'),
+  }),
+  execute: async ({ task }, { abortSignal }) => {
+    const result = await researchSubagent.generate({
+      prompt: task,
+      abortSignal,
+    });
+    return result.text;
+  },
+});
+
+// Main agent uses the research tool
+const mainAgent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are a helpful assistant that can delegate research tasks.',
+  tools: {
+    research: researchTool,
+  },
+});
+```
+
+This works well when you don't need to show the subagent's progress in the UI. The tool call blocks until the subagent completes, then returns the final text response.
+
+### Handling Cancellation
+
+When the user cancels a request, the `abortSignal` propagates to the subagent. Always pass it through to ensure cleanup:
+
+```ts
+execute: async ({ task }, { abortSignal }) => {
+  const result = await researchSubagent.generate({
+    prompt: task,
+    abortSignal, // Cancels subagent if main request is aborted
+  });
+  return result.text;
+},
+```
+
+If you abort the signal, the subagent stops executing and throws an `AbortError`. The main agent's tool execution fails, which stops the main loop.
+
+To avoid errors about incomplete tool calls in subsequent messages, use `convertToModelMessages` with `ignoreIncompleteToolCalls`:
+
+```ts
+import { convertToModelMessages } from 'ai';
+
+const modelMessages = await convertToModelMessages(messages, {
+  ignoreIncompleteToolCalls: true,
+});
+```
+
+This filters out tool calls that don't have corresponding results. Learn more in the [convertToModelMessages](/docs/reference/ai-sdk-ui/convert-to-model-messages) reference.
+
+## Streaming Subagent Progress
+
+When you want to show incremental progress as the subagent works, use [**preliminary tool results**](/docs/ai-sdk-core/tools-and-tool-calling#preliminary-tool-results). This pattern uses a generator function that yields partial updates to the UI.
+
+### How Preliminary Tool Results Work
+
+Change your `execute` function from a regular function to an async generator (`async function*`). Each `yield` sends a preliminary result to the frontend:
+
+```ts
+execute: async function* ({ /* input */ }) {
+  // ... do work ...
+  yield partialResult;
+  // ... do more work ...
+  yield updatedResult;
+}
+```
+
+### Building the Complete Message
+
+Each `yield` **replaces** the previous output entirely (it does not append). This means you need a way to accumulate the subagent's response into a complete message that grows over time.
+
+The `readUIMessageStream` utility handles this. It reads each chunk from the stream and builds an ever-growing `UIMessage` containing all parts received so far:
+
+```ts
+import { readUIMessageStream, tool } from 'ai';
+import { z } from 'zod';
+
+const researchTool = tool({
+  description: 'Research a topic or question in depth.',
+  inputSchema: z.object({
+    task: z.string().describe('The research task to complete'),
+  }),
+  execute: async function* ({ task }, { abortSignal }) {
+    // Start the subagent with streaming
+    const result = await researchSubagent.stream({
+      prompt: task,
+      abortSignal,
+    });
+
+    // Each iteration yields a complete, accumulated UIMessage
+    for await (const message of readUIMessageStream({
+      stream: result.toUIMessageStream(),
+    })) {
+      yield message;
+    }
+  },
+});
+```
+
+Each yielded `message` is a complete `UIMessage` containing all the subagent's parts up to that point (text, tool calls, and tool results). The frontend simply replaces its display with each new message.
+
+## Controlling What the Model Sees
+
+Here's where subagents become powerful for context management. The full `UIMessage` with all the subagent's work is stored in the message history and displayed in the UI. But you can control what the main agent's model actually sees using `toModelOutput`.
+
+### How It Works
+
+The `toModelOutput` function maps the tool's output to the tokens sent to the model:
+
+```ts
+const researchTool = tool({
+  description: 'Research a topic or question in depth.',
+  inputSchema: z.object({
+    task: z.string().describe('The research task to complete'),
+  }),
+  execute: async function* ({ task }, { abortSignal }) {
+    const result = await researchSubagent.stream({
+      prompt: task,
+      abortSignal,
+    });
+
+    for await (const message of readUIMessageStream({
+      stream: result.toUIMessageStream(),
+    })) {
+      yield message;
+    }
+  },
+  toModelOutput: ({ output: message }) => {
+    // Extract just the final text as a summary
+    const lastTextPart = message?.parts.findLast(p => p.type === 'text');
+    return {
+      type: 'text',
+      value: lastTextPart?.text ?? 'Task completed.',
+    };
+  },
+});
+```
+
+With this setup:
+
+- **Users see**: The full subagent execution—every tool call, every intermediate step
+- **The model sees**: Just the final summary text
+
+The subagent might use 100,000 tokens exploring and reasoning, but the main agent only consumes the summary. This keeps the main agent coherent and focused.
+
+### Write Subagent Instructions for Summarization
+
+For `toModelOutput` to extract a useful summary, your subagent must produce one. Add explicit instructions like this:
+
+```ts
+const researchSubagent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: `You are a research agent. Complete the task autonomously.
+
+IMPORTANT: When you have finished, write a clear summary of your findings as your final response.
+This summary will be returned to the main agent, so include all relevant information.`,
+  tools: {
+    read: readFileTool,
+    search: searchTool,
+  },
+});
+```
+
+Without this instruction, the subagent might not produce a comprehensive summary. It could simply say "Done", leaving `toModelOutput` with nothing useful to extract.
+
+## Rendering Subagents in the UI (with useChat)
+
+To display streaming progress, check the tool part's `state` and `preliminary` flag.
+
+### Tool Part States
+
+| State              | Description                                |
+| ------------------ | ------------------------------------------ |
+| `input-streaming`  | Tool input being generated                 |
+| `input-available`  | Tool ready to execute                      |
+| `output-available` | Tool produced output (check `preliminary`) |
+| `output-error`     | Tool execution failed                      |
+
+### Detecting Streaming vs Complete
+
+```tsx
+const hasOutput = part.state === 'output-available';
+const isStreaming = hasOutput && part.preliminary === true;
+const isComplete = hasOutput && !part.preliminary;
+```
+
+### Type Safety for Subagent Output
+
+Export types alongside your agents for use in UI components:
+
+```ts filename="lib/agents.ts"
+import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
+
+export const mainAgent = new ToolLoopAgent({
+  // ... configuration with researchTool
+});
+
+// Export the main agent message type for the chat UI
+export type MainAgentMessage = InferAgentUIMessage<typeof mainAgent>;
+```
+
+### Render Messages and Subagent Output
+
+This example uses the types defined above to render both the main agent's messages and the subagent's streamed output:
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { MainAgentMessage } from '@/lib/agents';
+
+export function Chat() {
+  const { messages } = useChat<MainAgentMessage>();
+
+  return (
+    <div>
+      {messages.map(message =>
+        message.parts.map((part, i) => {
+          switch (part.type) {
+            case 'text':
+              return <p key={i}>{part.text}</p>;
+            case 'tool-research':
+              return (
+                <div>
+                  {part.state !== 'input-streaming' && (
+                    <div>Research: {part.input.task}</div>
+                  )}
+                  {part.state === 'output-available' && (
+                    <div>
+                      {part.output.parts.map((nestedPart, i) => {
+                        switch (nestedPart.type) {
+                          case 'text':
+                            return <p key={i}>{nestedPart.text}</p>;
+                          default:
+                            return null;
+                        }
+                      })}
+                    </div>
+                  )}
+                </div>
+              );
+            default:
+              return null;
+          }
+        }),
+      )}
+    </div>
+  );
+}
+```
+
+## Caveats
+
+### No Tool Approvals in Subagents
+
+Subagent tools cannot use `needsApproval`. All tools must execute automatically without user confirmation.
+
+### Subagent Context is Isolated
+
+Each subagent invocation starts with a fresh context window. This is one of the key benefits of subagents: they don't inherit the accumulated context from the main agent, which is exactly what allows them to do heavy exploration without bloating the main conversation.
+
+If you need to give a subagent access to the conversation history, the `messages` are available in the tool's execute function alongside `abortSignal`:
+
+```ts
+execute: async ({ task }, { abortSignal, messages }) => {
+  const result = await researchSubagent.generate({
+    messages: [
+      ...messages, // The main agent's conversation history
+      { role: 'user', content: task }, // The specific task for this invocation
+    ],
+    abortSignal,
+  });
+  return result.text;
+},
+```
+
+Use this sparingly since passing full history defeats some of the context isolation benefits.
+
+### Streaming Adds Complexity
+
+The basic pattern (no streaming) is simpler to implement and debug. Only add streaming when you need to show real-time progress in the UI.

package/node_modules/ai/docs/03-agents/index.mdx

@@ -0,0 +1,46 @@
+---
+title: Agents
+description: An overview of building agents with the AI SDK.
+---
+
+# Agents
+
+The following section shows you how to build agents with the AI SDK - systems where large language models (LLMs) use tools in a loop to accomplish tasks.
+
+<IndexCards
+  cards={[
+    {
+      title: 'Overview',
+      description: 'Learn what agents are and why to use the ToolLoopAgent.',
+      href: '/docs/agents/overview',
+    },
+    {
+      title: 'Building Agents',
+      description: 'Complete guide to creating agents with the ToolLoopAgent.',
+      href: '/docs/agents/building-agents',
+    },
+    {
+      title: 'Workflow Patterns',
+      description:
+        'Structured patterns using core functions for complex workflows.',
+      href: '/docs/agents/workflows',
+    },
+    {
+      title: 'Loop Control',
+      description: 'Advanced execution control with stopWhen and prepareStep.',
+      href: '/docs/agents/loop-control',
+    },
+    {
+      title: 'Configuring Call Options',
+      description:
+        'Pass type-safe runtime inputs to dynamically configure agent behavior.',
+      href: '/docs/agents/configuring-call-options',
+    },
+    {
+      title: 'Subagents',
+      description:
+        'Delegate context-heavy tasks to specialized subagents while keeping the main agent focused.',
+      href: '/docs/agents/subagents',
+    },
+  ]}
+/>

package/node_modules/ai/docs/03-ai-sdk-core/01-overview.mdx

@@ -0,0 +1,31 @@
+---
+title: Overview
+description: An overview of AI SDK Core.
+---
+
+# AI SDK Core
+
+Large Language Models (LLMs) are advanced programs that can understand, create, and engage with human language on a large scale.
+They are trained on vast amounts of written material to recognize patterns in language and predict what might come next in a given piece of text.
+
+AI SDK Core **simplifies working with LLMs by offering a standardized way of integrating them into your app** - so you can focus on building great AI applications for your users, not waste time on technical details.
+
+For example, here’s how you can generate text with various models using the AI SDK:
+
+<PreviewSwitchProviders />
+
+## AI SDK Core Functions
+
+AI SDK Core has various functions designed for [text generation](./generating-text), [structured data generation](./generating-structured-data), and [tool usage](./tools-and-tool-calling).
+These functions take a standardized approach to setting up [prompts](./prompts) and [settings](./settings), making it easier to work with different models.
+
+- [`generateText`](/docs/ai-sdk-core/generating-text): Generates text and [tool calls](./tools-and-tool-calling).
+  This function is ideal for non-interactive use cases such as automation tasks where you need to write text (e.g. drafting email or summarizing web pages) and for agents that use tools.
+- [`streamText`](/docs/ai-sdk-core/generating-text): Stream text and tool calls.
+  You can use the `streamText` function for interactive use cases such as [chat bots](/docs/ai-sdk-ui/chatbot) and [content streaming](/docs/ai-sdk-ui/completion).
+
+Both `generateText` and `streamText` support [structured output](/docs/ai-sdk-core/generating-structured-data) via the `output` property (e.g. `Output.object()`, `Output.array()`), allowing you to generate typed, schema-validated data for information extraction, synthetic data generation, classification tasks, and [streaming generated UIs](/docs/ai-sdk-ui/object-generation).
+
+## API Reference
+
+Please check out the [AI SDK Core API Reference](/docs/reference/ai-sdk-core) for more details on each function.