Replaying an Assistants-API Thread Through the Chat Completions Endpoint on One Key

Why Replay a Thread?

Many teams prototype with the OpenAI Assistants API, which manages conversation state, tool invocations, and file attachments on the server side. When moving to a multi-model aggregator that exposes only an OpenAI-compatible chat completions endpoint, you need to reconstruct the conversation as a flat list of messages. This is also useful for debugging, auditing, or migrating threads between providers.

The aggregator supports a single API key for multiple models (Claude, GPT, DeepSeek, Qwen, GLM, Kimi) and uses the standard chat completions format. The challenge is that the Assistants API stores more than just text: it includes tool calls, tool outputs, and file references. Below is a conceptual approach to flattening and replaying.

Understand the Assistants Thread Structure

A typical Assistants thread consists of:

• Messages: user and assistant text messages, with metadata like role and content.
• Runs: execution records that may contain tool calls (e.g., function calls, code interpreter, retrieval).
• Steps: detailed steps within a run, including tool inputs and outputs.
• Attachments: file IDs attached to messages or used by tools.

When replaying, you want to convert this into a linear sequence of chat messages. The chat completions API expects a messages array where each message has a role (system, user, assistant, tool) and content.

Flatten Thread Messages into Chat Messages

Start by retrieving the thread messages in chronological order. Each message has a role and content parts. For plain text, map directly:

• User messages → {"role": "user", "content": "..."}
• Assistant messages → {"role": "assistant", "content": "..."}

If a message contains multiple content parts (e.g., text and image), you can concatenate text and handle images separately (see file references below).

Handle Tool Calls and Outputs

The Assistants API records tool calls within runs. To replay, you need to convert these into the chat completions tool calling format:

• Assistant tool call: When the assistant decides to call a function, the original run step includes the function name and arguments. In chat completions, this is represented as an assistant message with a tool_calls array.
• Tool output: The result of the function execution is a message with role tool, containing the toolcallid and the output content.

For example, if the thread shows the assistant called get_weather with {"location": "Paris"} and received a response, you would insert:

1. An assistant message with tool_calls containing that call.
2. A tool message with the result.

This preserves the conversation flow so the model can see what was called and what was returned.

Resolve File References

The Assistants API allows attaching files to messages or using them in retrieval. The chat completions endpoint does not accept file IDs directly; you must convert them to content the model can consume.

Options:

• Text extraction: If the file is text-based, extract its content and include it as part of a user message (e.g., "Here is the document content: ...").
• Image files: For vision-capable models, you can include images as base64-encoded data or URLs in the message content (using the image_url format).
• Retrieval results: If the assistant used retrieval, the run steps may include the retrieved text snippets. Include those snippets as context in a system or user message.

Always check the model's capabilities: not all backends support vision or long context. Flattening to text is the most portable approach.

Verify Backend Acceptance

Different backends (Claude, GPT, DeepSeek, Qwen, GLM, Kimi) may have slight variations in how they handle tool calls, system messages, or content formats. After flattening, test with each model you intend to use:

• Send a minimal replay (e.g., a short thread with one tool call) and check for errors.
• Confirm that the model correctly interprets tool call messages and responds appropriately.
• For file references, ensure the model accepts the content format (e.g., base64 images may not be supported by all).

Since the aggregator uses a single API key and OpenAI-compatible interface, you can switch models by changing the model parameter. Use the same flattened messages across backends to compare behavior.

Practical Tips

• Preserve order: Flatten messages and tool events in the exact chronological order they occurred.
• Include system prompts: If the original assistant had instructions, prepend them as a system message.
• Truncate if needed: Very long threads may exceed context limits; consider summarizing earlier parts.
• Log the transformation: Keep a record of how you flattened the thread for debugging.

By following these steps, you can replay Assistants-API threads through the chat completions endpoint on a single key, enabling multi-model evaluation and migration without losing conversational context.