# Letta Provider

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:

<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
  <Tab>
    <Snippet text="pnpm add @letta-ai/vercel-ai-sdk-provider" dark />
  </Tab>
  <Tab>
    <Snippet text="npm install @letta-ai/vercel-ai-sdk-provider" dark />
  </Tab>
  <Tab>
    <Snippet text="yarn add @letta-ai/vercel-ai-sdk-provider" dark />
  </Tab>
  <Tab>
    <Snippet text="bun add @letta-ai/vercel-ai-sdk-provider" dark />
  </Tab>
</Tabs>

## 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).


## Navigation

- [Writing a Custom Provider](/v5/providers/community-providers/custom-providers)
- [Qwen](/v5/providers/community-providers/qwen)
- [Ollama](/v5/providers/community-providers/ollama)
- [A2A](/v5/providers/community-providers/a2a)
- [ACP (Agent Client Protocol)](/v5/providers/community-providers/acp)
- [Helicone](/v5/providers/community-providers/helicone)
- [FriendliAI](/v5/providers/community-providers/friendliai)
- [Portkey](/v5/providers/community-providers/portkey)
- [Built-in AI](/v5/providers/community-providers/built-in-ai)
- [Gemini CLI](/v5/providers/community-providers/gemini-cli)
- [MCP Sampling AI Provider](/v5/providers/community-providers/mcp-sampling)
- [Automatic1111](/v5/providers/community-providers/automatic1111)
- [Cloudflare Workers AI](/v5/providers/community-providers/cloudflare-workers-ai)
- [Cloudflare AI Gateway](/v5/providers/community-providers/cloudflare-ai-gateway)
- [OpenRouter](/v5/providers/community-providers/openrouter)
- [Azure AI](/v5/providers/community-providers/azure-ai)
- [Aihubmix](/v5/providers/community-providers/aihubmix)
- [SAP AI Core](/v5/providers/community-providers/sap-ai)
- [Crosshatch](/v5/providers/community-providers/crosshatch)
- [Requesty](/v5/providers/community-providers/requesty)
- [MiniMax](/v5/providers/community-providers/minimax)
- [Mixedbread](/v5/providers/community-providers/mixedbread)
- [Voyage AI](/v5/providers/community-providers/voyage-ai)
- [Jina AI](/v5/providers/community-providers/jina-ai)
- [Mem0](/v5/providers/community-providers/mem0)
- [Letta](/v5/providers/community-providers/letta)
- [Supermemory](/v5/providers/community-providers/supermemory)
- [React Native Apple](/v5/providers/community-providers/react-native-apple)
- [Anthropic Vertex](/v5/providers/community-providers/anthropic-vertex-ai)
- [Spark](/v5/providers/community-providers/spark)
- [Inflection AI](/v5/providers/community-providers/inflection-ai)
- [LangDB](/v5/providers/community-providers/langdb)
- [Zhipu AI](/v5/providers/community-providers/zhipu)
- [SambaNova](/v5/providers/community-providers/sambanova)
- [Dify](/v5/providers/community-providers/dify)
- [Sarvam](/v5/providers/community-providers/sarvam)
- [AI/ML API](/v5/providers/community-providers/aimlapi)
- [Claude Code](/v5/providers/community-providers/claude-code)


[Full Sitemap](/sitemap.md)