--- title: Letta description: Learn how to use the Letta provider with the AI SDK. --- # 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: ## 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: '', 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).