Skip to main content
A thread is a sequence of agent runs that belong to the same conversation or session. Linking them with a shared threadId / thread_id lets you filter and inspect the full conversation arc in the Lemma dashboard.

​
Passing a thread ID

Pass threadId / thread_id as the second argument when calling the wrapped agent: 
const myAgent = agent("chat-agent", async (input: string) => {
  return await handleTurn(input);
});

// Link this run to a thread
const { result, runId } = await myAgent(
  input,
  { threadId: "chat-session-abc" }
);
The SDK stores the value as lemma.thread_id on the root span. Empty and whitespace-only strings are ignored — the attribute is omitted entirely in that case.

​
Where thread IDs come from

Use any stable identifier that represents a conversation:
  • A session ID from the user’s browser cookie
  • A chat room or channel ID from your database
  • A unique conversation UUID you generate at the start of a session
await myAgent(
  { userMessage: req.body.message },
  { threadId: req.session.conversationId }
);

​
How threads appear in Lemma

Runs that share the same non-empty lemma.thread_id are grouped in the traces list with a Thread · N indicator, where N is the number of runs in that thread. You can click any run to see the full conversation history.

​
Python context manager

The context manager form does not accept a second argument. To pass a thread ID in context manager mode, set the attribute directly on the span: 
async with agent("chat-agent", input=user_message) as run:
    run.span.set_attribute("lemma.thread_id", session_id)
    result = await call_llm(user_message)
    run.complete(result)

​
Next Steps

  • Overview — how agent() works and what it captures
  • Custom attributes — attach user ID, session ID, and other business metadata to runs