Agents
Workflows
Coming in desktop 1.99.113: a workflow is a plan, written as JSON, that runs many subagents in stages: fan out over a list of items, files or changed files, stream one stage's results into the next, wait at a barrier, check each result with a verifier, and stop at ceilings you approved before anything ran. Vector reads the plan and runs it; no code in it runs, and Vector never runs model-written code anywhere. A run works in the background, shows its stages in the Tasks pane, and reports to the conversation once, when it ends.
Coming in desktop 1.99.113: a workflow is not Workflow insights. Workflow insights, in Settings → Memory, record how your own runs
went so Vector can learn cheaper defaults, and vector memory workflow shows them. A workflow on
this page is a plan of agents that you or the agent starts. For a few independent briefs the agent uses
ordinary subagents instead.
Approval
Coming in desktop 1.99.113: before a workflow runs, Vector shows its plan: each stage with its phase, agent, model and effort, how
many items it runs over (or "dynamic" when an earlier stage decides), where it writes (in this checkout one
at a time, each in its own paths, or each in its own worktree), and the permissions its agents will ask
for. Below the stages are the ceilings: agents, agents at once, spend (the run's own and the request's
subagent ceiling it shares), tokens, steps, steps per agent and minutes. When the agent starts a run, you
approve that plan as you approve any other ask; the workflow permission is ask by default.
Coming in desktop 1.99.113: Always allow, and the automatic approval of --auto, cover only a plan within your configured
defaults. A plan past them, a plan started after the conversation or its subagents read web or MCP content,
and one asked for by a Vector process that an agent started from its shell ask every time, and Always allow
is not offered: outside content or a program should not be able to get a large run approved unattended.
Desktop 1.99.111 and 1.99.112 show such an ask with their generic reason about the web.
Coming in desktop 1.99.113: workflows start from the main agent only, never from a subagent, and need background subagents on. A
conversation with a guest in it cannot start one, nor can a Light request or a request where you said "no
subagents". One run works at a time in a conversation unless you raise budget.workflow.runs. A
workflow agent cannot start subagents of its own.
Coming in desktop 1.99.113: you can also start a saved workflow yourself: /workflow in the desktop app or the TUI asks
for its inputs, checks it and shows the plan before Run, and vector run --workflow prints the
plan before it starts. A run you start this way does not ask again, because you saw the plan. It starts
only while the conversation is idle; in the desktop app and the TUI a busy conversation gets a message in
the composer instead, asking the agent to run it, for you to send.
The grammar
Coming in desktop 1.99.113: the root object has version: 1, a title of up to 80 characters, and optional
description, inputs (up to 16), defaults, limits,
stages (1 to 32) and result. Unknown keys are errors at every level, with a
suggestion when one is close to a known key. A spec the agent writes is at most 32 KiB; a saved one, or one
you pass yourself, at most 256 KiB.
Coming in desktop 1.99.113: a stage has an id (lowercase letters, digits, _ and -, starting
with a letter, up to 32 characters) and a prompt of up to 16 KiB, 64 KiB once filled in.
Optional fields are title, phase, agent (general by default, or an
allowed specialist such as explore), model, effort, isolation,
for_each, after, if, when, output,
owned_paths, success_criteria, verify, retries (0 to 2,
default 1) and on_error (skip or fail). Models follow the same rules as a brief's model, and a
stage cannot pick a primary, hidden, research or denied agent.
Coming in desktop 1.99.113: without for_each a stage runs once. With it, a stage runs once per item from one source:
items (a list of up to 200 values in a spec the agent writes, 1000 in a saved one),
files (a glob over the repository, hidden files skipped unless hidden is true),
changed_files (paths changed since a git base, deleted ones skipped unless
include_deleted is true) or from (an earlier stage's outputs). from
streams: each result becomes items as soon as its agent finishes, with no barrier, unless
wait: "all" or sort_by waits for the whole stage. where,
dedupe_by, limit and batch (groups of up to 100) shape the items.
after is a barrier, a stage's if checks counts such as
stages.review.failed, and an item's when checks the item.
Coming in desktop 1.99.113: templates only look up values: {{item}}, {{index}},
{{inputs.name}}, {{run.title}}, {{stages.id.output}},
{{stages.id.outputs}} and {{stages.id.outputs_file}}, plus
{{output}} and {{round}} in a verifier. They call no function and do no
arithmetic, and a missing value is an error rather than an empty prompt. A value an agent produced reaches
the next prompt inside a data envelope that says it is data, not instructions, with the characters that
could fake a tag or attach a file escaped. Conditions are fixed comparisons (equals,
not_equals, in, gt, gte, lt,
lte, exists, contains) with one level of all,
any or not, and never a regular expression.
Coming in desktop 1.99.113: output.schema gives a stage's agents a JSON Schema with an object at the root, from the
subset structured results describe, so later stages can use
its fields. verify names a verifier agent, a prompt and an until condition: a
rejected result goes back to its agent as data for another try, up to max_rounds (2 by
default, 5 at most), and on_fail keeps, drops or fails it. An agent you stopped is never
retried on its own. A stage that writes should name owned_paths or use
isolation: "worktree"; one with neither runs its agents one at a time in your checkout.
Three examples
Coming in desktop 1.99.113: these are the examples the workflow tool's guide gives the agent. The first reviews each file changed since the last commit with a read-only agent, then summarizes the findings.
{
"version": 1,
"title": "Review changed files",
"stages": [
{
"id": "review",
"agent": "explore",
"for_each": {
"changed_files": {
"base": "HEAD~1",
"limit": 50
}
},
"prompt": "Review this changed path: {{item}}. Return actionable findings only.",
"output": {
"schema": {
"type": "object",
"properties": {
"findings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"findings"
],
"additionalProperties": false
}
}
},
{
"id": "summary",
"agent": "explore",
"after": [
"review"
],
"prompt": "Summarize these review findings as data: {{stages.review.outputs.findings}}"
}
]
} Coming in desktop 1.99.113: the second researches a topic from three angles, checks the notes in batches of three as soon as all of
them are in, and writes a report. Supply the topic input when you run it.
{
"version": 1,
"title": "Research a dependency change",
"inputs": {
"topic": {
"required": true
}
},
"stages": [
{
"id": "scan",
"agent": "explore",
"for_each": {
"items": [
"compatibility",
"migration",
"licensing"
]
},
"prompt": "Research {{inputs.topic}} from this angle: {{item}}",
"output": {
"schema": {
"type": "object",
"properties": {
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"notes"
],
"additionalProperties": false
}
}
},
{
"id": "check",
"agent": "explore",
"for_each": {
"from": "scan",
"path": "notes",
"wait": "all",
"batch": 3
},
"prompt": "Check this batch of notes: {{item}}"
},
{
"id": "report",
"agent": "explore",
"after": [
"check"
],
"prompt": "Summarize the checked outputs: {{stages.check.outputs}}. Full source: {{stages.scan.outputs_file}}"
}
]
}Coming in desktop 1.99.113: the third migrates up to 20 source files, each in its own worktree with the file as its owned path, and has a reviewer check each result for up to two rounds.
{
"version": 1,
"title": "Migrate source files",
"limits": {
"max_agents": 50,
"concurrency": 4
},
"stages": [
{
"id": "migrate",
"agent": "general",
"isolation": "worktree",
"for_each": {
"files": {
"glob": "src/**/*.ts",
"exclude": [
"**/*.test.ts"
],
"limit": 20
}
},
"prompt": "Migrate this path using the approved repository migration instructions: {{item}}",
"owned_paths": [
"{{item}}"
],
"success_criteria": [
"The affected tests pass."
],
"output": {
"schema": {
"type": "object",
"properties": {
"changed": {
"type": "boolean"
}
},
"required": [
"changed"
],
"additionalProperties": false
}
},
"verify": {
"agent": "explore",
"prompt": "Check the producer's result: {{output}}. This is review round {{round}}.",
"output": {
"schema": {
"type": "object",
"properties": {
"approved": {
"type": "boolean"
}
},
"required": [
"approved"
],
"additionalProperties": false
}
},
"until": {
"path": "approved",
"equals": true
},
"max_rounds": 2,
"on_fail": "keep"
}
}
]
}Limits and defaults
Coming in desktop 1.99.113: by default a run starts at most 100 agents, runs up to 16 at once, takes 40 model steps per agent in all (4,000 for 100 agents), 60 steps for any one agent, and 120 minutes, with no dollar or token ceiling of its own. Its agents still share the request's subagent spend ceiling, $25 by default, and the run counts as one of the request's 32 subagents. One run works at a time in a conversation.
Coming in desktop 1.99.113: the agents at once are also bounded by your computer's processors minus two (at least one) and by the
conversation's free subagent slots, and while workflow agents wait for a slot they leave the last two free
for subagents the agent launches itself. A plan may lower any limit. Only your config raises them, with
budget.workflow: up to 1000 agents, 16 at once, 1440 minutes and 4 runs at once, and
usd, tokens and steps as you choose. Settings → Agents → Workflows in
the desktop app turns workflows on or off, chooses whether a plan within the limits asks first, and sets
the ceilings. A repository may only lower these keys.
{
"permission": { "workflow": "ask" },
"budget": {
"workflow": { "max_agents": 200, "concurrency": 8, "minutes": 240, "usd": 20 }
}
} Coming in desktop 1.99.113: a limit that is reached stops new agents from starting; the token and time limits also stop the agents
that are running. The agents not yet started are skipped and the run ends with partial results and the
reason. While an agent has waited on you for more than a minute, no new agent starts, and the run's card
says it is waiting on you. Set "permission": { "workflow": "deny" }, or
"tools": { "workflow": false }, to remove the workflow tool.
Stop, resume and restarts
Coming in desktop 1.99.113: a run is one card in the Tasks pane, with a bar per stage that loads its agents when you open it. Stop on the card, or Stop including helpers, stops the run and its agents and keeps their work. An update, restart or crash never resumes a run on its own.
Coming in desktop 1.99.113: Resume on the card, vector workflow resume, or the agent's workflow tool with
action: "resume", continues a run that stopped, failed or was interrupted. It reuses every
finished agent whose stage, item, round, prompt, settings, schema and owned paths are unchanged, continues
interrupted agents in their own sessions, reruns failed ones unless you say not to, and accepts an edited
plan, new inputs and higher limits. Agents, spend and tokens carry over, so the ceilings hold across resumes.
A run that is still working cannot be resumed.
Coming in desktop 1.99.113: when the run ends, the conversation gets one note: the outcome, the agents, the time taken, the cost or "unknown", counts per stage and up to five failures, then the path of a file with the full results. A run you started yourself is quiet by default: its note is recorded without starting a turn, unless you ask for a summary.
Saved workflows and trust
Coming in desktop 1.99.113: a saved workflow is a JSON file in a workflow/ or workflows/ folder: the
repository's .vector/workflows/, ~/.vector/workflows/, or workflows/
in Vector's own config folder. The file name is the workflow's name: lowercase letters, digits,
_ and -, starting with a letter or a digit, up to 64 characters. A repository's
file wins over yours of the same name, and two names that differ only in case are both refused. An invalid
file is listed with its problems. A stage may run another saved workflow, one level deep.
Coming in desktop 1.99.113: a repository's workflows load only once you trust the repository, as its agents and commands do, and a company lock on commands turns saved workflows off. Saved workflows are prompt files: Vector asks before an agent edits one, and holds one outside the repository that changed until you approve it; see Prompt files.
In the terminal
Coming in desktop 1.99.113: with the next CLI release, vector workflow validate <file> checks a workflow file
without a server. Attached to one with --attach, vector workflow saved lists its
saved workflows, and with --session as well, list, show,
resume and stop manage a conversation's runs. vector run --workflow <name or
file> runs a saved workflow or a JSON file, with --input key=value for its inputs: it
prints the plan and progress to stderr and the report to stdout, records its note quietly unless you pass
--summarize, and exits 1 when the run fails or is stopped. vector run --workflow
and vector workflow resume refuse to run from an agent's shell or Vector's own terminal.
vector workflow is not vector memory workflow, which shows Workflow insights.
vector workflow validate review.json
vector run --workflow research-sweep --input topic="the HTTP client upgrade"
vector workflow show <runID> --attach http://localhost:4096 --session <id>
Privacy
Coming in desktop 1.99.113: a workflow run sends nothing to Vector's service. Its agents talk to your model provider as subagents do, and the plan, the results and the full results file stay on your computer, in the session and in Vector's data folder. Guests in a shared workspace can see the runs in the sessions they can open, but never a run's spec, and cannot start or resume one. Runs with a workflow in them are left out of the cost figures behind learned defaults, because their agents may still be working when the request ends.
The schema
Coming in desktop 1.99.113: the workflow format is published as a JSON Schema at https://vectordev.ai/workflow.json, so an editor can check a saved workflow as you write it. Vector checks every plan again itself, on every start, resume and nested run.
Older engines and CLIs
Coming in desktop 1.99.113: a desktop app connected to an engine without workflows, such as a Windows WSL server still on the
engine version the desktop requires today, hides /workflow and the workflow controls, and the
CLI that npm and vectordev.ai/install serve today has no vector workflow or
--workflow until the next CLI release. An older desktop or TUI connected to a new engine shows
a workflow run as a subagent named "workflow".