Threads

Threads, an AI Primitive by Langbase, allows you to manage conversation history and context. They are essential for building conversational applications that require context management and organization of conversation threads.

Threads help you maintain a coherent conversation flow, making it easier to build applications that require context-aware interactions.



In this guide, we'll use the Langbase SDK to interact with the Threads API:


Step #1

Every request you send to Langbase needs an API key. This guide assumes you already have one. If not, please check the instructions below.


Step #2

Create a new directory for your project and navigate to it.

Project setup

mkdir conversation-app && cd conversation-app

Initialize the project

Create a new Node.js project.

Initialize project

npm init -y

Install dependencies

You will use the Langbase SDK to work with threads and dotenv to manage environment variables.

Install dependencies

npm i langbase dotenv

Create an env file

Create a .env file in the root of your project and add your Langbase API key:

.env

LANGBASE_API_KEY=your_api_key_here

Step #3

Let's create a file named create-thread.ts to demonstrate how to create a new thread:

create-thread.ts

import 'dotenv/config'; import { Langbase } from 'langbase'; const langbase = new Langbase({ apiKey: process.env.LANGBASE_API_KEY!, }); async function main() { // Create a new thread with initial messages and metadata const thread = await langbase.threads.create({ // Metadata for organization and filtering metadata: { userId: "user-456", topic: "billing-question", channel: "website" }, // Initial messages to start the conversation messages: [ { role: "system", content: "You are a helpful customer support agent. Be concise and friendly in your responses." }, { role: "user", content: "Hi, I have a question about my recent bill." } ] }); console.log('Thread created:', thread); } main()

Run the script to create your first thread:

Run the script

npx tsx create-thread.ts

You should see output similar to this:

{ "id": "06d1be7e-94fb-4219-b983-931089680ebb", "object": "thread", "created_at": 1714322048, "metadata": { "userId": "user-456", "topic": "billing-question", "channel": "website" } }

Step #4

Now let's create a file named append-messages.ts to add more messages to our thread:

append-messages.ts

import 'dotenv/config'; import { Langbase } from 'langbase'; const langbase = new Langbase({ apiKey: process.env.LANGBASE_API_KEY!, }); async function main() { const threadId = "06d1be7e-94fb-4219-b983-931089680ebb"; // Add an assistant response and a follow-up user message const messages = await langbase.threads.append({ threadId, messages: [ { role: "assistant", content: "I'd be happy to help with your billing question. Could you please provide your account number or the specific charge you're inquiring about?" }, { role: "user", content: "My account number is AC-9876. I was charged twice for the same service on April 15.", metadata: { timestamp: new Date().toISOString(), device: "mobile" } } ] }); console.log(`Added ${messages.length} messages to thread ${threadId}`); console.log('Messages:', messages); } main()

Run the script to append messages to your thread:

Run the script

npx tsx append-messages.ts

Step #5

Let's create a file named list-messages.ts to retrieve all messages in our thread:

list-messages.ts

import 'dotenv/config'; import { Langbase } from 'langbase'; const langbase = new Langbase({ apiKey: process.env.LANGBASE_API_KEY!, }); async function main() { const threadId = "06d1be7e-94fb-4219-b983-931089680ebb"; // List all messages in the thread const messages = await langbase.threads.messages.list({ threadId }); console.log(`Retrieved ${messages.length} messages from thread ${threadId}`); // Display the conversation messages.forEach(msg => { console.log(`[${msg.role}]: ${msg.content}`); }); } main()

Run the script to see all messages in your thread:

Run the script

npx tsx list-messages.ts

The output should show the entire conversation history in chronological order:

Retrieved 4 messages from thread 06d1be7e-94fb-4219-b983-931089680ebb [system]: You are a helpful customer support agent. Be concise and friendly in your responses. [user]: Hi, I have a question about my recent bill. [assistant]: I'd be happy to help with your billing question. Could you please provide your account number or the specific charge you're inquiring about? [user]: My account number is AC-9876. I was charged twice for the same service on April 15.