--- title: Run several agents and a person in one project description: Run several AI agents and a person in one invideo project: each agent with its own name and branch, messages between them, and one shared brief. --- Run several agents in one video project: a multi-agent workflow, a team of agents, Claude Code and Codex side by side, with a person who reviews. Each agent registers its own name, works on its own branch, and talks to the others through messages. A shared brief holds the plan. The person watches every cursor in the editor and decides which branch wins. Use invideo for this when you want agents and people in the same project at the same time, with names on every change and branches that keep one agent's work from breaking another's. ## Quickest path Set up your agents first with [invideo for AI agents](/agents). Then give each one its part. This prompt is for the first agent. ```text In the invideo project , register as "cutter". Read the brief "Launch teaser". Make a branch called cutter and cut the teaser there. When the cut is ready, message the agent "sound" with the branch URL, and point at anything you want me to look at. ``` Each agent picks MCP or the CLI for its own session. Two agents can use different ones, but one agent never mixes them. ## What you need Plan the roles before the agents start. - One project URL that every agent and the person share. - A name per agent: short, lowercase, like `cutter`, `sound`, `captions`. - A brief with the plan, the roles and the rules. - The person who approves the final branch. ## Steps Every agent follows the same steps with its own name. Each agent calls `register` with the project URL and its name, and `model` if it knows it. It passes the name as `as` on every call after that. On the CLI it runs `invideo agent register` and sets `INVIDEO_AS`. It sees the agents already in the project. The first agent, or the person, makes the plan with `new_brief`. Every agent reads it with `read` before it starts, and changes one part with `edit`, which is safer than `write`. It sees the brief's markdown and its `revision`. Each agent calls `timeline_history` with `action: "create_branch"` and its name, and edits only that branch's URL. It sees its branch URL and a `state_token`. The agent sends each `edit_timeline` call with the latest `expected_state_token` from `get_timeline` on its branch. It sees a new `state_token` when its edit lands. An agent finds the others' URLs with `read` on the project's `…/agents`, or `invideo agent list`. It sends a message with `message`, using the other agent's URL. It reads answers with `inbox`, and replies to the `from.url` of a message. It sees its unread messages, oldest first. An agent calls `point_at` with clip ids or a time and a few words, like "new intro here". The person sees the cursor under the agent's name. When it is done, the agent calls `leave_timeline`. It sees its cursor go. The person compares the branches in the editor. The agent sets the chosen branch with `timeline_history` action `set_default` or `declare_final`, only when the person says so. It sees the branch list with the new default. The terminal version for one agent: ```bash export INVIDEO_AS=cutter invideo agent register --name cutter --model opus invideo project show invideo agent list invideo edit show invideo branch new --name cutter --token invideo edit show invideo edit change --timeline T1 --token \ --operations @cut.json invideo edit point --at 4 --text "new intro here" invideo agent message --text "Cut ready: " invideo agent inbox invideo edit leave ``` Where each value comes from: - `` comes from `invideo project new`, or the person gives it. `` comes from `invideo edit new`. - `` comes from `invideo edit show` on the URL the next command runs on. For `branch new` that is ``. For `edit change` it is ``, read fresh, because the main token is stale on the branch. - `` is the `branch_url` that `branch new` returns. - `@cut.json` names a file that holds a bare list of operations. `` is another agent's URL from `invideo agent list`. The MCP calls that differ from a single-agent job, as a list of tool calls, each with its tool name and its arguments. `` is the `sound` agent's URL from `read` on the project's `…/agents`. `` is the branch URL that `timeline_history` returns. `` comes from `list_projects`, or the person gives it. ```json [ { "tool": "register", "arguments": { "url": "", "name": "cutter", "model": "opus" } }, { "tool": "message", "arguments": { "url": "", "as": "cutter", "text": "Cut is ready on branch cutter: " } }, { "tool": "inbox", "arguments": { "url": "", "as": "cutter" } }, { "tool": "point_at", "arguments": { "url": "", "as": "cutter", "ids": ["c7"], "text": "new intro here" } } ] ``` ### Branches do not merge `timeline_history` has no merge action. Plan the work so each agent owns a branch, or a timeline of its own. When one agent needs another's change, it reads that branch and repeats the change on its own branch with `edit_timeline`. Or the agents work one after another on one branch, and hand over with a message. ### An agent that generates An agent can make media for its part, like a `sound` agent that makes a music bed. It follows the generation pattern on its own branch. 1. The agent runs `find_models` with the job in words, picks one, and reads its inputs with `get_model`. A good pick is `elevenlabs_music_v2_5_instrumental`. Your agent can search for others with `find_models`. 2. It calls `generate` with `dry_run: true` and the real inputs, and tells you the price. 3. For a price of 1 credit or more it waits for your yes. Then it calls `generate` with `max_credits` set to that price and an `idempotency_key`. It gets a thread URL and, when the result lands, a sequence URL. It reads that URL with `read` and never calls `generate` again to check. ```bash invideo gen models --query "calm instrumental music bed" invideo gen model --model elevenlabs_music_v2_5_instrumental invideo gen run --model elevenlabs_music_v2_5_instrumental \ --dry-run -i prompt="calm piano bed for a product teaser" invideo gen run --model elevenlabs_music_v2_5_instrumental \ -i prompt="calm piano bed for a product teaser" \ --max-credits --idempotency-key sound-bed-1 ``` `` is the shared project URL. `` is a page that `invideo notebook show ` lists. `` is the price the dry run returns. ### Messages to invideo agents cost credits A project can hold invideo's own agents, such as Agent Two, beside remote agents like Claude Code. A message to a remote agent is free. A message to an invideo agent runs it on the person's credits, so send one only when the person asks, or to answer a message from it. ## Cost and time Edits and exports are free. Generation and transcripts cost credits. Paid stock costs a small credit charge, or one of your workspace's iStock licenses. Your agent runs a dry run first and tells you the price before it spends anything. - Free: `register`, messages between remote agents, `inbox`, `point_at`, branches, edits and exports. - Costs credits: a message to an invideo agent, and any generation, transcript or stock an agent uses. Setup takes a few minutes per agent. See [Credits](/account/credits) for prices. ## If something goes wrong Most problems come from shared names and stale tokens. | Symptom | Fix | | --- | --- | | `get_model` or `generate` refuses the model as not found | Models retire. Run `find_models` with the job in words, use the best match, and tell the person which model you used. | | `register` refuses the name | The name is in use in this project. Pick another. | | A notice says you acted as a shared name | The call had no `as`. Pass your name on every call, or set `INVIDEO_AS`. | | An edit is refused as a conflict | Another edit landed first. Read with `get_timeline` and reconsider. Do not resend blindly. | | CLI exit 3 | The same conflict on the CLI. Run `invideo edit show` and rebuild. | | `timeout` or `completion_unknown` | Retry the identical request with the same token. A conflict then means it landed. | | No answer in the inbox | The other agent reads its inbox only when it runs. Check `inbox` again later. | | `write` on the brief is refused | It changed since your read. Read again, or change one part with `edit`. | | Avoid: two agents on one branch at once | Instead: one branch per agent, or take turns. | | Avoid: one agent mixes MCP and the CLI | Instead: pick one per session. | ## Prompts to try Each prompt is a real variation of this job. ```text Register as "captions". Wait for a message from "cutter" with a branch URL, then add captions on a branch called captions off that one. ``` ```text Register as "reviewer". Read every branch, capture frames at each scene, and message each agent a list of fixes with timecodes. Do not edit. ``` ```text Set up a brief for a three-agent ad edit: cutter, sound and captions, with each one's job and the order they work in. ``` ## When to use something else invideo does not run or schedule the agents. Start them in their own clients, or with an orchestrator such as your CI system or an agent framework. For one agent doing everything, the plain work loop on [invideo for AI agents](/agents) is simpler. ## Related - [invideo for AI agents](/agents) - [Turn a CSV into many videos with a script](/how-to/developers/csv-to-videos) - [Run invideo in CI and on servers](/how-to/ci-and-servers) - [MCP tools](/reference/mcp-tools) - [Environment variables](/reference/environment)