Build a code-review assistant with the Assistants API

30 min

By the end you'll have a reusable Assistant, a Thread per PR, a streaming Run that calls your custom review_pull_request tool, and a tiny Next.js UI that pastes in a URL and watches the review stream in.

Prerequisites

• A Ringside API key
• Node 20+ and Next.js 14 or 15
• A GitHub token if you want to hit real PRs in the tool implementation
• Familiarity with SSE + fetch streaming helps but isn't required
• 30 minutes

Step 1

Create the Assistant

// register tools once, use forever

An Assistant is a named config: model + instructions + tool schema. Create it once and reference it from every run. You can update instructions later without touching your call sites.

The tool review_pull_request takes a PR URL. Ringside will ask the model when to invoke it. You run the actual fetch in your own code.

What just happened

Function tools don't execute on Ringside's side. The model decides when to call them; you receive a requires_action event; you run the tool yourself and post the result back. This keeps secrets (like GitHub tokens) on your infra.

~/reviewer

$ curl -X POST https://api.fightclub.pro/v1/assistants -H "Authorization: Bearer $FC_API_KEY" -d @assistant.json

# assistant.json:

# {"model":"fc:openai/gpt-4o-mini","name":"PR reviewer",

# "instructions":"You review pull requests for bugs + style.",

# "tools":[{"type":"function","function":{

# "name":"review_pull_request",

# "parameters":{"type":"object","properties":{

# "pr_url":{"type":"string"}},"required":["pr_url"]}}}]}

✓{"id":"asst_8kL2xC"}

█

Step 2

Create a Thread for the PR

// one thread per PR

Threads hold message history. Use one thread per PR so multi-turn conversations (e.g. "also check the test coverage") pick up where the last one left off.

Stash any useful context on metadata the PR URL, the author, the repo. Ringside passes it through unchanged and it shows up in your dashboard's thread browser.

~/reviewer

$ curl -X POST https://api.fightclub.pro/v1/threads -H "Authorization: Bearer $FC_API_KEY" -d '{"metadata":{"pr_url":"https://github.com/acme/api/pull/482"}}'

✓201 Created

{"id":"thread_Yq9mNp","object":"thread"}

█

Step 3

Post the PR diff as a message

// user turn = your data

Append a user message containing the diff. Keep it under ~50k tokens or the run will come back with input_too_large; for bigger PRs, summarize or split.

ordinal in the response is the message position in the thread. Useful for display and for re-fetching later.

~/reviewer

$ curl -X POST https://api.fightclub.pro/v1/threads/thread_Yq9mNp/messages -H "Authorization: Bearer $FC_API_KEY" -d @diff.json

# diff.json:

# {"role":"user","content":"Review this diff:\n\ndiff --git a/api.py ..."}

✓{"id":"msg_Lp3k7","ordinal":1}

█

Step 4

Create a streaming Run

// stream: true

Kick off the run with stream: true. Ringside returns SSE chunks in the OpenAI Assistants event taxonomy: run lifecycle (created/in_progress/completed) interleaved with message deltas.

When the model wants to call a tool, the stream emits thread.run.requires_action and pauses. The next move is yours.

What just happened

SSE runs idle for up to 10 minutes while waiting on tool output. If you miss the requires_action event, the run will eventually expire and emit run.failed with reason='expired' - safer than hanging forever.

~/reviewer

$ curl -N -X POST https://api.fightclub.pro/v1/threads/thread_Yq9mNp/runs -H "Authorization: Bearer $FC_API_KEY" -d '{"assistant_id":"asst_8kL2xC","stream":true}'

event: thread.run.created

event: thread.run.in_progress

event: thread.message.delta data: {"content":[{"text":"Looking at"}]}

event: thread.message.delta data: {"content":[{"text":" the diff..."}]}

event: thread.run.requires_action

data: {"tool_calls":[{"id":"call_9x","function":{"name":"review_pull_request","arguments":"{\"pr_url\":\"...\"}"}}]}

█

Step 5

Handle requires_action

// run the tool, submit outputs

Read the tool_calls array, execute each call in your own code (this is where you'd call the GitHub API), and POST the JSON-stringified outputs back to submit_tool_outputs.

The stream resumes immediately and the model writes its review using the tool output. Terminal: thread.run.completed.

What just happened

You can loop tool calls up to 10 times per run. The 11th returns 400 max_tool_iterations_exceeded - design your tool schemas so the model reaches an answer in a few hops.

~/reviewer

$ curl -X POST https://api.fightclub.pro/v1/threads/thread_Yq9mNp/runs/run_H2/submit_tool_outputs -H "Authorization: Bearer $FC_API_KEY" -d @outputs.json

# outputs.json:

# {"tool_outputs":[{"tool_call_id":"call_9x",

# "output":"{\"additions\":47,\"deletions\":12,\"files\":3}"}]}

event: thread.run.in_progress

event: thread.message.delta data: {"content":[{"text":"The diff adds input validation"}]}

event: thread.run.completed

✓run_H2 completed in 4.2s

█

Step 6

Tiny Next.js UI

// input + button + stream

Your /api/review route proxies the Assistant run and streams back plain text. The client just reads from response.body and appends to a <pre>.

30-line component, no frameworks, no chat-ui library. Paste a PR URL, hit Review, watch the assistant's analysis appear character-by-character.

app/reviewer/page.tsx

$ cat > app/reviewer/page.tsx

"use client";

import { useState } from "react";

export default function Reviewer() {

const [url, setUrl] = useState("");

const [out, setOut] = useState("");

async function run() {

const r = await fetch("/api/review", { method:"POST", body: JSON.stringify({url}) });

const reader = r.body!.getReader();

const dec = new TextDecoder();

while (true) { const {value,done} = await reader.read(); if (done) break;

setOut(o => o + dec.decode(value)); }

}

return <><input value={url} onChange={e=>setUrl(e.target.value)}/>

<button onClick={run}>Review</button><pre>{out}</pre></>;

}

✓Type a PR URL, see the review stream live

█

You built it.

An Assistant with a custom tool, a Thread per PR, a streaming Run that calls out to your tool implementation, and a working UI. The same scaffold swaps in for any function-tool agent. Replace the tool schema and your implementation, done.

Example: assistants with tools →Endpoint reference: /v1/assistants →