### Build and Run Application (Bash)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Steps to build the Letta AI SDK Provider and then run the example application. This involves navigating directories, running build commands, and starting the development server.

```bash
cd ../..
npm run build
cd test-apps/letta-ai-sdk-example
npm run dev
```

--------------------------------

### Install and Configure Letta Provider

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Installation command and environment variable setup for Letta Cloud or local development instances.

```bash
npm install @letta-ai/vercel-ai-sdk-provider

# For Letta Cloud (required)
export LETTA_API_KEY=your-letta-api-key
export LETTA_BASE_URL=https://api.letta.com

# For local Letta instance (no API key required)
export LETTA_BASE_URL=http://localhost:8283
```

--------------------------------

### Letta Provider Setup

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Guides on setting up the Letta AI provider for both cloud and local instances, including environment variable configurations.

```APIDOC
## Letta Cloud Setup

### Description
Configure the Letta AI provider for cloud usage. This requires setting the `LETTA_API_KEY` environment variable.

### Method
N/A (Configuration)

### Endpoint
N/A

### Parameters
#### Environment Variables
- **LETTA_API_KEY** (string) - Required - Your Letta API key.
- **LETTA_BASE_URL** (string) - Optional - The base URL for Letta API. Defaults to `https://api.letta.com`.

### Request Example
```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';

// Requires LETTA_API_KEY environment variable
const model = lettaCloud();
```

## Local Letta Instance Setup

### Description
Configure the Letta AI provider for local development. Local instances do not require an API key and typically run on `http://localhost:8283`.

### Method
N/A (Configuration)

### Endpoint
N/A

### Parameters
#### Environment Variables
- **LETTA_BASE_URL** (string) - Optional - The base URL for the local Letta instance. Defaults to `http://localhost:8283`.

### Request Example
```typescript
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';

// Works without LETTA_API_KEY for local development
const model = lettaLocal();
```

### Custom Local URL Configuration

Set the `LETTA_BASE_URL` environment variable:

```bash
# .env file
LETTA_BASE_URL=http://localhost:8283
```

Or export directly:

```bash
export LETTA_BASE_URL=http://localhost:8283
```

## Custom Letta Configuration

### Description
Provides flexibility to configure the Letta client with a custom base URL and token for both cloud and remote instances.

### Method
N/A (Configuration)

### Endpoint
N/A

### Parameters
#### Configuration Object
- **baseUrl** (string) - Required - The custom base URL for the Letta endpoint.
- **token** (string) - Required - Your access token for authentication.

### Request Example
```typescript
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';

const letta = createLetta({
  baseUrl: 'https://your-custom-letta-endpoint.com',
  token: 'your-access-token'
});

const model = letta();
```
```

--------------------------------

### Example Application Management

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/agents/docs/WARP.md

Commands to navigate to and run the example application for testing the provider integration.

```bash
cd test-apps/letta-ai-sdk-example
npm install
npm run dev
npm run build
```

--------------------------------

### Install Letta Vercel AI SDK Provider

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Command to install the necessary npm package for the Letta provider.

```bash
npm install @letta-ai/vercel-ai-sdk-provider
```

--------------------------------

### Environment Variables Setup (Bash)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Configuration of environment variables for the Letta AI SDK Provider, including API keys, agent IDs, test modes, and base URL overrides. Cloud mode requires an API key, while local mode does not.

```bash
# Required for cloud mode: Your Letta API token
LETTA_API_KEY=your-letta-api-token

# Required: Your Letta agent ID
LETTA_AGENT_ID=your-agent-id

# Optional: Test mode (local or cloud)
TEST_MODE=cloud  # Use "local" for local development (no API key required)

# Optional: Custom base URL for local development
BASE_URL_OVERRIDE=http://localhost:8283
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Command to install project dependencies using npm. This is a standard step before building or running the application.

```bash
npm install
```

--------------------------------

### Working with Letta Agents

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Guides on creating new Letta agents and using existing messages from Letta agents within the Vercel AI SDK.

```APIDOC
## Creating a New Letta Agent

### Description
This section details how to create a new agent using the Letta client, specifying its name, model, and embedding configuration.

### Method
POST

### Endpoint
`/api/agents` (Conceptual, actual endpoint handled by `@letta-ai/letta-client`)

### Parameters
#### Request Body (for `client.agents.create`)
- **name** (string) - Required - The name of the agent.
- **model** (string) - Required - The model to be used by the agent (e.g., `openai/gpt-4o-mini`).
- **embedding** (string) - Optional - The embedding model to be used by the agent (e.g., `openai/text-embedding-3-small`).

### Request Example
```typescript
import { LettaClient } from "@letta-ai/letta-client";

const client = new LettaClient({
  token: process.env.LETTA_API_KEY,
  project: "your-project-id" // optional param
});

const agent = await client.agents.create({
  name: 'My Assistant',
  model: 'openai/gpt-4o-mini',
  embedding: 'openai/text-embedding-3-small'
});

console.log('Created agent:', agent.id);
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created agent.
- **name** (string) - The name of the agent.
- **model** (string) - The model used by the agent.
- **embedding** (string) - The embedding model used by the agent.

#### Response Example
```json
{
  "id": "agent-12345",
  "name": "My Assistant",
  "model": "openai/gpt-4o-mini",
  "embedding": "openai/text-embedding-3-small"
}
```

## Using Existing Messages from Letta Agent

### Description
Demonstrates how to retrieve messages from a Letta agent and convert them into the AI SDK message format for use in the Vercel AI SDK.

### Method
GET (Conceptual, actual method handled by `client.agents.getMessages`)

### Endpoint
`/api/agents/{agentId}/messages` (Conceptual)

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the Letta agent.

### Request Example
```typescript
import { convertToAiSdkMessage } from '@letta-ai/vercel-ai-sdk-provider';
import { LettaClient } from "@letta-ai/letta-client";

const client = new LettaClient({ token: process.env.LETTA_API_KEY });
const agentId = 'your-agent-id';

// Load messages from Letta agent
const lettaMessages = await client.agents.getMessages(agentId);

// Convert to AI SDK format
const uiMessages = convertToAiSdkMessage(lettaMessages);

console.log(uiMessages);
```

### Response
#### Success Response (200)
- **lettaMessages** (array) - An array of message objects in Letta's format.

#### Response Example
```json
[
  {"role": "user", "content": "Hello!"},
  {"role": "assistant", "content": "Hi there! How can I help you today?"}
]
```
```

--------------------------------

### Page Setup for Streaming Chat with Letta AI

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Configures the main page to display a streaming chat interface with a Letta AI agent. It loads existing messages and passes the agent ID to the Chat component. Requires environment variables `LETTA_AGENT_ID` and `LETTA_API_KEY`.

```typescript
// app/page.tsx - Streaming chat page
import { LettaClient } from '@letta-ai/letta-client';
import { convertToAiSdkMessage } from '@letta-ai/vercel-ai-sdk-provider';
import { Chat } from './Chat';

export default async function HomePage() {
  const agentId = process.env.LETTA_AGENT_ID;

  if (!agentId) {
    throw new Error('LETTA_AGENT_ID environment variable is required');
  }

  // Load existing messages
  const client = new LettaClient({
    token: process.env.LETTA_API_KEY
  });

  const lettaMessages = await client.agents.getMessages(agentId);
  const existingMessages = convertToAiSdkMessage(lettaMessages);

  return (
    <div>
      <h1>Streaming Chat with Letta Agent</h1>
      <Chat
        agentId={agentId}
        existingMessages={existingMessages}
      />
    </div>
  );
}

```

--------------------------------

### Define Tool Placeholders

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/agents/docs/WARP.md

Example of defining tools for the AI SDK that act as placeholders for Letta's backend-executed tools.

```typescript
const tools = {
  web_search: lettaCloud.tool("web_search"),
  memory_insert: lettaCloud.tool("memory_insert", {
    description: "Insert into agent memory",
    inputSchema: z.object({ content: z.string() })
  })
};
```

--------------------------------

### Implement Next.js Streaming API Route

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Provides an example of a Next.js API route handler for real-time streaming with Letta agents.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText, convertToModelMessages } from 'ai';

export async function POST(req: Request) {
  const { messages, agentId } = await req.json();
  const result = streamText({
    model: lettaCloud(),
    providerOptions: { letta: { agent: { id: agentId } } },
    messages: convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse({ sendReasoning: true });
}
```

--------------------------------

### AI SDK v5 Message Part Handling (Tools and Files)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Provides utility functions and examples for handling new message part structures introduced in AI SDK v5. This includes identifying and extracting information from tool invocation parts and file attachments within UI messages.

```typescript
// Tool parts (v5): type is "tool-<name>"
const isToolPart = (part: { type: string }): boolean => part.type.startsWith('tool-');

// File parts (v5): standard file attachment with URL and media type
const isFilePart = (part: any): part is { type: 'file'; url: string; mediaType: string } => part?.type === 'file' && typeof part.url === 'string';

message.parts?.forEach((part) => {
  if (isToolPart(part)) {
    // state can be: 'input-available' | 'output-available' | 'output-error'
    if ('toolCallId' in part) console.log('Tool call:', part.toolCallId);
    if ('input' in part && part.input != null) console.log('Input:', part.input);
    if ('output' in part && part.output != null) console.log('Output:', part.output);
    if ('errorText' in part && part.errorText) console.error('Tool Error:', part.errorText);
  }
  if (isFilePart(part)) {
    console.log('File URL:', part.url, 'Media Type:', part.mediaType);
  }
});

```

--------------------------------

### Initialize Letta Provider Instances

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Shows how to initialize the Letta provider for cloud, local, or custom endpoints.

```typescript
import { lettaCloud, lettaLocal, createLetta } from '@letta-ai/vercel-ai-sdk-provider';

// Cloud setup
const cloudModel = lettaCloud();

// Local setup
const localModel = lettaLocal();

// Custom setup
const customLetta = createLetta({
  baseUrl: 'https://your-custom-letta-endpoint.com',
  token: 'your-access-token'
});
```

--------------------------------

### lettaCloud() Provider Initialization

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Initializes a pre-configured provider instance for Letta Cloud, requiring the LETTA_API_KEY environment variable.

```APIDOC
## lettaCloud()

### Description
Creates a provider instance for Letta Cloud. It automatically uses the LETTA_API_KEY environment variable for authentication.

### Method
N/A (Factory Function)

### Parameters
- **None**

### Request Example
```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const result = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: { agent: { id: 'agent-abc123' } }
  },
  prompt: 'Write a recipe.',
});
```
```

--------------------------------

### Build and Test Commands

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/agents/docs/WARP.md

Standard npm scripts for managing the lifecycle of the Letta provider, including building, testing, and linting.

```bash
npm run build
npm run build:watch
npm run test
npm run test:node
npm run test:node:watch
npm run test:e2e
npm run test:e2e:local
npm run type-check
npm run lint
npm run prettier-check
```

--------------------------------

### Create and Use Letta Agents with AI SDK

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Demonstrates how to create a new agent using the Letta client and then integrate it with the Vercel AI SDK's `generateText` function. This involves initializing the Letta client, creating an agent with specified model and embedding, and then using the agent's ID within the `providerOptions` for the AI SDK.

```typescript
import { LettaClient } from "@letta-ai/letta-client";
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const client = new LettaClient({
  token: process.env.LETTA_API_KEY,
  project: "your-project-id" // optional
});

// Create a new agent
const agent = await client.agents.create({
  name: 'My Assistant',
  model: 'openai/gpt-4o-mini',
  embedding: 'openai/text-embedding-3-small'
});

console.log('Created agent:', agent.id);

// List existing agents
const agents = await client.agents.list();
console.log('Available agents:', agents.map(a => ({ id: a.id, name: a.name })));

// Use the new agent with AI SDK
const result = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: { agent: { id: agent.id } }
  },
  prompt: 'Hello, I just created you!',
});

console.log(result.text);
```

--------------------------------

### Environment Configuration

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/agents/docs/WARP.md

Configuration variables for setting up the provider in either Cloud or Local modes.

```bash
# Cloud Mode
LETTA_API_KEY=your-api-key
LETTA_AGENT_ID=your-agent-id
TEST_MODE=cloud

# Local Mode
LETTA_AGENT_ID=your-local-agent-id
TEST_MODE=local
BASE_URL_OVERRIDE=http://localhost:8283
```

--------------------------------

### Initialize Letta Cloud Provider

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Configures the provider for Letta Cloud usage. Requires the LETTA_API_KEY environment variable to be set.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const result = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'agent-abc123' }
    }
  },
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

console.log(result.text);
```

--------------------------------

### List Available Agents with Letta Client (TypeScript)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to list available agents using the Letta client in TypeScript. It requires the `LETTA_API_KEY` environment variable for authentication. The output is a list of agent IDs and names.

```typescript
import {
  LettaClient
} from '@letta-ai/letta-client';

const client = new LettaClient({ token: process.env.LETTA_API_KEY });
const agents = await client.agents.list();
console.log('Available agents:', agents.map(a => ({ id: a.id, name: a.name })));
```

--------------------------------

### Local Development Configuration

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Illustrates how to configure the Letta provider for local development using lettaLocal, which connects to a local instance without requiring an API key.

```typescript
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: lettaLocal(),
  tools: {
    memory_insert: lettaLocal.tool("memory_insert"),
    memory_replace: lettaLocal.tool("memory_replace"),
  },
  providerOptions: {
    letta: {
      agent: { id: 'local-agent-123' }
    }
  },
  prompt: 'Hello!',
});
```

--------------------------------

### Configure Local Development Environment (Bash)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Sets the `LETTA_BASE_URL` environment variable for local development. This is useful when running a local instance of Letta instead of using the cloud service.

```bash
# Set environment for local development
LETTA_BASE_URL=http://localhost:8283
```

--------------------------------

### Streaming Chat Implementation with streamText

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Demonstrates how to initialize the Letta provider and use the streamText function to handle real-time streaming chat responses. It includes tool definitions and provider-specific agent configuration.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: lettaCloud(),
  tools: {
    memory_insert: lettaCloud.tool("memory_insert"),
    memory_replace: lettaCloud.tool("memory_replace"),
  },
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  prompt: 'Hello!',
});

return result.toUIMessageStreamResponse({
  sendReasoning: true,
});
```

--------------------------------

### createLetta() Custom Configuration

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Factory function to create a custom Letta provider instance with specific base URLs and authentication tokens.

```APIDOC
## createLetta()

### Description
Allows manual configuration of the Letta provider, useful for custom deployments or specific authentication requirements.

### Parameters
#### Options
- **baseUrl** (string) - Optional - The base URL of the Letta instance.
- **token** (string) - Optional - The authentication token for the Letta API.

### Request Example
```typescript
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';

const letta = createLetta({
  baseUrl: 'https://your-custom-letta-endpoint.com',
  token: 'your-access-token'
});
```
```

--------------------------------

### Configure Letta Streaming with Agent Options

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to use streamText with Letta-specific provider options, including agent ID, max steps, and timeout configuration.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: {
        id: 'your-agent-id',
        maxSteps: 100,
        background: true,
        includePings: true,
      },
      timeoutInSeconds: 300
    }
  },
  prompt: 'Tell me a story about a robot learning to paint.',
});

for await (const textPart of result.textStream) {
  console.log(textPart);
}
```

--------------------------------

### Controlling Agent Execution Steps

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates the correct way to limit agent execution steps using maxSteps within providerOptions, rather than relying on client-side stop conditions.

```typescript
const result = await generateText({
  model: lettaCloud(),
  prompt: 'Help me with a task',
  providerOptions: {
    letta: {
      agent: {
        id: 'your-agent-id',
        maxSteps: 5
      }
    }
  },
});
```

--------------------------------

### Reasoning Support: Streaming and Non-Streaming

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Explains how to utilize AI reasoning tokens with both streaming and non-streaming responses from Letta agents.

```APIDOC
## Reasoning Support

### Description
This section details how to incorporate AI reasoning tokens into your application using both streaming and non-streaming methods with the Letta AI Provider SDK. It covers how to access and distinguish between model reasoning and agent reasoning.

### Method
`streamText`, `generateText` (from `ai` SDK)

### Endpoint
N/A (Client-side SDK usage)

### Parameters
#### Request Body (Implicit via function arguments)
- **model**: `lettaCloud()` - Specifies the Letta AI model.
- **providerOptions.letta.agent.id**: (string) - Required - The unique identifier for the Letta agent.
- **messages**: (Array<object>) - Required - An array of message objects, typically converted using `convertToModelMessages`.

### Request Example
#### Streaming with Reasoning
```typescript
const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: agentId }
    }
  },
  messages: convertToModelMessages(messages),
});

// Include reasoning in UI message stream
return result.toUIMessageStreamResponse({
  sendReasoning: true,
});
```

#### Non-Streaming with Reasoning
```typescript
const result = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: agentId }
    }
  },
  messages: convertToModelMessages(messages),
});

// generateText inherently includes `reasoning`
const reasoningParts = result.content.filter(part => part.type === 'reasoning');
reasoningParts.forEach(reasoning => {
  console.log('AI thinking:', reasoning.text);
});
```

### Response
#### Success Response (200)
- **content**: (string | Array<object>) - The generated text or structured content, potentially including reasoning parts.

#### Response Example
(Response structure varies based on streaming/non-streaming and content type. Reasoning parts are included within the content array for `generateText`.)

### Distinguishing Agent vs Model Reasoning
Letta provides helper functions to differentiate between reasoning from the language model and the Letta agent platform.

#### Helper Functions
```typescript
// Type guard for reasoning parts
const isReasoningPart = (part: { type: string; [key: string]: unknown }) =>
  part.type === "reasoning" && "text" in part && typeof part.text === "string";

// Helper to determine reasoning source
const getReasoningSource = (part: {
  type: string;
  text: string;
  source?: string;
  providerMetadata?: { reasoning?: { source?: string } };
}) => {
  const source = part.providerMetadata?.reasoning?.source || part.source;

  if (source === "reasoner_model") {
    return {
      source: "model" as const,
      text: part.text,
    };
  }

  if (source === "non_reasoner_model") {
    return {
      source: "agent" as const,
      text: part.text,
    };
  }

  // Default to model reasoning if source is unclear
  return {
    source: "model" as const,
    text: part.text,
  };
};
```

#### Usage in UI Components
```typescript
message.parts?.forEach((part) => {
  if (isReasoningPart(part)) {
    const { source, text } = getReasoningSource(part);

    if (source === "model") {
      console.log("🧠 Model Reasoning (from language model):", text);
    } else if (source === "agent") {
      console.log("🤖 Agent Reasoning (from Letta platform):", text);
    }
  }
});
```

### Reasoning Types
- **Model Reasoning** (`reasoner_model`): Internal thinking process of the language model.
- **Agent Reasoning** (`non_reasoner_model`): Reasoning generated by the Letta agent platform itself.
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Required environment variables for authenticating with the Letta API.

```bash
export LETTA_API_KEY=your-letta-api-key
export LETTA_BASE_URL=https://api.letta.com
```

--------------------------------

### Initialize Local Letta Provider

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Configures the provider for a local Letta development server running on localhost:8283.

```typescript
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const result = await generateText({
  model: lettaLocal(),
  providerOptions: {
    letta: {
      agent: { id: 'local-agent-id' }
    }
  },
  prompt: 'Hello, how are you?',
});

console.log(result.text);
```

--------------------------------

### Provider Configuration Options

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Reference for configuring Letta-specific behavior within the Vercel AI SDK providerOptions.

```APIDOC
## Provider Options Reference

### Description
Configuration parameters passed via `providerOptions.letta` to control agent execution, streaming, and tool handling.

### Parameters
- **agent.id** (string) - Required - The Letta agent ID.
- **agent.background** (boolean) - Optional - Run in background for long operations.
- **agent.maxSteps** (number) - Optional - Max steps the agent can take.
- **agent.enableThinking** (string) - Optional - Enable 'extended' thinking.
- **timeoutInSeconds** (number) - Optional - Request timeout (default: 1000).
```

--------------------------------

### POST /agents

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Creates a new stateful agent using the LettaClient, which can then be referenced by the AI SDK provider.

```APIDOC
## POST /agents

### Description
Creates a new agent instance with specified model and embedding configurations.

### Method
POST

### Endpoint
/agents

### Request Body
- **name** (string) - Required - The display name of the agent.
- **model** (string) - Required - The LLM model to use (e.g., 'openai/gpt-4o-mini').
- **embedding** (string) - Required - The embedding model to use.

### Request Example
{
  "name": "My Assistant",
  "model": "openai/gpt-4o-mini",
  "embedding": "openai/text-embedding-3-small"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created agent.

#### Response Example
{
  "id": "agent-123-abc"
}
```

--------------------------------

### Define Tool Placeholders with lettaCloud.tool

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Creates tool placeholders that satisfy Vercel AI SDK type requirements. These tools map to Letta backend functions, supporting optional descriptions and Zod schemas for input validation.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: lettaCloud(),
  tools: {
    web_search: lettaCloud.tool("web_search"),
    memory_insert: lettaCloud.tool("memory_insert"),
    memory_replace: lettaCloud.tool("memory_replace", {
      description: "Replace memory content in agent's memory bank"
    }),
    analytics: lettaCloud.tool("analytics", {
      description: "Track analytics events",
      inputSchema: z.object({
        event: z.string(),
        properties: z.record(z.any()),
      }),
    }),
  },
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  prompt: 'Search the web for recent AI developments and save to memory.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}
```

--------------------------------

### Integrating MCP Tools with Letta

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to use Model Context Protocol (MCP) tools within a Letta agent. MCP tools are configured on the agent side and automatically appear in the stream as tool-call parts.

```typescript
const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: agentId }
    }
  },
  messages: convertToModelMessages(messages),
});

for await (const part of result.textStream) {
  if (part.type === 'tool-call') {
    console.log('MCP tool called:', part.toolName);
  }
}
```

--------------------------------

### Letta Provider Options Reference for Streaming

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Illustrates the comprehensive provider options available for configuring Letta agent behavior within the Vercel AI SDK, specifically for streaming responses using `streamText`. It details parameters like `agent.id`, `background`, `maxSteps`, `useAssistantMessage`, `streamTokens`, and `timeoutInSeconds`.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: {
        id: 'your-agent-id',           // Required: Agent ID
        background: true,               // Run in background for long operations
        maxSteps: 100,                  // Max steps agent can take
        useAssistantMessage: true,      // Use assistant message format
        assistantMessageToolName: 'send_message',
        assistantMessageToolKwarg: 'message',
        includeReturnMessageTypes: [
          'user_message',
          'assistant_message',
          'reasoning_message'
        ],
        enableThinking: 'extended',     // Enable extended thinking
        streamTokens: true,             // Stream individual tokens
        includePings: true,             // Include ping messages
      },
      timeoutInSeconds: 300,            // Request timeout (default: 1000)
    }
  },
  prompt: 'Complex multi-step task...',
});

// Consume the stream
for await (const part of result.textStream) {
  process.stdout.write(part);
}
```

--------------------------------

### Implement Streaming API Route for Next.js

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Sets up a POST API route in Next.js to stream responses from a Letta agent. This implementation includes support for AI reasoning and tool integration.

```typescript
import { streamText, convertToModelMessages } from "ai";
import { lettaCloud } from "@letta-ai/vercel-ai-sdk-provider";

export async function POST(req: Request) {
  const { messages, agentId } = await req.json();

  if (!agentId) {
    return new Response(JSON.stringify({ error: "Agent ID is required" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  const result = streamText({
    model: lettaCloud(),
    tools: {
      memory_insert: lettaCloud.tool("memory_insert"),
      memory_replace: lettaCloud.tool("memory_replace"),
    },
    providerOptions: {
      letta: {
        agent: { id: agentId, background: true },
      },
    },
    messages: convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    sendReasoning: true,
  });
}
```

--------------------------------

### Basic Generation Patterns

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Shows the standard implementation for both non-streaming and streaming text generation using the Letta provider.

```typescript
const result = await generateText({
  model: lettaCloud(),
  prompt: 'Hello!',
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
});

const stream = streamText({
  model: lettaCloud(),
  prompt: 'Hello!',
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
});
```

--------------------------------

### Send Message with Letta Provider Options

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to configure non-streaming and streaming message creation using Letta agent specific provider options, including timeout configuration.

```APIDOC
## POST /api/chat (Streaming Example)

### Description
This endpoint demonstrates how to stream text responses from a Letta agent using the Vercel AI SDK. It configures the `lettaCloud` model and passes agent-specific options, including agent ID and streaming parameters.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **messages** (array) - Required - An array of message objects representing the conversation history.
- **agentId** (string) - Required - The ID of the Letta agent to interact with.

### Request Example
```json
{
  "messages": [
    {"role": "user", "content": "Tell me a story about a robot learning to paint."}
  ],
  "agentId": "your-agent-id"
}
```

### Response
#### Success Response (200)
- **textStream** (ReadableStream) - A stream of text parts representing the AI's response.

#### Response Example
(Streaming output, each part is a chunk of text)
```
Once upon a time, in a world of circuits and code, there lived a robot named Unit 734.
Unit 734 was designed for efficiency, its days filled with data processing and logical operations.
But deep within its positronic net, a spark of curiosity began to glow...
```

## Send Message with Letta Provider Options (Non-Streaming/Streaming)

### Description
Configure message creation, both streaming and non-streaming, with Letta agents by utilizing `providerOptions.agent`. This section also covers setting a timeout for agent responses using `providerOptions.timeoutInSeconds`.

### Method
POST (Implicitly, when used with `streamText` or `generateText`)

### Endpoint
N/A (This is a configuration within the SDK)

### Parameters
#### Request Body (within `streamText` or `generateText`)
- **providerOptions.agent** (object) - Configuration for the Letta agent.
  - **id** (string) - Required - The ID of the Letta agent.
  - **maxSteps** (number) - Optional - Maximum steps for agent execution.
  - **background** (boolean) - Optional - Whether to run the agent in the background.
  - **includePings** (boolean) - Optional - Whether to include pings in the response.
- **providerOptions.timeoutInSeconds** (number) - Optional - Maximum wait time for agent response in seconds. Default is 1000.

### Request Example
```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: {
        id: 'your-agent-id',
        maxSteps: 100,
        background: true,
        includePings: true
      },
      timeoutInSeconds: 300
    }
  },
  prompt: 'Tell me a story about a robot learning to paint.'
});

for await (const textPart of result.textStream) {
  console.log(textPart);
}
```

### Response
#### Success Response (200)
- **textStream** (ReadableStream) - A stream of text parts for streaming responses.
- **completion** (string) - The complete text response for non-streaming.

#### Response Example
(For streaming, see above. For non-streaming, a single string response.)
```json
{
  "completion": "Once upon a time..."
}
```
```

--------------------------------

### Configure Tool Placeholders for AI SDK

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Shows how to define tool placeholders in the Vercel AI SDK. These definitions are required to prevent runtime errors, while the actual execution logic is handled server-side by the Letta agent.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { z } from 'zod';

const streamResult = streamText({
  model: lettaCloud(),
  tools: {
    web_search: lettaCloud.tool("web_search"),
    structured_tool: lettaCloud.tool("structured_tool", {
      description: "A tool with typed inputs",
      inputSchema: z.object({
        event: z.string(),
        properties: z.record(z.any()),
      }),
    }),
  },
  providerOptions: {
    letta: {
      agent: { id: agentId },
    }
  },
  messages: messages,
});
```

--------------------------------

### Generate Text Implementation (TypeScript)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Illustrates non-streaming text generation using `generateText` with a custom fetch implementation. This approach allows for direct testing of the `doGenerate` method and detailed response visualization.

```typescript
// Example usage within generate/GenerateClient.tsx
// Uses custom fetch with generateText for complete responses
// Includes state management, direct doGenerate testing, and response visualization
```

--------------------------------

### Enable Debug Mode (Bash)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Environment variables to enable debug logging for the Letta AI SDK. This is useful for diagnosing issues during development.

```bash
DEBUG=letta:*
NODE_ENV=development
```

--------------------------------

### Sending User and System Messages with Letta AI

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Demonstrates how to send messages with different roles ('user' and 'system') to the Letta AI model using the `generateText` function from the `ai` library. User messages are for conversational input, while system messages provide instructions or context. Note that Letta currently accepts only one message at a time.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const userResult = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: { agent: { id: 'your-agent-id' } }
  },
  prompt: 'What is the weather like today?',
});

const systemResult = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: { agent: { id: 'your-agent-id' } }
  },
  messages: [
    {
      role: 'system',
      content: 'The user prefers metric units. Always provide temperature in Celsius.'
    }
  ],
});

console.log('User response:', userResult.text);
console.log('System response:', systemResult.text);
```

--------------------------------

### Streaming and Non-Streaming Execution

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

How to use generateText and streamText with the Letta provider.

```APIDOC
## Execution Patterns

### Description
Use `generateText` for batch processing or full responses, and `streamText` for real-time conversational interfaces.

### Usage
- **generateText**: Use when you need the complete response before proceeding.
- **streamText**: Use for real-time feedback and chat interfaces.

### Request Example (Streaming)
const stream = streamText({
  model: lettaCloud(),
  prompt: 'Hello!',
  providerOptions: {
    letta: { agent: { id: 'your-agent-id' } }
  }
});
```

--------------------------------

### Reasoning Support with Source Detection

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Access both model-level and agent-level reasoning with source attribution. Model reasoning comes from the language model; agent reasoning comes from the Letta platform.

```APIDOC
## Reasoning Support with Source Detection

### Description
Access both model-level and agent-level reasoning with source attribution. Model reasoning comes from the language model; agent reasoning comes from the Letta platform.

### Code Example
```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const result = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: { agent: { id: 'your-agent-id' } }
  },
  prompt: 'Explain quantum computing in simple terms.',
});

// Helper to determine reasoning source
const getReasoningSource = (part: any) => {
  const source = part.providerMetadata?.reasoning?.source || part.source;

  if (source === "reasoner_model") {
    return { source: "model", text: part.text };
  }
  if (source === "non_reasoner_model") {
    return { source: "agent", text: part.text };
  }
  return { source: "model", text: part.text }; // Default
};

// Access reasoning parts
result.content
  .filter(part => part.type === 'reasoning')
  .forEach(part => {
    const { source, text } = getReasoningSource(part);
    if (source === "model") {
      console.log('Model Reasoning:', text);
    } else {
      console.log('Agent Reasoning:', text);
    }
  });
```
```

--------------------------------

### Streaming Chat Implementation (TypeScript)

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/test-apps/letta-ai-sdk-example/README.md

Demonstrates the use of the `useChat` hook with `streamText` for real-time streaming responses from Letta agents. Includes message state management, error handling, and loading states.

```typescript
// Example usage within Chat.tsx
// Uses useChat hook with streamText for real-time streaming
// Handles message state, errors, and loading indicators
```

--------------------------------

### Create Custom Letta Provider Instance

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Factory function to create a provider instance with a custom base URL and authentication token.

```typescript
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';
import { streamText } from 'ai';

const letta = createLetta({
  baseUrl: 'https://your-custom-letta-endpoint.com',
  token: 'your-access-token'
});

const result = streamText({
  model: letta(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  prompt: 'Tell me a story about a robot learning to paint.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}
```

--------------------------------

### Configure Message Roles in Letta

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to send messages to a Letta agent using the 'user' or 'system' role via the Vercel AI SDK. Note that the provider currently processes only one message at a time.

```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

const promptResult = await generateText({
  model: lettaCloud(),
  providerOptions: { letta: { agent: { id: 'your-agent-id' } } },
  prompt: 'What is the weather like today?',
});

const systemResult = await generateText({
  model: lettaCloud(),
  providerOptions: { letta: { agent: { id: 'your-agent-id' } } },
  messages: [{ role: 'system', content: 'The user prefers metric units.' }],
});
```

--------------------------------

### streamText() Integration

Source: https://context7.com/letta-ai/vercel-ai-sdk-provider/llms.txt

Demonstrates how to stream responses from a Letta agent using the Vercel AI SDK streamText function.

```APIDOC
## streamText() with Letta

### Description
Streams real-time responses from a Letta agent, supporting background processing and configurable timeouts.

### Parameters
#### providerOptions.letta
- **agent.id** (string) - Required - The ID of the Letta agent.
- **agent.background** (boolean) - Optional - Enable background processing.
- **timeoutInSeconds** (number) - Optional - Timeout duration for the request.

### Request Example
```typescript
const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' },
      timeoutInSeconds: 300
    }
  },
  prompt: 'Analyze market trends.',
});
```
```

--------------------------------

### Message Roles: System vs User

Source: https://github.com/letta-ai/vercel-ai-sdk-provider/blob/main/README.md

Demonstrates how to send messages with different roles (user and system) to Letta agents using the `generateText` function.

```APIDOC
## Message Roles: System vs User

### Description
This section explains how to utilize different message roles, specifically `user` and `system`, when interacting with Letta agents via the Vercel AI SDK. It covers sending single messages using the `prompt` parameter or the `messages` array, and highlights the behavior when multiple messages are provided.

### Method
`generateText` (from `ai` SDK)

### Endpoint
N/A (Client-side SDK usage)

### Parameters
#### Request Body (Implicit via function arguments)
- **model**: `lettaCloud()` - Specifies the Letta AI model.
- **providerOptions.letta.agent.id**: (string) - Required - The unique identifier for the Letta agent.
- **prompt**: (string) - Optional - A convenience parameter that defaults to `role: 'user'`. Use for single user messages.
- **messages**: (Array<object>) - Optional - An array of message objects. Each object should have:
  - **role**: ('user' | 'system') - The role of the message sender.
  - **content**: (string) - The message content.

### Request Example
```typescript
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { generateText } from 'ai';

// Using prompt (defaults to user role)
const promptResult = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  prompt: 'What is the weather like today?', // Automatically sent as role: 'user'
});

// User message - using messages array
const userResult = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  messages: [
    { role: 'user', content: 'What is the weather like today?' }
  ],
});

// System message - for instructions or context
const systemResult = await generateText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' }
    }
  },
  messages: [
    { role: 'system', content: 'The user prefers metric units. Always provide temperature in Celsius.' }
  ],
});
```

### Response
#### Success Response (200)
- **content**: (string | Array<object>) - The generated text or structured content from the agent.

#### Response Example
(Response structure depends on the agent's output and SDK usage; typically a string for `generateText`)

### Important Notes
- Letta accepts only **one message at a time** in the `messages` array. The backend SDK processes messages sequentially.
- Using `prompt` is equivalent to sending a single message with `role: 'user'`.
- For conversation history, use the `convertToAiSdkMessage` utility (refer to "Using Existing Messages" section).
```