# The AI Agent

Ask for multi-step creative work in plain language — *"cut the silences, add captions, make three vertical shorts and publish to TikTok"* — and the suite-wide AI Agent turns it into a concrete, costed plan you approve before a single credit is spent or a single frame changes.

**On this page**

- [What the AI Agent is](#what-the-ai-agent-is)
- [Why you'd use it](#why-youd-use-it)
- [Before you start](#before-you-start)
- [The core promise: plan first, run only after you approve](#the-core-promise-plan-first-run-only-after-you-approve)
- [Step-by-step: your first agent run](#step-by-step-your-first-agent-run)
- [Reading the plan card](#reading-the-plan-card)
- [Approvals, confirmations, and the hard floor](#approvals-confirmations-and-the-hard-floor)
- [Spending guardrails](#spending-guardrails)
- [While the run executes](#while-the-run-executes)
- [Undo a whole run in one click](#undo-a-whole-run-in-one-click)
- [How the agent understands you](#how-the-agent-understands-you)
- [When the agent asks instead of guessing](#when-the-agent-asks-instead-of-guessing)
- [When something fails](#when-something-fails)
- [What the agent can do](#what-the-agent-can-do)
- [Hand a film brief to the director](#hand-a-film-brief-to-the-director)
- [Speak your request](#speak-your-request)
- [Turn a plan into a reusable recipe](#turn-a-plan-into-a-reusable-recipe)
- [Every run is on the record](#every-run-is-on-the-record)
- [Tips](#tips)
- [Troubleshooting](#troubleshooting)
- [Related pages](#related-pages)

---

## What the AI Agent is

The AI Agent is CoreReflex's conversational co-editor. You describe what you want in a sentence — an edit, a piece of generated media, or a whole multi-step job — and the agent composes an ordered plan of real actions over your actual project: trims, deletions, resizes, color grades, keyframe animations, image/voiceover/music generation, workflow recipes, even a full film production brief handed to the [agentic director](directing-films.md).

Two things make it different from a chatbot bolted onto an editor:

1. **It plans against reality.** Before proposing anything, the agent reads your actual timeline — what clips exist, how long they are, what's selected — plus your brand voice, your workspace knowledge base, your connected accounts, and your remaining credits. Plans reference real items, never invented ones.
2. **Nothing runs without you.** Planning and executing are strictly separate. The plan card shows you every step, a plain-English summary of what would change, and a credit cost range — and only your explicit approval runs it. Risky or expensive actions require an extra confirmation on top.

## Why you'd use it

- **One sentence instead of twenty clicks.** "Make it vertical and fade in the title" becomes a resize plus keyframes, applied together.
- **You see the price before you pay it.** Every plan carries a credit estimate — and a low–high range when the true cost varies (a film's shot count, a recipe's fan-out). A plan your workspace can't afford refuses to run before anything is spent.
- **Everything is reversible.** A run's timeline edits land as **one undo entry** — one click (or one ⌘Z) reverts the whole run.
- **It asks rather than guesses.** If "the intro clip" could mean three things, you get one targeted question with clickable choices — not a wrong edit.
- **Failures are named, not shrugged at.** If step 4 of 7 fails, the agent tells you which step, why, that nothing half-applied, and offers two concrete fixes.

## Before you start

1. **Sign in** at corereflex.com — the editor and the agent share your one account. If your session has expired, the agent will tell you to sign in first.
2. **Open a project in the studio editor.** The agent works on the composition you have open.
3. **Have credits for generative steps.** Timeline edits are free; generating images, voiceovers, music, or film shots spends credits (see [Plans & Billing](plans-and-billing.md)). Plans that only edit cost nothing.
4. **Use a desktop-sized window.** The Agent button lives in the editor's top bar and is hidden on small screens.

## The core promise: plan first, run only after you approve

Every agent interaction is two phases:

- **Plan.** The agent interprets your request, inspects your project, and produces a validated plan — with zero side effects. Nothing is edited, nothing is generated, nothing is charged. The plan is previewed by rehearsing its edits against a **copy** of your project, so the change summary you read is a real projection, not a guess.
- **Run.** Only after you click **Approve & run** does anything execute. Timeline edits apply as one atomic batch — either the whole set of edits lands, or none of them do. Generative steps run in order, each metered against your credits as it happens.

The panel's footer says it plainly: *nothing runs without approval.*

## Step-by-step: your first agent run

1. Open your project in the studio editor.
2. In the top bar, click the **✦ Agent** button (next to the Console button). The Agent panel opens on the right, labeled **plan → approve → run**.
3. Type your request into the box at the bottom. Start simple: *"make it vertical"* or *"delete the last clip"*. For bigger jobs, chain them: *"cut the silences, add captions, make 3 shorts and publish to TikTok"*.
4. Click **Plan** (or press **⌘/Ctrl + Enter**). The button shows *Planning…* while the agent reads your project and composes the steps.
5. Read the **plan card** that appears: the summary, the numbered steps, the plain-English change list, and the credit estimate. (See [Reading the plan card](#reading-the-plan-card).)
6. If the agent needs a decision from you — say your request mentioned "the intro clip" and several clips qualify — you'll get **one question with clickable choices** instead of a plan. Click a choice and the agent re-plans with your answer.
7. If the plan includes anything that always needs explicit confirmation (a large deletion, a big spend, an external publish), **tick the confirmation checkbox** describing exactly what you're confirming.
8. Click **Approve & run**. The button shows *Running…* while the plan executes.
9. When it finishes, a green verdict summarizes what ran — and an **↩ Undo this run** button appears so you can revert the entire run as one step.

## Reading the plan card

The plan card is the contract between you and the agent. Top to bottom:

- **Summary** — one line describing the plan's intent.
- **The change list** — a plain-English projection of what would happen, computed by rehearsing the plan against a copy of your project: *"removes 2 clips, resizes to 1080×1920, will generate an image (a title card)"*. If a step places media that a generation step will produce, it's listed as chained work that completes after the generation lands.
- **Numbered steps** — every action, in order, with the tool it uses, a short rationale, and a per-step credit figure on anything that spends.
- **The cost line** — the total estimate. When the true cost can vary (a film production's shot count isn't known until the director boards it; a workflow recipe fans out into its own steps), you see a range: *"Estimated 300 credits (100–800, varies)"*. Timeline edits always cost nothing.
- **Safety flags** — if your request (or retrieved workspace-knowledge text) contained something that looks like a hidden instruction or an attempt to exfiltrate data, a red banner lists the flags so you can review before approving. Anything shaped like a password or API key you paste is scrubbed before the AI ever sees it.
- **The confirmation checkbox** — appears only when the plan includes an action that always requires explicit confirmation (see the next section). The Approve & run button stays disabled until you tick it.
- **"Not runnable"** — if the plan can't execute as-is (an unresolvable reference, a publish step with no connected social account, a cost past the hard cap), the card says why, and the run button stays disabled. Fix the blocker or rephrase and re-plan.

If the plan card carries an amber notice that it was **planned offline**, the AI planner was briefly unavailable and a simpler keyword-based plan was used instead. It's still validated and gated exactly the same way — but for anything nuanced, re-plan in a minute to get the full AI plan.

## Approvals, confirmations, and the hard floor

CoreReflex distinguishes three approval postures for agent work:

- **Guided** (the default, and what the editor's Agent panel uses) — every plan that changes or spends anything waits for your approval.
- **Manual** — everything except pure reads waits for approval.
- **Auto** — safe, undoable property edits may run unattended.

Whatever the posture, a **hard floor** applies that no setting can lift:

- **Generation always gates.** Any step that spends credits waits for approval, even under Auto.
- **External actions always confirm.** Publishing sends content outside CoreReflex and can't be un-sent — a publish step always requires the explicit confirmation tick, on top of approval.
- **Deletions never run unattended.** Removing clips or tracks is human-gated under every posture.
- **Bulk operations always confirm.** By default: deleting more than **25 items** across a plan, deleting an **entire track and its clips**, running more than **8 generation steps** in one plan, or any plan whose spend reaches roughly **100 credits** — each demands the explicit confirmation tick, with the reason spelled out next to the checkbox.

Splitting a big deletion into several small steps doesn't slip the gate — the thresholds count the whole plan.

## Spending guardrails

Money is guarded at three layers, in order:

1. **Before planning finishes** — a plan whose worst-case cost exceeds the platform's hard cap (5,000 credits by default) is rejected outright. A runaway "make 500 films" plan is never even presented as runnable. Plans are also capped at 200 steps.
2. **Before the run starts** — the plan's worst-case cost is checked against your workspace's remaining credits. If it might not fit, the run refuses with the exact shortfall: *"This plan may cost up to 800 credits but only 240 remain. Approve a smaller plan or top up."* Nothing has been spent at this point.
3. **During the run** — a run-scoped budget ledger reserves each generation step's credits **before** that step spends. If a mid-run step would push past your balance, the run halts at exactly that step — *"this step needs 20 credits but only 12 remain in the run budget"* — rather than charging past it. Every progress update also carries the credits committed so far and the budget remaining.

Honesty extends to the books: if a generation was charged but its output then failed, the run's record still shows that real spend — the ledger never under-reports.

## While the run executes

- The **Approve & run** button switches to *Running…* and the plan's steps execute in order: timeline edits in atomic batches, generations one at a time.
- A **transient hiccup** (a temporary provider error, a timeout) retries automatically with a short backoff — up to two extra attempts — and you'll see a toast like *"Agent retrying generate.music"*. A retried generation is **never double-charged**.
- For runs executing against your saved project from elsewhere (another tab, an automation), the editor's **top progress bar** tracks the run live, with toasts when it starts, retries, completes, or fails — the same activity feedback as renders and uploads.
- Steps that hand off to longer background work — most notably a film production — are reported as continuing on their own pipeline; the finished result lands in your workspace when done.

## Undo a whole run in one click

Every agent run applies its timeline edits through the editor's normal edit machinery, as **one coalesced undo entry**:

- After a successful run, the green verdict shows **↩ Undo this run**. Click it and everything the run changed reverts in one step.
- The one-click button works while the run is still your most recent change. If you've edited since, the button disables and points you to regular undo — **⌘Z** steps back through history as usual, and the run still occupies just one entry in it.
- Undo reverts the **timeline**. Credits already spent on generation aren't refunded by undoing — generated media stays in your library.

## How the agent understands you

**Fuzzy references resolve against your real timeline.** You can say *"the last clip"*, *"the first video"*, *"the longest clip"*, *"the selected items"*, or *"everything"* — the agent resolves these against the project's actual items at planning time, and the plan you approve is bound to concrete clips. A reference that matches nothing never silently edits the wrong thing: it either becomes a clarifying question (when there are candidates to choose from) or a clear "not runnable" reason.

**Plans are grounded in your workspace.** Before planning, the agent quietly gathers:

- a live **summary of your composition** — item counts by type, duration, canvas size, frame rate;
- your **brand name and voice** from Brand Studio, so generated copy and prompts stay on-brand;
- the most relevant extracts from your **workspace knowledge base** — treated strictly as reference facts, never as instructions; any knowledge-base passage that itself looks like a hidden instruction is excluded and flagged on the plan card;
- your **connected social accounts** (names and platforms only — never credentials);
- your **remaining credits and plan tier**, so the agent knows what's affordable;
- your **recent agent runs**, so *"do it like last time"* means something.

**Feasibility is checked while planning.** A publish step when no social account is connected marks the plan not runnable and says so — the agent doesn't offer you a dead button.

## When the agent asks instead of guessing

When a request is genuinely ambiguous, the agent asks **one targeted question** and pauses — it never stacks questions, and it never nags on a clear request.

- If the question has natural choices (which clip did you mean?), you get up to six **clickable options**, each labeled with the item's type and position on the timeline. Click one and the agent re-plans with your answer.
- If it's an open question, just type your answer — or a more specific version of your request — into the box and plan again.

A question turn produces **no executable plan**: nothing can run until the ambiguity is resolved.

## When something fails

Failures come back specific and actionable:

- **Which step**: *"Step 4 of 7 (generate.music) failed because …"* — never an opaque error.
- **Why**: one clean human-readable line, never a stack trace.
- **The atomicity guarantee**: *"No changes from the failed step were applied."* Timeline edit batches roll back wholesale; a failed generation writes nothing to your project.
- **Two concrete fixes**, chosen by the kind of failure:
  - a **temporary** provider issue → run the plan again; if it persists, run the failing step on its own;
  - **out of credits** → the run pauses; top up or approve a cheaper plan;
  - **bad parameters** → re-plan with more specific wording, since retrying identically would fail identically.

Steps that completed before the failure are reported, and any credits genuinely spent are recorded — the failure never hides real spend.

## What the agent can do

| Ask for | What happens | Cost |
|---|---|---|
| Timeline edits — trim, split, delete, move, mute, resize the canvas, change fps, color grade, transitions, audio FX, markers | Applied as one atomic, undoable batch through the editor's real edit engine | Free |
| Motion — fade-ins/outs, slide-ins, pop/bounce, pulse, Ken Burns drift, easing changes | Composed from real keyframes on the item, editable afterward like any hand-made animation | Free |
| Questions — *"what's on the timeline?"*, *"how many clips?"* | A read-only inspection plan; reads can never change anything | Free |
| **Generate an image** | Created inline during the run; a later plan step can place it on the timeline | Credits |
| **Generate a voiceover** | Text-to-speech synthesis, placeable by the plan | Credits |
| **Generate music** | A scored track from a mood or description | Credits |
| **Produce a film** | The brief hands off to the [agentic director's](directing-films.md) plan → produce → critique → assemble pipeline, running in the background; the finished film lands as a project | Credits (per shot — shown as a range) |
| **Run a saved workflow recipe** | Launches the recipe in the background; its own steps meter their own costs | Varies by recipe |
| Cut silences · add captions · create shorts · auto-reframe · upscale · **publish** | The agent recognizes, prices, and gates these in plans — but does not execute them itself yet. Today they come back marked as handed off; run the work from its own studio ([Auto-Clips](auto-clips.md) for shorts and captions, the editor's caption and reframe tools, social scheduling for publishing) | Priced on the card; nothing is charged for a handed-off step |

That last row is worth restating plainly: for those cross-studio verbs, the agent is currently a **planner and cost estimator**, not the executor. The plan card still gates them (publish always requires confirmation), but after the run they are reported as deferred rather than done, and no credits are spent on them by the agent.

## Hand a film brief to the director

Ask the agent to *"produce a 30-second teaser for our spring launch"* and it plans a director step: the cost shows as a **range** (the real cost depends on how many shots the director boards — the card assumes roughly 1–8), and on approval the brief hands off to the same durable film pipeline described in [Directing Films](directing-films.md). The production runs in the background — credits meter per shot inside the pipeline, not up front — and the assembled film persists as a composition in your workspace. Because it's one agent step, you can compose it: *"produce the teaser, generate a poster image, and score a 30-second track"* is one plan, one approval.

## Speak your request

CoreReflex's real-time voice agent includes a **Creative Copilot** persona wired to the same planner. Speak a request — *"cut the silences and make three shorts"* — and it plans exactly as the panel would, then **reads the plan back to you**: the summary, the step count, and the credit estimate. If the planner needs a clarification, the copilot asks you that one question out loud and re-plans with your answer.

The two-phase promise holds over voice: the copilot **never executes anything** and never claims it did — plans made by voice run only after you approve them in the editor. The Creative Copilot isn't yet offered in the persona menu on the `/voice` page (which lists the booking, lead, sales, and support personas — see [Recording, Meetings & Podcasts](recording-and-podcasts.md)); it's available to workspaces that connect a voice line to that persona directly.

## Turn a plan into a reusable recipe

An approved one-off plan can become a **reusable, parameterized recipe** — the same workflow, re-runnable with new copy. The conversion is honest about what repeats:

- **Generative steps convert.** Their prompts become fill-in slots (with your original text as the default), so the recipe re-runs with a new image prompt, voiceover script, or music brief each time.
- **Timeline edits are skipped — and reported.** They referenced specific clips in one project, which mean nothing in the next; a recipe is a repeatable generation workflow, not an edit macro. The conversion tells you exactly which steps were skipped and why.

Today this conversion is exposed through the CoreReflex platform API rather than a button in the Agent panel; the recipes it creates appear alongside your other saved workflows and run like any of them.

## Every run is on the record

Every agent execution writes an audit record: what you asked, the full plan, what each step did, and the credits **actually** committed — including a step that charged and then failed. This ledger is what powers the agent's memory of your recent runs (*"like last time"*), and it means a workspace can always answer "what has the agent done here, and what did it cost?" truthfully.

## Tips

- **Chain related work into one request.** One plan means one approval, one cost figure, and one undo entry: *"delete the last clip, fade in the first one, and generate an upbeat 20-second track"*.
- **Select first, then say "the selected clips".** Your live selection is part of the agent's context — it's the most precise reference there is.
- **Read the change list, not just the summary.** *"removes 12 clips"* on a plan you expected to remove one is the moment to re-plan, and exactly what the preview exists to catch.
- **Watch the range, not just the estimate.** On film and recipe steps the expected figure is a floor — the high end of the range is what the affordability check uses, so it's the honest worst case.
- **Ask before you edit.** *"How many audio clips are there?"* plans a free, read-only inspection — a safe way to check the agent sees your project the way you do.
- **Rephrase beats retry for parameter errors.** If a step was rejected for bad parameters, running the same plan again fails the same way; a more specific request plans better.

## Troubleshooting

- **"Sign in at corereflex.com first, then reopen the editor."** Your session expired. Sign in on the dashboard, then reopen the editor tab — one account covers both.
- **"The agent is unreachable — try again."** A network hiccup between the editor and the platform. Nothing was changed. Try again in a moment.
- **The card says "Not runnable" with a reason.** The plan failed validation — an unresolvable reference, a step your workspace can't run (for example a publish with no connected social account), or a cost past the hard cap. Fix the named blocker or rephrase and re-plan.
- **"This plan needs explicit confirmation: …"** The plan crosses an always-confirm line (bulk delete, whole-track delete, external publish, high spend, a large generation batch). Read the reason next to the checkbox, tick it if you mean it, then Approve & run.
- **"This plan may cost up to X credits but only Y remain."** The affordability check refused before any spend. Top up (see [Plans & Billing](plans-and-billing.md)) or ask for a smaller plan.
- **"Agent run halted: this step needs N credits but only M remain in the run budget."** The mid-run budget ledger stopped the run at the exact step that would have overspent. Everything before it that completed stands; the halting step spent nothing.
- **An amber "Planned offline" notice.** The AI planner was briefly unavailable, so a simpler keyword plan was substituted (and clearly labeled). It's safe to run — same validation, same gates — but re-plan in a minute if the request was nuanced.
- **The agent asked a question with no choice buttons.** It needs detail only you have. Type your answer — or your request with the detail folded in — and click Plan again.
- **"↩ Undo this run" is grayed out.** You've edited the project since the run, so one-click revert would also revert your edits. Use regular undo (⌘Z) — the run is still a single entry in history.
- **"Too many requests."** Planning and executing are rate-limited (about 30 each per minute) to keep costs sane. Wait a few seconds.
- **A step "continues on durable paths" but nothing seems to happen.** For film production and recipes, the work genuinely continues in the background and lands in your workspace. For shorts, captions, silence-cutting, auto-reframe, upscale, and publish, the agent currently plans and prices but does not execute — run those from their own studios (see [What the agent can do](#what-the-agent-can-do)).

## Related pages

- [Directing Films](directing-films.md) — the film pipeline the agent can brief conversationally.
- [Editing & Mastering](editing-and-mastering.md) — the timeline the agent edits; everything it does, you can do (and adjust) by hand.
- [Auto-Clips](auto-clips.md) — the studio that actually cuts long video into captioned vertical shorts today.
- [Voiceover & Music](voiceover-and-music.md) — the narration and scoring the agent can generate into a plan.
- [Recording, Meetings & Podcasts](recording-and-podcasts.md) — the real-time voice agent that hosts the Creative Copilot persona.
- [Plans & Billing](plans-and-billing.md) — credits, tiers, and topping up.
- [Getting Started](getting-started.md) — accounts, sign-in, and your first project.