> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciamento de threads para requisições agrupadas

> Agrupe requisições relacionadas do AI Gateway em threads de conversa para a observabilidade. As threads rotulam chamadas relacionadas em conjunto sem armazenar o histórico de mensagens.

**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](/docs/pt-BR/ai-gateway/request-metadata.md).

***

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](/docs/pt-BR/reference/threads/list-trace-threads.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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](/docs/pt-BR/ai-studio/observability/span-attributes.md).

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]
    }
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]
      }
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"],
    },
  },
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.