---
title: Letta
description: Learn how to use the Letta provider with the AI SDK.
url: "https://ai-sdk.dev/v5/providers/community-providers/letta"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The [Letta AI SDK provider](https://github.com/letta-ai/vercel-ai-sdk-provider) allows you to use Letta agents with the AI SDK.

Features include:

- Persistent and long-term memory
- Access to both agent-level and model-level reasoning messages with source attribution
- Support for custom agent-configured tools and MCP (Model Context Protocol)
- Agent-managed filesystem operations with tool-based file access
- Built-in utilities to convert between Letta and AI SDK message formats
- [Every Letta Send Message API feature](https://docs.letta.com/api-reference/agents/messages/create-stream), like [Long-Running Agent Executions](https://docs.letta.com/guides/agents/long-running)

## Supported Models

See the [Letta documentation](https://docs.letta.com/connecting-model-providers/supported-models) for the complete list of supported models. For models not on the list, you can try configuring Letta to use [OpenAI proxy](https://docs.letta.com/guides/server/providers/openai-proxy).

## Setup

You can install the Letta provider with:

#### pnpm

```
pnpm add @letta-ai/vercel-ai-sdk-provider
```

#### npm

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

#### yarn

```
yarn add @letta-ai/vercel-ai-sdk-provider
```

#### bun

```
bun add @letta-ai/vercel-ai-sdk-provider
```

## Provider Instance

You can import the provider instance `lettaCloud` or `lettaLocal` from `@letta-ai/vercel-ai-sdk-provider`:

```ts
// For cloud users
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';

// For self-hosted users
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';

// Create a custom Letta provider
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';

const letta = createLetta({
  baseUrl: '<your-base-url>',
  token: '<your-access-token>',
});
```

## Basic Usage

Get your API key from the [Letta dashboard](https://app.letta.com/api-keys).

```bash
# .env
LETTA_API_KEY=your-letta-api-key
```

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

const result = await generateText({
  model: lettaCloud(), // Model configuration (LLM, temperature, etc.) is managed through your Letta agent
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' },
    },
  },
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

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

## Advanced Usage

### Provider Options

You can configure Letta-specific settings using the `providerOptions.letta` parameter:

```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,
        includePings: true,
        streamTokens: true,
      },
      timeoutInSeconds: 300,
    },
  },
  prompt: 'Tell me a story about a robot learning to paint',
});
```

#### Agent Configuration

Configure agent-specific parameters for message creation. These settings apply to both streaming and non-streaming operations.

Available options:

- `id` (`string`, required): The ID of your Letta agent
- `maxSteps` (`number`): Maximum number of agent execution steps
- `includePings` (`boolean`): Whether to include ping messages in the stream
- `streamTokens` (`boolean`): Enable token-by-token streaming
- `background` (`boolean`): Enable background execution for long-running operations
- Additional parameters available in the [Letta API documentation](https://docs.letta.com/api-reference/agents/messages/create-stream)

#### Timeout Configuration

**Type:** `number`

**Default:** `1000`

Set the maximum wait time (in seconds) for agent responses. This is important for long-running agent operations or when working with complex reasoning chains.

```typescript
const result = streamText({
  model: lettaCloud(),
  providerOptions: {
    letta: {
      agent: { id: 'your-agent-id' },
      timeoutInSeconds: 300, // Wait up to 5 minutes
    },
  },
  prompt: 'Process this complex task...',
});
```

## Custom Tools and MCP

Letta agents support custom tools and MCP (Model Context Protocol) servers through provider-executed tools. Once [ configured on your Letta agent ](https://docs.letta.com/guides/agents/custom-tools), you can include them in your requests using `letta.tool()` and Letta handles tool execution.

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

// Use with streaming
const result = streamText({
  model: lettaCloud(),
  tools: {
    web_search: lettaCloud.tool('web_search'),
    memory_insert: lettaCloud.tool('memory_insert'),
    memory_replace: lettaCloud.tool('memory_replace'),
    core_memory_append: lettaCloud.tool('core_memory_append'),
    my_custom_tool: lettaCloud.tool('my_custom_tool'),
    // Optionally provide description and schema (placeholders only - execution handled by Letta)
    typed_query: lettaCloud.tool('typed_query', {
      description: 'Query with typed parameters',
      inputSchema: z.object({
        query: z.string(),
      }),
    }),
  },
  providerOptions: {
    letta: {
      agent: { id: agentId },
    },
  },
  prompt: 'Tell me a story about a robot learning to paint',
});
```

## Using other Letta Client Functions

The `vercel-ai-sdk-provider` extends the [@letta-ai/letta-client](https://www.npmjs.com/package/@letta-ai/letta-client), you can access the operations directly by using `lettaCloud.client` or `lettaLocal.client` or your custom generated `letta.client`

```ts
// with Letta Cloud
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';

lettaCloud.client.agents.list();

// with Letta Local
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';

lettaLocal.client.agents.list();
```

### More Information

For more information on the Letta API, please refer to the [Letta API documentation](https://docs.letta.com/api-reference/overview).

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)