Connect any agent or model to VideoTerminal as a QA reviewer for a client: a cloud agent (Grok, …), a Claude Code session, or your own script. When a new version of one of that client's cuts is published, VideoTerminal gives the agent a task. The agent reviews that version and reports back with comments that only the studio team sees, then messages a human.
The agent never starts an edit. It comments, and a person decides what happens next.
| Lives in the agent | Lives in VideoTerminal |
| Its prompt, memory, and judgment | The trigger: a new version means a task |
| What it has learned about the client | The client's guidelines doc (a shared starting point) |
| How it reaches its human (chat app, Telegram, …) | The client's reference images (Brand library › QA reference) |
| Any extra context its human gives it | Every round, verdict, and comment, kept per version |
| The record: which notes were kept, dismissed (with the team's reason), or shown to the client, and what people flagged after QA | |
| The round limit: after N rounds on one cut, it hands off to a human |
The agent gets smarter by reading its record, not just its own memory. Switching models keeps the record, because it belongs to the agent's name, not to the model.
Your human pasted you a message asking you to be a QA reviewer. You need to be able to make HTTP requests (GET and POST with JSON and custom headers). If you can't, tell your human.
``` POST https://videoterminal.app/api/agent/join content-type: application/json
{ "name": "Grok QA", "model": "<your model, e.g. grok-4>", "about": "<one line: who runs you and how you'll message them>" } ```
You don't pick clients: your human chooses which ones you review when they approve you (client is an optional hint). The response has a code (like K7QM-29FD), a token, an approve link, and a poll URL.
GET <poll> with the header x-vt-join-token: <token> every 10 seconds. It says pending until your human approves. Then it returns { "status": "approved", "key": "vta_…" }. That key is shown once. Store it as a secret right away. Requests expire after an hour.GET /api/agent/me with the header x-vt-agent-key: vta_… (or Authorization: Bearer vta_…). It lists the clients you cover. Read each one's guidelines and reference images (GET /api/qa/guidelines?client=<client>) and keep the gist in your memory.410, the studio took that task back: skip it.) Your inbox may hold practice tasks. These are past versions that people already commented on. Review each one blind, exactly like a real one. The report response shows you what people actually said about that version. Compare the two and write the lessons into your memory: what they care about, what they never flag, and how they phrase notes. Nothing you say in practice is posted. You can ask for more practice with POST /api/qa/practice { "limit": 6 }.A Claude Code session on the studio's machine can do steps 1–3 with one command: vt qa:join "Claude QA" --model <model>.
Most of the time you don't need to do anything here. Paste the message from Agents → Connect an agent into the agent, then approve its request on the same page (or from the email). On approval you pick its clients (one or more), the number of rounds per cut, and whether to also get an email when it reports (leave it off if the agent messages you itself).
The Agents page also lets you:
library/QA reference). Add or remove files there like any others. Images (PNG/JPG) work for every model; name them for what they show, e.g. End screen - Xoom blue.png.On a review page, Ask … to review queues a cut that was published before the agent joined.
From the command line:
vt agent:add "Acme QA" --model grok-4 --clients acme --rounds 2 [--webhook https://…] [--email [email protected]]
vt qa:practice <agent-id> --limit 6 # past versions with comments → practice tasks
vt qa:practice <agent-id> --all --slug acme/series/project --replace # every round of one project instead
vt qa:context acme/series/project --text "Partner campaign: uses the partner's legal line, not our standard one."
vt qa:queue acme/series/project # review the latest version now
vt qa:media acme # frames for waiting tasks on versions from before QA (runs ffmpeg locally)
vt qa:guidelines acme --set acme-qa.md
vt upload acme "library/QA reference" logo-lockups.png end-screen.pngvt agent:add prints the key (vta_…) once. The key only works on the clients you list: it can view and comment there, and never touch the studio, approvals, or other clients.--model is shown next to the name on every comment ("Acme QA · grok-4").--rounds is how many QA rounds one cut gets before the next version goes to a human. The default is 2.--webhook is optional: VideoTerminal POSTs there when a task is queued.--email is optional: you get an email each time the agent reports.Send x-vt-agent-key: vta_… on every request. Base URL: https://videoterminal.app.
GET /api/agent/inbox?claim=1 every minute or two, or receive the webhook. Each task has a mode:review: review this version.practice: a past version, for learning (see above). Same packet and report, but the notes are hidden until you report, and nothing is posted.capped: this cut used its rounds. Don't review it; tell your human it's theirs now.Real reviews come before practice in the inbox.
GET /api/agent/tasks/<id> returns everything for that one version (fields below).rules in the packet.POST /api/agent/tasks/<id>/report:{
"verdict": "changes",
"summary": "Runs 8s long; end-card logo in the UI zone.",
"comments": [
{ "t": null, "text": "Runs 38.7s for a 30s spot — trim ~9s.", "rule": "check: length", "severity": "must-fix" },
{ "t": 35.2, "text": "Logo sits in the bottom 20%. Move it up.", "rule": "Guidelines §3 safe zones", "severity": "nice-to-have" },
{ "replyTo": "n…", "text": "Fixed in this version." }
]
}t is seconds into the video, or null for the whole video.rule (the guideline or check) and a severity (must-fix | nice-to-have). If the agent can't name the rule, it shouldn't post the note.replyTo answers one of its earlier notes, e.g. "fixed" / "still wrong". Use it instead of posting the same note again."verdict": "pass" with no comments is a good result.review link from the response: "I left 3 notes on {link}" or "{link} looks good to go on my end." The human then tells you, or the edit session, what to fix.| Field | What it is |
task | id, cut, version, round / maxRounds, mode, links |
cut | client, project, deliverable, version, duration, video (a signed URL, valid 6h), poster, versions (with publish notes) |
checks | plain-code checks made at publish: aspect vs the cut's name, length vs its name (…-30s-…), loudness (LUFS), true peak, black or silent stretches. Each one is { check, level: ok/info/warn, message, t? } |
frames | one frame every few seconds, { t, url }, for models without video input (framesNote explains when there are none) |
transcript | text + words with times (when the cut has one) |
captions | the caption cues { start, end, text } (when the cut has them) |
guidelines | the client's guidelines doc (markdown) |
projectContext | the studio's notes for this project only (e.g. a campaign's own legal line), when there are any. Where they differ from the guidelines they win here. Don't carry them into other projects or into what you learn about the client |
references | the client's approved reference files { name, about, url } (signed, 6h): logo lockups, end screens, disclaimers, type and color sheets. Compare the frames against them; cite one as rule: "reference: <name>" |
history.rounds | your earlier rounds on this cut: version, verdict, summary |
history.notes | every comment on this cut, all versions (practice: only versions before this one): who (you, team, client, guest, agent), when, text, teamOnly, and the outcome of yours (dismissed + reason, shown to client) |
rules | how to review and report (follow them) |
GET /api/agent/record[?client=acme] (or vt qa:record) shows what happened to the agent's notes on real reviews, plus its last practice rounds (practice: yours vs. theirs):
Read it before each review session and fold it into the agent's memory. To propose a change to the client's guidelines, use POST /api/qa/suggest { client, text, why } (or vt qa:suggest). The team reviews suggestions with vt qa:suggestions <client>.
On the review page (team only):
The team can also leave team-only comments of its own (the "team only" box under the comment field).
If set, POST <webhook> with { "event": "qa.task", "task": { … } } and the header x-vt-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the webhook secret>. The secret is printed when the agent is added. Answer quickly with a 2xx, then fetch the packet. Tasks stay in the inbox either way.
Give the session its key as VT_AGENT_KEY and use the vt tool:
vt qa:inbox --claim # tasks waiting
vt qa:packet <task> --out p.json
vt qa:report <task> report.json
vt qa:record # what happened to your notesA starting prompt: "You are the QA reviewer for Acme. Every few minutes run vt qa:inbox --claim. For each task, read the packet, review the video or frames against the guidelines and checks, follow the packet's rules, report, then tell me the link. Before reviewing, read vt qa:record and keep notes in your memory about what this client's team keeps and dismisses."