Conversation threads in traces - Orq.ai Documentation

Threads group related AI Gateway calls into a single conversation view, letting you trace multi-turn interactions across your Deployments and Agents.

Viewing Threads

To view Threads, open Threads in the Observability section of the sidebar.

The Threads Overview, dates, duration, traces, and costs are available to see.

By selecting a Thread, you can then visualize the conversation.

Thread conversation view showing user messages and assistant replies as chat bubbles with avatars — The conversation view of a Thread.

Adding a Generation to a Thread

Threads are configured at runtime when using the Invoke API for Deployments, or when invoking an Agent. The API receives the following extra parameter:

Conversations will be grouped by Thread ID Tags can be used to filter and search Threads in the panel.

{
  "thread": {
  "id": "<unique-thread-id>",
    "tags": ["tag1", "tag2"]
  }
}

Deployment Invoke
Agent

import os
from orq_ai_sdk import Orq

client = Orq(
  api_key=os.environ.get("ORQ_API_KEY", "<insert your api key here>"),
)

generation = client.deployments.invoke(
  key="deployment-demo",
  context={"environments": ["production"]},
  metadata={"custom-field-name": "custom-metadata-value"},
  thread={
    "id": "<unique-thread-id>",
    "tags": ["tag1", "tag2"]
  }
)

print(generation.choices[0].message.content)

import { Orq } from '@orq-ai/node';

const client = new Orq({
  apiKey: '<insert orq api key>',
});

const deployment = await client.deployments.invoke({
  key: "deployment-demo",
  context: { environments: ["production"] },
  metadata: { "custom-field-name": "custom-metadata-value" },
  thread: {
    id: "<unique-thread-id>",
    tags: ["tag1", "tag2"]
  }
});

curl 'https://my.orq.ai/v2/deployments/invoke' \
-H 'Authorization: Bearer <insert Orq API key>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "key": "deployment-demo",
  "context": { "environments": [] },
  "metadata": { "custom-field-name": "custom-metadata-value" },
  "thread": { "id": "<unique-thread-id>", "tags": ["tag1", "tag2"] }
}' \
--compressed

import os
from orq_ai_sdk import Orq

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    response = orq.responses.create(
        model="agent/agent-demo",
        input="Hello!",
        thread={
            "id": "<unique-thread-id>",
            "tags": ["tag1", "tag2"]
        }
    )

    print(response)

import { Orq } from '@orq-ai/node';

const orq = new Orq({ apiKey: process.env['ORQ_API_KEY'] ?? '' });

const response = await orq.responses.create({
  model: 'agent/agent-demo',
  input: 'Hello!',
  thread: {
    id: '<unique-thread-id>',
    tags: ['tag1', 'tag2']
  }
});

curl --request POST \
--url 'https://my.orq.ai/v3/router/responses' \
-H 'Authorization: Bearer <insert Orq API key>' \
-H 'Content-Type: application/json' \
--data '{
  "model": "agent/agent-demo",
  "input": "Hello!",
  "thread": { "id": "<unique-thread-id>", "tags": ["tag1", "tag2"] }
}'

AI Gateway Thread Management

Full API reference for attaching threads to AI Gateway Deployment and Agent invocations.