@upstash/agentkit-ai-sdk weekly downloads statistics

@upstash/agentkit-ai-sdk

Vercel AI SDK adapter for Upstash AgentKit — drop-ins for generateText / streamText. redis defaults to Redis.fromEnv(), so you import only from this package.

Import	Feature
createChatHistory	Durable chat history on Redis Search — save, list, and $smart-search a user's transcripts.
createMemoryTools	recall_memory + save_memory tools so the model reads and writes long-term memory.
createSearchTools	search / aggregate / count tools over a Redis Search index (this is how you do RAG).
createRateLimit	A configured Upstash Ratelimit to call before the model.
cachedTools	Memoize a map of AI SDK tools' results in Redis.

pnpm add @upstash/agentkit-ai-sdk @upstash/redis ai

Chat history

A Redis-backed ChatHistory<UIMessage>, the durable source of truth for your conversations. userId comes from your auth session; chatId is the useChat id that the client posts. Save the full transcript from your route's onFinish:

// app/api/chat/route.ts
import { convertToModelMessages, createUIMessageStreamResponse, streamText, toUIMessageStream } from "ai";
import { createChatHistory } from "@upstash/agentkit-ai-sdk";

const history = createChatHistory();

export async function POST(req: Request) {
  const userId = await getSessionUserId(req); // your auth session — never trust a client-sent id
  const { id: chatId, messages } = await req.json(); // useChat posts its chat id + the full transcript

  const result = streamText({ model, messages: convertToModelMessages(messages) });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({
      stream: result.stream,
      originalMessages: messages,
      onFinish: ({ messages }) =>
        history.saveChat({ userId, sessionId: chatId, messages, title: "New chat" }),
    }),
  });
}

To load a chat, take chatId from the page route and userId from the session, then seed useChat:

const chat = await history.getChat({ userId, sessionId: chatId }); // full transcript, or null
const chats = await history.listChats({ userId, limit: 50 }); // summaries, no messages
const hits = await history.searchChats({ userId, query: "headphones", target: "both", limit: 20 });
// client: useChat({ id: chatId, messages: chat?.messages ?? [] })

<details> <summary>Config &amp; how it's stored</summary>

createChatHistory({
  redis, // optional: defaults to Redis.fromEnv()
  prefix: "agentkit:chat", // optional: base key prefix
  indexName: "agentkit_chat", // optional: Redis Search index name (defaults to the prefix)
  ttlSeconds: 60 * 60 * 24 * 30, // optional: per-chat TTL (default: no expiry)
});

Each chat is one JSON doc at agentkit:chat:<userId>:<sessionId> (keyed per user, so two users can't collide on a sessionId), indexed over userId + sessionId (filters) and userMessages + modelMessages ($smart fuzzy text); the raw messages array rides along unindexed. saveChat overwrites the whole array (no delta merge) — useChat sends the full conversation. Other methods: getChat / deleteChat ({ userId, sessionId }), listChats / searchChats ({ userId }).

</details> <details> <summary>Security: <code>userId</code> is the tenant boundary</summary>

Every method takes a single object; userId is required, non-empty, and may not contain :. Derive it from a verified server-side auth source — the subject/user id from your auth provider (Clerk, Auth.js/NextAuth, Supabase Auth, Auth0, …) — and never from a client-supplied header, query param, or body (read it from the session in your route, not the request the browser controls). A chat can't be read or overwritten under a different userId.

</details>

Agent memory

recall_memory and save_memory tools so the model reads and writes its own long-term memory.

import { createMemoryTools } from "@upstash/agentkit-ai-sdk";
import { generateText, stepCountIs } from "ai";

const tools = createMemoryTools({ userId });

await generateText({ model, tools, stopWhen: stepCountIs(5), prompt: "What do you know about me?" });

<details> <summary>Options &amp; the <code>userId</code> tenant boundary</summary>

• userId (required) — a string, or (input, options) => string.
• redis — defaults to Redis.fromEnv().
• topK — max memories recall returns.
• minScore — BM25 relevance floor.
• recallToolName / saveToolName — override the tool names.

userId is the only tenant boundary (required, non-empty, no :). Derive it from a verified server-side auth source (Clerk, Auth.js/NextAuth, Supabase Auth, Auth0, …) — never a client-supplied value. Memories are stored at agentkit:memory:<userId>:<id>.

</details>

Search tools

search / aggregate / count over an Upstash Redis Search index; the model-facing descriptions are generated from your schema. Use these over your own documents for RAG.

import { s } from "@upstash/redis";
import { createSearchTools } from "@upstash/agentkit-ai-sdk";
import { generateText, stepCountIs } from "ai";

const schema = s.object({ name: s.string(), age: s.number(), city: s.string().noTokenize() });
const tools = createSearchTools({ schema, indexName: "users" });

await generateText({ model, tools, stopWhen: stepCountIs(5), prompt: "How many users named Ada live in London?" });

<details> <summary>Options</summary>

• schema (required) — built with s from @upstash/redis.
• redis — defaults to Redis.fromEnv().
• indexName — defaults to "agentkit:search".
• prefix — key prefix for indexed JSON docs (defaults to "<indexName>:").
• defaultLimit — default page size for search (10).

The index is created (and waitIndexing-ed) reactively on first use — no setup step.

</details>

Rate limiting…