Langbase

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.

Quickstart: Managing Conversations with Threads

Let's get started

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

Step #1Generate Langbase API key

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 #2Setup your project

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 #3Create a new thread

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 #4Add messages to a thread

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 #5Retrieve thread messages

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.

Next Steps