Gerenciamento de threads para requisições agrupadas

Casos de uso

Visualizar todos os turnos de uma conversa com vários turnos como um único trace na observabilidade.
Depurar fluxos de trabalho de agentes inspecionando a sequência completa de requisições de ponta a ponta.
Organizar conversas de suporte para analisar padrões de resolução entre sessões.
Separar conversas simultâneas do mesmo usuário para evitar a mistura de traces.

Para conhecer todas as formas de anexar contexto a uma requisição, incluindo nome do app, identidade e metadados personalizados, consulte Request Metadata.

Agrupe requisições relacionadas em Threads de conversa para que apareçam juntas na observabilidade. As threads são um mecanismo de rotulagem e não armazenam nem injetam histórico de mensagens. O agrupamento é manual e opcional: passe o mesmo thread.id em todas as requisições que pertencem a uma conversa. Requisições de API sem ID de thread aparecem como traces individuais e nunca são agrupadas automaticamente, com uma exceção: o Claude Code e o Codex enviam seus próprios identificadores de sessão, que são detectados e agrupados automaticamente.

Início rápido

Passe thread no nível superior em /v3/router/responses. Em /v3/router/chat/completions, passe-o dentro do objeto orq como orq.thread. Para ler as threads que um workspace registrou, chame List trace threads.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Start a new conversation about AI",
    "thread": {
      "id": "conversation-abc123",
      "tags": ["ai-discussion", "user-123"]
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "Start a new conversation about AI",
  thread: {
    id: `conversation-${crypto.randomUUID()}`,
    tags: ["ai-discussion", "user-123"],
  },
});

console.log(response.output_text);

from openai import OpenAI
import os
import uuid

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Start a new conversation about AI",
    extra_body={
        "thread": {
            "id": f"conversation-{uuid.uuid4()}",
            "tags": ["ai-discussion", "user-123"],
        }
    },
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Start a new conversation about AI" }],
  orq: {
    thread: {
      id: `conversation-${crypto.randomUUID()}`,
      tags: ["ai-discussion", "user-123"],
    },
  },
});

Configuração

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único da thread para agrupar requisições
`tags`	string[]	Não	Tags de metadados para filtragem e categorização

Boas práticas

Nomenclatura consistente: use padrões previsíveis de ID de thread
Tags significativas: escolha tags que ajudem na filtragem e na análise
Gerenciamento de sessões: vincule os IDs de thread às sessões dos usuários
IDs únicos: use UUIDs ou chaves compostas para evitar sobreposição entre sessões

// Good: Descriptive and unique
const threadId = `support-${userId}-${sessionId}-${timestamp}`;

// Good: UUID-based for uniqueness
const threadId = `conversation-${crypto.randomUUID()}`;

// Avoid: Too generic
const threadId = "conversation1";

Casos de uso

Cenário	Estratégia de ID de thread	Exemplo de tags
Sessões de usuário	`user-{userId}-{sessionId}`	`["user-session", "support"]`
Tickets de suporte	`ticket-{ticketId}`	`["support", "priority-high"]`
Testes A/B	`test-{variant}-{userId}`	`["experiment", "variant-a"]`
Fluxos com várias etapas	`workflow-{processId}`	`["onboarding", "step-2"]`

Exemplos de implementação

Threads baseadas em sessão

Atribua o mesmo thread.id a todas as requisições de uma sessão para agrupá-las na observabilidade. Sua aplicação gerencia o array de mensagens de cada requisição. thread.id agrupa os turnos de uma única conversa. O atributo de span orq.session_id agrupa requisições de várias conversas para um acompanhamento de sessão mais amplo; quando uma requisição leva ambos, o ID de thread determina o agrupamento. Consulte atributos de span do Toqan Router.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

// Initialize conversation
const userId = "user-123";
const sessionId = crypto.randomUUID();
const threadId = `user-${userId}-${sessionId}`;

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "How do I reset my password?" }],
  orq: {
    thread: {
      id: threadId,
      tags: ["support", "password-reset", `user-${userId}`],
    },
  },
});

// Continue conversation
const followUp = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [
    { role: "user", content: "How do I reset my password?" },
    { role: "assistant", content: response.choices[0].message.content },
    { role: "user", content: "I didn't receive the reset email" },
  ],
  orq: {
    thread: {
      id: threadId, // Same thread ID
      tags: ["support", "email-issue", `user-${userId}`],
    },
  },
});

Suporte a várias linguagens

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Explain machine learning basics",
    "thread": {
      "id": "tech-discussion-001",
      "tags": ["education", "ml-basics", "beginner"]
    }
  }'

curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Explain machine learning basics"}],
    "orq": {
      "thread": {
        "id": "tech-discussion-001",
        "tags": ["education", "ml-basics", "beginner"]
      }
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const threadId = `conversation-${crypto.randomUUID()}`;

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "Explain machine learning basics",
  thread: {
    id: threadId,
    tags: ["education", "ml-basics", "beginner"],
  },
});

console.log(response.output_text);

import os
from openai import OpenAI
import uuid

client = OpenAI(
    api_key=os.environ["TOQAN_API_KEY"],
    base_url="https://router.toqan.ai/eu/v3/router",
)

thread_id = f"conversation-{uuid.uuid4()}"

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Explain machine learning basics",
    extra_body={
        "thread": {
            "id": thread_id,
            "tags": ["education", "ml-basics", "beginner"],
        }
    },
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const threadId = `conversation-${crypto.randomUUID()}`;

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Explain machine learning basics" }],
  orq: {
    thread: {
      id: threadId,
      tags: ["education", "ml-basics", "beginner"],
    },
  },
});

import os
from openai import OpenAI
import uuid

client = OpenAI(
    api_key=os.environ["TOQAN_API_KEY"],
    base_url="https://router.toqan.ai/eu/v3/router",
)

thread_id = f"conversation-{uuid.uuid4()}"

response = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[{"role": "user", "content": "Explain machine learning basics"}],
    extra_body={
        "orq": {
            "thread": {
                "id": thread_id,
                "tags": ["education", "ml-basics", "beginner"],
            }
        }
    },
)

Padrões avançados

Gerenciamento dinâmico de threads

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

interface ThreadConfig {
  userId: string;
  sessionType: "support" | "sales" | "general";
  priority?: "low" | "medium" | "high";
}

function createThreadId(config: ThreadConfig): string {
  const timestamp = Date.now();
  return `${config.sessionType}-${config.userId}-${timestamp}`;
}

function generateTags(config: ThreadConfig): string[] {
  const baseTags = [config.sessionType, `user-${config.userId}`];

  if (config.priority) {
    baseTags.push(`priority-${config.priority}`);
  }

  return baseTags;
}

const threadConfig: ThreadConfig = {
  userId: "user123",
  sessionType: "support",
  priority: "high",
};

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Urgent: System not responding" }],
  orq: {
    thread: {
      id: createThreadId(threadConfig),
      tags: generateTags(threadConfig),
    },
  },
});

Processamento de threads em lote

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const conversations = [
  { userId: "user1", message: "Question about billing" },
  { userId: "user2", message: "Technical support needed" },
  { userId: "user3", message: "Feature request" },
];

const responses = await Promise.all(
  conversations.map(async (conv, index) => {
    return client.chat.completions.create({
      model: "openai/gpt-5.6-sol",
      messages: [{ role: "user", content: conv.message }],
      orq: {
        thread: {
          id: `batch-${Date.now()}-${index}`,
          tags: ["batch-processing", `user-${conv.userId}`],
        },
      },
    });
  }),
);

Acompanhamento do fluxo da conversa

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

// Track conversation progression
const conversationSteps = [
  "greeting",
  "problem-identification",
  "solution-proposal",
  "confirmation",
];

async function processConversationStep(step: string, threadId: string, message: string) {
  return await client.chat.completions.create({
    model: "openai/gpt-5.6-sol",
    messages: [{ role: "user", content: message }],
    orq: {
      thread: {
        id: threadId,
        tags: ["workflow", `step-${step}`, "customer-service"],
      },
    },
  });
}

Solução de problemas

Problema	Causa	Solução
Requisições não estão sendo agrupadas	IDs de thread diferentes usados entre as requisições	Use um ID de thread consistente para todas as requisições da mesma sessão ou fluxo de trabalho
Sobreposição de threads	IDs de thread não únicos compartilhados entre sessões	Use IDs baseados em UUID ou timestamp

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Gerenciamento de threads para requisições agrupadas

Início rápido

Configuração

Boas práticas

Casos de uso

Exemplos de implementação

Threads baseadas em sessão

Suporte a várias linguagens

Padrões avançados

Gerenciamento dinâmico de threads

Processamento de threads em lote

Acompanhamento do fluxo da conversa

Solução de problemas

​Início rápido

​Configuração

​Boas práticas

​Casos de uso

​Exemplos de implementação

​Threads baseadas em sessão

​Suporte a várias linguagens

​Padrões avançados

​Gerenciamento dinâmico de threads

​Processamento de threads em lote

​Acompanhamento do fluxo da conversa

​Solução de problemas

Início rápido

Configuração

Boas práticas

Casos de uso

Exemplos de implementação

Threads baseadas em sessão

Suporte a várias linguagens

Padrões avançados

Gerenciamento dinâmico de threads

Processamento de threads em lote

Acompanhamento do fluxo da conversa

Solução de problemas