Skip to content

Commit 3a8fad0

Browse files
vercel-ai-sdk[bot]shelleyphamnicoalbanese
authored
Backport: docs: update Letta provider page (#10146)
This is an automated backport of #8880 to the release-v5.0 branch. FYI @shelleypham Co-authored-by: Shelley Pham <shelleypham@users.noreply.github.com> Co-authored-by: Nico Albanese <49612682+nicoalbanese@users.noreply.github.com> Co-authored-by: nicoalbanese <gcalbanese96@gmail.com>
1 parent 392c422 commit 3a8fad0

File tree

1 file changed

+131
-39
lines changed

1 file changed

+131
-39
lines changed

‎content/providers/03-community-providers/71-letta.mdx‎

Lines changed: 131 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,28 @@
11
---
2-
title: 'Letta'
3-
description: 'Learn how to use the Letta AI SDK provider for the AI SDK.'
2+
title: Letta
3+
description: Learn how to use the Letta provider with the AI SDK.
44
---
55

66
# Letta Provider
77

8-
<Note type="warning">
9-
This community provider is not yet compatible with AI SDK 5. Please wait for
10-
the provider to be updated or consider using an [AI SDK 5 compatible
11-
provider](/providers/ai-sdk-providers).
12-
</Note>
8+
The [Letta AI SDK provider](https://github.com/letta-ai/vercel-ai-sdk-provider) allows you to use Letta agents with the AI SDK.
139

14-
The [Letta AI-SDK provider](https://github.com/letta-ai/vercel-ai-sdk-provider) is the official provider for the [Letta](https://docs.letta.com) platform. It allows you to integrate Letta's AI capabilities into your applications using the Vercel AI SDK.
10+
Features include:
11+
12+
- Persistent and long-term memory
13+
- Access to both agent-level and model-level reasoning messages with source attribution
14+
- Support for custom agent-configured tools and MCP (Model Context Protocol)
15+
- Agent-managed filesystem operations with tool-based file access
16+
- Built-in utilities to convert between Letta and AI SDK message formats
17+
- [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)
18+
19+
## Supported Models
20+
21+
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).
1522

1623
## Setup
1724

18-
The Letta provider is available in the `@letta-ai/vercel-ai-sdk-provider` module. You can install it with:
25+
You can install the Letta provider with:
1926

2027
<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
2128
<Tab>
@@ -34,62 +41,147 @@ The Letta provider is available in the `@letta-ai/vercel-ai-sdk-provider` module
3441

3542
## Provider Instance
3643

37-
You can import the default provider instance `letta` from `@letta-ai/vercel-ai-sdk-provider`:
44+
You can import the provider instance `lettaCloud` or `lettaLocal` from `@letta-ai/vercel-ai-sdk-provider`:
3845

3946
```ts
40-
import { letta } from '@letta-ai/vercel-ai-sdk-provider';
41-
```
47+
// For cloud users
48+
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
49+
50+
// For self-hosted users
51+
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';
52+
53+
// Create a custom Letta provider
54+
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';
4255

43-
## Quick Start
56+
const letta = createLetta({
57+
baseUrl: '<your-base-url>',
58+
token: '<your-access-token>',
59+
});
60+
```
4461

45-
### Using Letta Cloud (https://api.letta.com)
62+
## Basic Usage
4663

47-
Create a file called `.env.local` and add your [API Key](https://app.letta.com/api-keys)
64+
Get your API key from the [Letta dashboard](https://app.letta.com/api-keys).
4865

49-
```text
50-
LETTA_API_KEY=<your_api_key>
66+
```bash
67+
# .env
68+
LETTA_API_KEY=your-letta-api-key
5169
```
5270

53-
```ts
71+
```typescript
5472
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
5573
import { generateText } from 'ai';
5674

57-
const { text } = await generateText({
58-
model: lettaCloud('your_agent_id'),
75+
const result = await generateText({
76+
model: lettaCloud(), // Model configuration (LLM, temperature, etc.) is managed through your Letta agent
77+
providerOptions: {
78+
letta: {
79+
agent: { id: 'your-agent-id' },
80+
},
81+
},
5982
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
6083
});
84+
85+
console.log(result.text);
6186
```
6287

63-
### Local instances (http://localhost:8283)
88+
## Advanced Usage
6489

65-
```ts
66-
import { lettaLocal } from '@letta-ai/vercel-ai-sdk-provider';
67-
import { generateText } from 'ai';
90+
### Provider Options
6891

69-
const { text } = await generateText({
70-
model: lettaLocal('your_agent_id'),
71-
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
92+
You can configure Letta-specific settings using the `providerOptions.letta` parameter:
93+
94+
```typescript
95+
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
96+
import { streamText } from 'ai';
97+
98+
const result = streamText({
99+
model: lettaCloud(),
100+
providerOptions: {
101+
letta: {
102+
agent: {
103+
id: 'your-agent-id',
104+
maxSteps: 100,
105+
includePings: true,
106+
streamTokens: true,
107+
},
108+
timeoutInSeconds: 300,
109+
},
110+
},
111+
prompt: 'Tell me a story about a robot learning to paint',
72112
});
73113
```
74114

75-
### Custom setups
115+
#### Agent Configuration
76116

77-
```ts
78-
import { createLetta } from '@letta-ai/vercel-ai-sdk-provider';
79-
import { generateText } from 'ai';
117+
Configure agent-specific parameters for message creation. These settings apply to both streaming and non-streaming operations.
80118

81-
const letta = createLetta({
82-
baseUrl: '<your_base_url>',
83-
token: '<your_access_token>',
119+
Available options:
120+
121+
- `id` (`string`, required): The ID of your Letta agent
122+
- `maxSteps` (`number`): Maximum number of agent execution steps
123+
- `includePings` (`boolean`): Whether to include ping messages in the stream
124+
- `streamTokens` (`boolean`): Enable token-by-token streaming
125+
- `background` (`boolean`): Enable background execution for long-running operations
126+
- Additional parameters available in the [Letta API documentation](https://docs.letta.com/api-reference/agents/messages/create-stream)
127+
128+
#### Timeout Configuration
129+
130+
**Type:** `number`
131+
132+
**Default:** `1000`
133+
134+
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.
135+
136+
```typescript
137+
const result = streamText({
138+
model: lettaCloud(),
139+
providerOptions: {
140+
letta: {
141+
agent: { id: 'your-agent-id' },
142+
timeoutInSeconds: 300, // Wait up to 5 minutes
143+
},
144+
},
145+
prompt: 'Process this complex task...',
84146
});
147+
```
85148

86-
const { text } = await generateText({
87-
model: letta('your_agent_id'),
88-
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
149+
## Custom Tools and MCP
150+
151+
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.
152+
153+
```typescript
154+
import { streamText } from 'ai';
155+
import { z } from 'zod';
156+
import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
157+
158+
// Use with streaming
159+
const result = streamText({
160+
model: lettaCloud(),
161+
tools: {
162+
web_search: lettaCloud.tool('web_search'),
163+
memory_insert: lettaCloud.tool('memory_insert'),
164+
memory_replace: lettaCloud.tool('memory_replace'),
165+
core_memory_append: lettaCloud.tool('core_memory_append'),
166+
my_custom_tool: lettaCloud.tool('my_custom_tool'),
167+
// Optionally provide description and schema (placeholders only - execution handled by Letta)
168+
typed_query: lettaCloud.tool('typed_query', {
169+
description: 'Query with typed parameters',
170+
inputSchema: z.object({
171+
query: z.string(),
172+
}),
173+
}),
174+
},
175+
providerOptions: {
176+
letta: {
177+
agent: { id: agentId },
178+
},
179+
},
180+
prompt: 'Tell me a story about a robot learning to paint',
89181
});
90182
```
91183

92-
### Using other Letta Client Functions
184+
## Using other Letta Client Functions
93185

94186
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`
95187

@@ -107,4 +199,4 @@ lettaLocal.client.agents.list();
107199

108200
### More Information
109201

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

0 commit comments

Comments
 (0)