Threads

Reference: Thread

A Thread is a sequence of events that represent a single execution of an agent. It holds the message history, tool calls, state, and everything that happens during a run.

Creating a thread

Every call to agent.run() or agent.stream() creates or resumes a thread:

// creates a new thread (auto-generated ID)
const result = await agent.run("Hello");

// creates a new thread with explicit ID
const result = await agent.run("Hello", { threadId: "thread_abc123" });

Resuming a thread

Pass the same threadId to continue a previous execution:

// first message
await agent.run("My name is Tony", { threadId: "thread_123" });

// later - same thread, agent remembers context
await agent.run("What's my name?", { threadId: "thread_123" });
// → "Your name is Tony"

The thread's history is loaded from storage and the conversation continues.

Events and history

Everything that happens in a thread is recorded as an event:

User messages
Assistant messages
Tool calls
Tool results
Errors

Retrieve history with:

const history = await agent.threads.history("thread_123", {
  limit: 50,
  order: "desc",
});

Persistence

When storage is configured, threads are automatically persisted:

import { Kernl } from "kernl";
import { postgres } from "@kernl-sdk/pg";

const kernl = new Kernl({
  storage: {
    db: postgres({ url: process.env.DATABASE_URL }),
  },
});

Threads checkpoint at key moments:

When execution starts
After each tool call completes
When execution ends

This means you can resume a thread even after a crash or restart.

Managing threads

Access an agent's threads:

// list all threads for an agent
const threads = await agent.threads.list();

// get a specific thread
const thread = await agent.threads.get("thread_abc123");

// get thread with history
const thread = await agent.threads.get("thread_abc123", { history: true });

// update thread title
await agent.threads.update("thread_abc123", { title: "Support conversation" });

// delete a thread
await agent.threads.delete("thread_abc123");

Namespaces

Threads can be scoped to a namespace for multi-tenant applications:

await agent.run("Hello", {
  threadId: "thread_123",
  namespace: "tenant-abc",
});

Namespaces let you partition threads by tenant, environment, or product. All thread operations are scoped to the namespace.

Thread Properties

Prop

Type