Assistants, threads and runs

Why this exists

Plain chat completions are stateless. You send the full message list on every call and you own the history. That is fine for one-shot work and it is the right tool most of the time. The stateful model handles the other case. You get a long-lived agent that holds a growing conversation, calls tools across many turns and stays addressable by a stable id, so a browser, a worker or a webhook handler can all drive the same session.

Ringside implements the OpenAI Assistants object model on the wire so the official OpenAI SDKs drive it unchanged. Point base_url at https://api.fightclub.pro/v1, send your ko_ key as Authorization: Bearer, prefix your model with fc: and client.beta.assistants, client.beta.threads and client.beta.threads.runs work as written. Under the hood a thread is a thin alias over a Ringside conversation, so the same spend attribution, customer isolation and metering you get on chat completions apply to every run.

Assistant

Reusable, stateless config. Holds the model, system instructions, the tools the agent may call, tool_resources (e.g. vector stores), sampling knobs and metadata. It carries no conversation. Id prefix asst_.

Thread

A message container. Append user and assistant messages to it; it grows up to a hard cap of 5,000 messages. Carries metadata that attributes its spend to a customer. Id prefix thread_.

Run

One execution of an assistant against a thread. The run reads the thread, calls the model, dispatches tools and writes the model's replies back as new thread messages. It moves through a lifecycle and may pause for you to supply tool outputs. Id prefix run_.

assistant (asst_)        thread (thread_)
   reusable config   +     message history
         \                     /
          \                   /
           v                 v
              run (run_)
         executes one on the other,
         appends replies to the thread

Assistants

Create an assistant once and reuse it across many threads. The config is the contract for every run that names it.

curl https://api.fightclub.pro/v1/assistants \
  -H "Authorization: Bearer ko_REPLACE_WITH_64_HEX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fc:openai/gpt-4o-mini",
    "name": "billing-support",
    "instructions": "You answer billing questions. Cite the docs you retrieve.",
    "tools": [
      {"type": "file_search"},
      {"type": "function", "function": {
        "name": "lookup_invoice",
        "description": "Fetch an invoice by id",
        "parameters": {"type": "object", "properties": {"invoice_id": {"type": "string"}}, "required": ["invoice_id"]}
      }}
    ],
    "tool_resources": {"file_search": {"vector_store_ids": ["vs_billing_kb"]}},
    "temperature": 0.2
  }'

Threads and spend attribution

A thread is the conversation. Create it empty or seed it with initial messages, then append more with POST /v1/threads/{id}/messages. Messages carry a role of user or assistant, and content is either a plain string or the OpenAI array form [{type:"text", text:{value}}]. Both are accepted and normalised on the way in.

Every thread is backed by a Ringside conversation, and that conversation must belong to a customer. How the customer is chosen depends on what you send and how you authenticated:

This matters because run cost lands on the resolved customer, not on a header passed per run. Decide attribution at thread-create time. If you are reselling, set metadata.customer_external_id to your own end-customer id so margin and usage reports line up per tenant. Thread metadata follows the same caps as everywhere else: 16 keys, 64-char keys, 512-char values.

curl https://api.fightclub.pro/v1/threads \
  -H "Authorization: Bearer ko_REPLACE_WITH_64_HEX" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"customer_id": "cus_42"},
    "messages": [
      {"role": "user", "content": "Why was I charged twice in March?"}
    ]
  }'

Runs and the lifecycle

Creating a run kicks an in-process executor. The run reads the thread, calls the model and writes the reply back as a new assistant message on the thread. If the model asks to call a function the run does not finish. It parks in requires_action and waits for you. One state machine covers every path.

                          +-------------+
  create run  ----------->  |   queued    |
                          +------+------+
                                 |
                                 v
                          +-------------+        model returns content
                +-------> | in_progress | -----------------------------> completed
                |         +------+------+
                |                |  model emits function tool_calls
  submit_tool_  |                v
  outputs       |        +------------------+
  (loop)        +------- | requires_action  |
                         +------------------+

   any non-terminal state may also end in:
     cancel  -> cancelling -> cancelled   (in-flight)
     cancel  -> cancelled                 (queued / requires_action)
     error   -> failed
     >10 min -> expired

The function-calling loop

This is the core interaction. Your code and the run trade control until the model has everything it needs.

1. 01POST a run. It goes queued then in_progress and calls the model.
2. 02The model decides it needs a tool and emits function tool_calls. The run writes those calls to the thread, transitions to requires_action, releases the thread lock and returns.
3. 03You poll GET /v1/threads/{tid}/runs/{rid} (or read the streamed event) and see status:"requires_action". The work to do is in required_action.submit_tool_outputs.tool_calls, each with an id, a function name and JSON arguments.
4. 04You run each tool in your own code and collect a string output per tool_call_id.
5. 05POST /submit_tool_outputs with {tool_outputs:[{tool_call_id, output}]}. The run re-acquires the lock, appends your outputs as tool-role messages and goes back to queued.
6. 06The executor re-enters the loop with the new context. The model either emits more tool calls (back to step 2) or returns a final answer and the run goes completed.

# 1. Create the run
RUN=$(curl -s https://api.fightclub.pro/v1/threads/thread_abc/runs \
  -H "Authorization: Bearer ko_REPLACE_WITH_64_HEX" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id":"asst_billing"}')
# RUN.status == "queued"

# 2. Poll until it leaves a non-terminal state
curl -s https://api.fightclub.pro/v1/threads/thread_abc/runs/run_xyz \
  -H "Authorization: Bearer ko_REPLACE_WITH_64_HEX"
# -> {"status":"requires_action",
#     "required_action":{"type":"submit_tool_outputs",
#       "submit_tool_outputs":{"tool_calls":[
#         {"id":"call_9","type":"function",
#          "function":{"name":"lookup_invoice","arguments":"{\"invoice_id\":\"inv_312\"}"}}
#       ]}}}

# 3. Run lookup_invoice yourself, then submit the output
curl -s https://api.fightclub.pro/v1/threads/thread_abc/runs/run_xyz/submit_tool_outputs \
  -H "Authorization: Bearer ko_REPLACE_WITH_64_HEX" \
  -H "Content-Type: application/json" \
  -d '{"tool_outputs":[{"tool_call_id":"call_9","output":"{\"total\":42.00,\"status\":\"paid\"}"}]}'
# -> run goes back to "queued"; poll again until "completed"

Both create-run and submit-tool-outputs also accept "stream": true, returning a text/event-stream of thread.run.* snapshots instead of a single object, so you can drive the loop without polling. The terminal events are thread.run.completed, thread.run.requires_action, thread.run.failed, thread.run.cancelled and thread.run.expired.

file_search for RAG inside a run

Attach a vector store to an assistant or a thread and the model can retrieve from it mid-run. Declare the stores under tool_resources.file_search.vector_store_ids, which is what the OpenAI SDKs send, on the assistant, on the thread or both. The run unions every declared store id and isolates retrieval to your own tenant; a cross-tenant store id simply matches nothing.

When file_search runs, the model gets chunk citations back as a tool message and continues. If the store was created with graphrag_enabled: true, the retrieval also returns a facts[] array of {subject, predicate, object} relationships alongside the chunks, so the model can reason over a knowledge graph as well as raw text. See RAG and vector stores for ingestion, embedding models, sealing and the graph build.

Errors and edge cases

Two timing rules bite in production. First, a run expires 10 minutes after creation if it has not reached a terminal state; a background sweep flips stragglers to expired with last_error.code:"run_expired". If you park in requires_action and your tool work is slow, submit before the window closes or the run is gone. Second, because only one run is active per thread at a time, concurrent agents that share a thread will trip thread_locked. Treat that as backpressure: retry the same thread with a short delay, or route the work to a separate thread.

Limits and defaults

• ·Thread message cap: 5,000 (hard, DB-enforced).
• ·Run expiry: 10 minutes from creation to terminal state.
• ·Tool-loop iterations per run: 10 (file_search rounds plus function rounds combined).
• ·Active runs per thread: 1.
• ·Assistant / thread metadata: 16 keys, key <=64 chars, value <=512 chars.
• ·List pagination: limit default 20, max 100; cursor via after / before taking object ids.
• ·Supported tool types: function and file_search. code_interpreter is not supported.
• ·temperature in [0, 2]; top_p in [0, 1].
• ·Model refs must carry a prefix (fc: / match: / slot: / dyn:); region suffix @<region> attaches to fc: refs only.

Related