Early preview

JevAgent Preflight Questions

Preflight questions are quick checks Jev runs on a request before your agent starts. Turn on the options you need, and Jev can stop an unclear request to ask the user, trim the tools your agent sees, split repeated work across agents, keep a run's goal across follow-ups, or keep a request that only asks for an assessment from changing anything.

Preflight checks the request before work begins

Before your agent starts, Jev answers a few narrow questions about the request. What it does with the answers depends on the options you turn on: only clarity can stop a run, and the others shape the run that goes ahead.

A request, checked before the agent acts

Preflight · early preview

User request

Build a launch plan

Jev · System 2 · before your agent starts

Answers the narrow questions your enabled options add

Clarity
Tool selector
Bulk work
Run-state relation
Read-only

No gap · the request is ready
Your agent starts this run
Shaped by the other options you turned on:
- Tool selector keeps only the tools that could help.
- Bulk work offers a tool that splits repeated work across fresh agents.
- Run-state relation keeps the original goal for a related follow-up.
- Read-only hides tools that write or run commands when the request only asks for an assessment.
Clarity finds a gap · this run stops
Short questions come back to your app
- Who is the launch for?
  - Existing customers
  - New developers
- When does it go live?
  - This month
  - Next quarter
Your app asks the user, then starts a new JevAgent run with the answers. Nothing resumes on its own.

If Jev can't answer, or the questions can't be written, preflight steps aside and your agent runs as usual. A missing or rejected Vidbyte API key, an empty API balance, or a rate or quota limit that outlasts Jev's retries stops the run with an error instead.

Illustrative example; the questions are samples, not recorded output. Clarity is the only option that can stop a run, and only when Jev finds a gap and the questions are written.

What a preflight question is

A preflight question is one narrow yes/no question Jev answers about the request before your agent does anything. Each option you turn on adds a fixed set of these questions and one action Jev takes on the answers.

One narrow question at a time — Each question looks at a single thing, such as whether the request names its target, so a failed check says exactly what is missing instead of calling the request vague.
Answers become one action — Each option turns its answers into one action: stop and ask, hide tools, offer a bulk-work tool, keep a record, or block changes.
One call for most options — Clarity, bulk work, run-state relation, read-only, and the specialist choice go to Jev together, in one call. The tool selector asks its own questions right after, only when your main agent goes ahead.
Outages never block work — If Jev can't answer, each option steps aside and your agent runs as it would without it. Jev's calls use your Vidbyte API key, so a missing or rejected key, an empty API balance, or a rate or quota limit that outlasts Jev's retries stops the run with an error instead.

When to use preflight

Preflight pays off when a wrong start is expensive: the agent does real work, the request comes from a person you can ask, or the agent has more tools or more items than one request needs.

Clarity: Use it whenRequests come from people and are often vague, such as “Build a launch plan.”; What it changesStops the run and returns a few short questions for the user.
Tool selector: Use it whenYour agent has many tools, and most requests need only a few.; What it changesHides tools that couldn't help, for this run only.
Bulk work: Use it whenRequests often ask for the same work on several items, such as “Translate these 20 files.”; What it changesOffers a tool that splits the items across fresh agents working at once.
Run-state relation: Use it whenUsers send follow-ups to work your done checks are tracking.; What it changesKeeps the original goal for related follow-ups instead of replacing it.
Read-only: Use it whenYour agent can change things, but many requests only ask a question, such as “Why is checkout slow?”; What it changesHides tools that write or run commands for a request that only asks for an assessment.

Which preflight option fits which situation
Option	Use it when	What it changes
Clarity	Requests come from people and are often vague, such as “Build a launch plan.”	Stops the run and returns a few short questions for the user.
Tool selector	Your agent has many tools, and most requests need only a few.	Hides tools that couldn't help, for this run only.
Bulk work	Requests often ask for the same work on several items, such as “Translate these 20 files.”	Offers a tool that splits the items across fresh agents working at once.
Run-state relation	Users send follow-ups to work your done checks are tracking.	Keeps the original goal for related follow-ups instead of replacing it.
Read-only	Your agent can change things, but many requests only ask a question, such as “Why is checkout slow?”	Hides tools that write or run commands for a request that only asks for an assessment.

The goal isn't to turn every request into an interview. Each option acts only when its answers say a short check would prevent wasted work.

Every preflight option

The SDK ships five preflight options. Open one to see what it asks, when it acts, its settings, and a working example.

Clarity: stop and ask when the request is missing something

Jev asks 14 narrow questions about the user's message, such as whether it names an action, a target, and the kind of result expected. If the request falls short, the run stops before any work and returns a few short questions for the user, each with suggested answers.

Asks: Detail14 yes/no questions about the request itself, read on its own.
Acts when: DetailThe average answer is below 0.75, or any single answer is below 0.2. A request that asks for no work reports only that gap.
What happens: DetailThe run stops and returns clarifying questions. Your app asks the user and starts a new run; nothing resumes on its own.
Settings: DetailNone. The thresholds are fixed starting points, the same for every agent.
If Jev can't answer: DetailThe check is skipped and your agent runs.
Where to look: DetailThe run's response holds the questions and their suggested answers.

Clarity at a glance
	Detail
Asks	14 yes/no questions about the request itself, read on its own.
Acts when	The average answer is below 0.75, or any single answer is below 0.2. A request that asks for no work reports only that gap.
What happens	The run stops and returns clarifying questions. Your app asks the user and starts a new run; nothing resumes on its own.
Settings	None. The thresholds are fixed starting points, the same for every agent.
If Jev can't answer	The check is skipped and your agent runs.
Where to look	The run's response holds the questions and their suggested answers.

Turn on clarity

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevPreflightPreset,
    JevRuntimeSettings,
)

# Jev, and by default this agent's own model calls, go through Vidbyte with
# VIDBYTE_API_KEY. With OPENAI_API_KEY also set, OpenAI bills the model calls
# and Vidbyte adds a 2% fee; without it, Vidbyte bills OpenAI's cost plus 2%.
agent = JevAgent(
    JevAgentSettings(
        name="launch-planner",
        system_prompt="You plan product launches.",
        provider="openai",
        model_name="gpt-5.4-mini",
    ),
    JevRuntimeSettings(preflight=(JevPreflightPreset.CLARITY,)),
)

reply = agent.run("Build a launch plan.")
clarification = agent.response.clarification
if clarification:
    # The run stopped before any work: ask, then start a new run.
    for item in clarification.questions:
        print(item.question, item.recommendations)

Tool selector: give your agent only the tools that could help

Jev asks one question per tool: could this tool help with the request? Tools that reach the threshold stay available, in their original order, and the rest are hidden for this run only.

Asks: DetailOne yes/no question for each tool your agent has, built from the tool's name, description, and inputs.
Acts when: DetailWhenever your main agent goes ahead. It runs right after the other options, so it never runs on a stopped request or one a specialist takes.
What happens: DetailTools below the threshold are left out of this run. Your agent's permissions don't change.
Settings: DetailThe tool threshold, 0.20 by default, from 0 to 1.
If Jev can't answer: DetailYour agent keeps every tool.
Where to look: DetailThe reply's details say how many tools were kept, out of how many, and Jev's token use.

Tool selector at a glance
	Detail
Asks	One yes/no question for each tool your agent has, built from the tool's name, description, and inputs.
Acts when	Whenever your main agent goes ahead. It runs right after the other options, so it never runs on a stopped request or one a specialist takes.
What happens	Tools below the threshold are left out of this run. Your agent's permissions don't change.
Settings	The tool threshold, 0.20 by default, from 0 to 1.
If Jev can't answer	Your agent keeps every tool.
Where to look	The reply's details say how many tools were kept, out of how many, and Jev's token use.

Turn on the tool selector

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevPreflightPreset,
    JevRuntimeSettings,
    tool,
)

@tool
def search_docs(query: str) -> str:
    """Search the product documentation."""
    return docs_index.search(query)

@tool
def open_ticket(summary: str) -> str:
    """Open a support ticket for the user."""
    return helpdesk.create(summary)

agent = JevAgent(
    JevAgentSettings(
        name="support-agent",
        system_prompt="Help users with product questions.",
        provider="openai",
        model_name="gpt-5.4-mini",
        tools=[search_docs, open_ticket],
    ),
    JevRuntimeSettings(
        preflight=(JevPreflightPreset.TOOL_SELECTOR,),
        tool_selector_threshold=0.2,  # the default
    ),
)

reply = agent.run("How do I rotate my API key?")
# How many tools Jev kept for this run, out of how many, and its token use.
print(reply.metadata.get("jev_tool_selector"))

Bulk work: split repeated work across fresh agents

Jev asks eight questions that together recognize work that splits cleanly: at least two named items, the same work on each, a separate result for each, and no item depending on another. When every answer passes, your agent gets a one-time bulk-work tool: it writes one task per item, fresh copies of the agent run them at the same time, and their results come back to your agent.

Asks: DetailEight yes/no questions: several items, every item identified, the same work, a result per item, independent items, changes kept inside each item, any order, and substantial work per item.
Acts when: DetailEvery answer reaches the threshold on its own. One clear no keeps the work on one agent.
What happens: DetailYour agent is offered the bulk-work tool for this run. Each fresh copy gets the same model, permissions, and limits, and only the tools the selector kept.
Settings: DetailHow many agents one request may split across (4 by default, at least 2), and the threshold every answer must reach (0.75 by default).
If Jev can't answer: DetailThe tool isn't offered, and your agent does the work itself.
Where to look: DetailThe run's response lists each task and what its agent handed back.

Bulk work at a glance
	Detail
Asks	Eight yes/no questions: several items, every item identified, the same work, a result per item, independent items, changes kept inside each item, any order, and substantial work per item.
Acts when	Every answer reaches the threshold on its own. One clear no keeps the work on one agent.
What happens	Your agent is offered the bulk-work tool for this run. Each fresh copy gets the same model, permissions, and limits, and only the tools the selector kept.
Settings	How many agents one request may split across (4 by default, at least 2), and the threshold every answer must reach (0.75 by default).
If Jev can't answer	The tool isn't offered, and your agent does the work itself.
Where to look	The run's response lists each task and what its agent handed back.

Turn on bulk work

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevBulkSettings,
    JevPreflightPreset,
    JevRuntimeSettings,
)

agent = JevAgent(
    JevAgentSettings(
        name="translator",
        system_prompt="You translate product copy.",
        provider="openai",
        model_name="gpt-5.4-mini",
        # The defaults: up to 4 agents; each answer needs 0.75.
        bulk_work=JevBulkSettings(agents=4, threshold=0.75),
    ),
    JevRuntimeSettings(preflight=(JevPreflightPreset.BULK_WORK,)),
)

reply = agent.run("Translate these three emails into French: ...")
if agent.response.bulk_work:
    for handoff in agent.response.bulk_work.handoffs:
        print(handoff.task, handoff.output)

Run-state relation: keep the original goal for related follow-ups

Continuation's done checks write a run state from the request: its goal, its parts, and what not to do. Normally every new request replaces it. With this option, Jev first asks whether the new request relates to the recorded work, and a related follow-up keeps the original record, so the done checks keep judging against the goal the user started with.

Asks: DetailOne yes/no question: does this request relate to the work or content in the existing record? It is asked only when a record exists.
Acts when: DetailRelated: the record is kept unchanged. Unrelated: a new record is written from the new request.
What happens: DetailA correction or a different action on the same project keeps the record; a request that only shares a broad topic replaces it.
Settings: DetailNone. Pair it with continuation's done checks, which use the record.
If Jev can't answer: DetailThe existing record is kept.
Where to look: DetailThe run's response holds the run state the checks used.

Run-state relation at a glance
	Detail
Asks	One yes/no question: does this request relate to the work or content in the existing record? It is asked only when a record exists.
Acts when	Related: the record is kept unchanged. Unrelated: a new record is written from the new request.
What happens	A correction or a different action on the same project keeps the record; a request that only shares a broad topic replaces it.
Settings	None. Pair it with continuation's done checks, which use the record.
If Jev can't answer	The existing record is kept.
Where to look	The run's response holds the run state the checks used.

Turn on run-state relation

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevContinualSettings,
    JevDoneCheck,
    JevPreflightPreset,
    JevRuntimeSettings,
)

agent = JevAgent(
    JevAgentSettings(
        name="release-writer",
        system_prompt="You write SDK release notes.",
        provider="openai",
        model_name="gpt-5.4-mini",
    ),
    JevRuntimeSettings(
        preflight=(JevPreflightPreset.RUN_STATE_RELATION,),
        continual=JevContinualSettings(
            checks=(JevDoneCheck.MULTI_PART,),
        ),
    ),
)

agent.run("Draft the v2.1 notes: auth migration and API changes.")
# A related follow-up keeps the record from the first request.
agent.run("In those notes, say existing API tokens still work.")
print(agent.response.run_state.objective)

Read about continuation and done checks

Read-only: keep a request that only asks for an assessment from changing anything

Jev asks eight questions that together recognize a request that only wants information back, such as an explanation, a diagnosis, a review, or a plan. When every answer passes, the run keeps only tools that are safe or only read, and nothing the run starts can write or run commands. Your agent still answers in full.

Asks: DetailEight yes/no questions: an assessment is asked for, it is the only result, everything stays as it is, every action mentioned is only described, every decision to change something stays with the user, the result belongs in the reply, reading is enough, and an answer alone meets the goal.
Acts when: DetailEvery answer reaches 0.75 on its own. One clear no, such as a request to explain one thing and fix another, keeps every tool.
What happens: DetailTools marked to write or run commands are hidden for this run, and the same limit binds every agent the run starts, including a specialist and bulk-work agents, whatever their own permissions. A tool you don't mark counts as safe and stays.
Settings: DetailNone. The threshold is a fixed starting point, the same for every agent.
If Jev can't answer: DetailYour agent keeps every tool, as it would without this option.
Where to look: DetailThe run's response says whether the read-only limit applied.

Read-only at a glance
	Detail
Asks	Eight yes/no questions: an assessment is asked for, it is the only result, everything stays as it is, every action mentioned is only described, every decision to change something stays with the user, the result belongs in the reply, reading is enough, and an answer alone meets the goal.
Acts when	Every answer reaches 0.75 on its own. One clear no, such as a request to explain one thing and fix another, keeps every tool.
What happens	Tools marked to write or run commands are hidden for this run, and the same limit binds every agent the run starts, including a specialist and bulk-work agents, whatever their own permissions. A tool you don't mark counts as safe and stays.
Settings	None. The threshold is a fixed starting point, the same for every agent.
If Jev can't answer	Your agent keeps every tool, as it would without this option.
Where to look	The run's response says whether the read-only limit applied.

Turn on read-only

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevPreflightPreset,
    JevRuntimeSettings,
    ToolPermission,
    tool,
)

@tool(permission=ToolPermission.READ)
def read_config(path: str) -> str:
    """Read a deployment config file."""
    return config_store.read(path)

@tool(permission=ToolPermission.WRITE)
def update_config(path: str, text: str) -> str:
    """Replace a deployment config file."""
    return config_store.write(path, text)

agent = JevAgent(
    JevAgentSettings(
        name="ops-assistant",
        system_prompt="You review and change deployment configs.",
        provider="openai",
        model_name="gpt-5.4-mini",
        tools=[read_config, update_config],
    ),
    JevRuntimeSettings(preflight=(JevPreflightPreset.READ_ONLY,)),
)

reply = agent.run("Review the staging config and tell me what looks risky.")
# True when Jev judged the request an assessment, so the run could only read.
print(agent.response.read_only)

Read about specialist routing

Turn on several options together

Turn on built-in checks before your agent starts by listing them in one setting. Order doesn't matter, and each option can be listed only once.

Clarity and the tool selector shipped in vidbyte-sdk 0.2.0, run-state relation in 0.2.1, bulk work in 0.3.0 and read-only in 0.4.0, and all five are in 0.4.2, the latest release. The feature is still in early development, and an older installed SDK may not include every option, so check your SDK version before you use the examples.

Combine preflight options

Python

from vidbyte import (
    JevAgent,
    JevAgentSettings,
    JevPreflightPreset,
    JevRuntimeSettings,
)

agent = JevAgent(
    JevAgentSettings(
        name="support-agent",
        system_prompt="Help users with product questions.",
        provider="openai",
        model_name="gpt-5.4-mini",
        tools=[search_docs, open_ticket],
    ),
    JevRuntimeSettings(
        preflight=(
            JevPreflightPreset.CLARITY,
            JevPreflightPreset.TOOL_SELECTOR,
            JevPreflightPreset.BULK_WORK,
        ),
    ),
)

# Plain strings work too. Listing an option twice is an error.
JevRuntimeSettings(
    preflight=("clarity", "tool_selector", "run_state_relation"),
)

What happens when clarity stops a run

Clarity is the one option that can stop a run. A request that passes goes straight to work; a request with a gap stops and returns questions.

Jev checks the request
Jev answers the questions your options add. If the request passes, your agent gets to work as usual.
The run stops with questions
If Jev finds a gap and clarifying questions are written, the run stops before any work is done and returns those questions.
Your app asks the user
Show the questions to the user and collect their answers. JevAgent does not automatically resume the stopped run or merge the user's reply for you.
Send a new request
Start a new JevAgent run with a request that includes the user's answers.

Adding your own checks

The built-in checks can't be extended from inside your app. A new check has to be added to the Vidbyte SDK itself and shipped in an SDK release or a private build. Once your installed SDK includes it, you turn it on the same way as the built-in checks.

Write the questions
Write each new question in plain yes/no form, with clear examples of requests that pass and requests that get flagged.
Add them to the SDK
Add the questions to the SDK as a new check, following the SDK's guide to writing Jev questions.
Test and ship
Test the new check, then ship it in an SDK release or a private build.
Turn the check on
Install that version, then turn the new check on in your agent's Jev settings, just like the built-in options.

JevAgent Preflight Questions

Preflight checks the request before work begins

A request, checked before the agent acts

What a preflight question is

When to use preflight

Every preflight option

Turn on several options together

What happens when clarity stops a run

Jev checks the request

The run stops with questions

Your app asks the user

Send a new request

Adding your own checks

Write the questions

Add them to the SDK

Test and ship

Turn the check on

Next steps

Specialist routing

Continuation

JevAgent

Writing Jev questions