Log conversations | Opik Documentation | Opik Documentation

Understanding Threads

Threads in Opik are collections of traces that are grouped together using a unique thread_id. This is particularly useful for:

The thread_id is a user-defined identifier that must be unique per project. All traces with the same thread_id will be grouped together and displayed as a single conversation thread in the Opik UI.

Logging conversations

You can log chat conversations by specifying the thread_id parameter when using either the low level SDK, Python decorators, or integration libraries:

import { Opik } from "opik";

const client = new Opik({
  apiUrl: "https://www.comet.com/opik/api", // Only required if you are using Opik Cloud
  apiKey: "your-api-key",
  projectName: "your-project-name",
  workspaceName: "your-workspace-name", // Optional
});

const threadId = "your-thread-id"; // any unique string per conversation

// Option A: set on trace creation
const trace = client.trace({
    name: "chat turn",
    input: { user: "Hi there" },
    output: { assistant: "Hello!" },
    threadId
});

The input to each trace will be displayed as the user message while the output will be displayed as the AI assistant response.

Thread ID Best Practices

Generating Thread IDs

Choose a thread ID strategy that fits your application:

import uuid
import opik

# Generate unique thread ID per user session
user_id = "user_12345"
session_start_time = "2024-01-15T10:30:00Z"
thread_id = f"{user_id}-{session_start_time}"

@opik.track
def process_user_message(message, user_id):
    return "Response to: " + message

process_user_message("What is Opik ?", opik_args={"trace": {"thread_id": thread_id}})

Integration-Specific Threading

Different integrations handle thread IDs in various ways:

from opik.integrations.langchain import OpikTracer

# Set thread_id at tracer level - applies to all traces
opik_tracer = OpikTracer(
    project_name="my-chatbot",
    thread_id="conversation-123"
)

# Or pass dynamically via metadata
chain.invoke(
    {"input": "Hello"},
    config={
        "callbacks": [opik_tracer],
        "metadata": {"thread_id": "dynamic-conversation-456"}
    }
)

Reviewing conversations

Conversations can be viewed at a project level in the threads tab. All conversations are tracked and by clicking on the thread ID you will be able to view the full conversation.

The thread view supports markdown making it easier for you to review the content that was returned to the user. If you would like to dig in deeper, you can click on the View trace button to deepdive into how the AI assistant response was generated.

Scoring conversations

You can assign conversation-level feedback scores to threads at any time. Threads are aggregated traces that are created when tracking agents or simply traces interconnected by a thread_id.

In the conversation list, you can see the feedback scores associated to each thread.

You can also tag a thread and add comments to it. This is useful to add additional context during the review process or investigate a specific conversation.

Thread Online Scoring Rule Cooldown Period

For thread-level online evaluation rules (automatic scoring), Opik waits for a "cooldown period" after the last activity in a thread before running the rules. This gives conversations time to settle before automatic evaluation.

By default, the cooldown period is 15 minutes. You can change this value by setting the OPIK_TRACE_THREAD_TIMEOUT_TO_MARK_AS_INACTIVE environment variable (if you are using the Opik self-hosted version). On cloud, you can change this setting at workspace level under "Thread online scoring rule cooldown period".

Behavior When Adding Traces to Existing Threads

When a new trace is added to an existing thread, the following happens:

Advanced Thread Features

Filtering and Searching Threads

You can filter threads using the thread_id field in various Opik features:

In Data Export

When exporting data, you can filter by thread_id using these operators:

In Thread Evaluation

You can evaluate entire conversation threads using the thread evaluation features. This is particularly useful for:

Thread Management

Threads can have traces added to them at any time, and you can add feedback scores, comments, and tags to threads regardless of whether new traces are still being added.

Programmatic Thread Management

You can also manage threads programmatically using the Opik SDK:

import opik

# Initialize client
client = opik.Opik()

# Search for threads by various criteria
threads = client.search_traces(
    project_name="my-chatbot",
    filter_string='thread_id contains "user-session"'
)

# Get specific thread content
for trace in threads:
    if trace.thread_id:
        thread_content = client.get_trace_content(trace.id)
        print(f"Thread: {trace.thread_id}")
        print(f"Input: {thread_content.input}")
        print(f"Output: {thread_content.output}")

# Add feedback scores to thread traces
for trace in threads:
    trace.log_feedback_score(
        name="conversation_quality",
        value=0.8,
        reason="Good multi-turn conversation flow"
    )

Next steps

Once you have added observability to your multi-turn agent, why not:

  1. Run offline multi-turn conversation evaluation
  2. Create online evaluation rules to score your multi-turn conversations in production