VidbyteVidbyte

Browse docs

Preflight questions

keys
OverviewQuickstartAuth & KeysPricingDeveloper guidelinesRate limitsSecurityBlogContactSDKsAgentsCLIOverviewResearchJevAgentPreflight questionsSelf-alignment

Preflight questions: clarify before the agent commits

Preflight questions are designed to let Jev inspect an incoming task for missing, decision-critical information before the generative agent begins its full tool loop. This page describes the intended behavior; PR #437 does not ship the feature or a supported configuration API for it.

1. Catch ambiguity before it becomes wasted work

A capable agent can still head in the wrong direction when a request leaves out a constraint that changes the answer: target audience, required format, operating environment, or the user's definition of done. A general model may guess and begin using tools before anyone notices the mismatch.

Preflight puts a narrow System 2 decision point before that work. Jev evaluates whether clarification is likely to change the plan. The goal is not to turn every prompt into an interview; it is to ask only when a focused answer can prevent materially misdirected execution.

2. One short clarification gate, then the normal agent loop

The intended sequence is request → preflight decision → optional user clarification → normal generative run. If the request is already actionable, the agent proceeds without adding friction. If an important decision is underdetermined, it asks a small set of targeted questions, incorporates the answers, and only then starts the full task.

Before the agent starts

User request
    ↓
Jev checks: is decision-critical context missing?
    ├─ No  → System 1 starts the normal agent loop
    └─ Yes → Ask focused preflight question(s)
                 ↓
              User answers
                 ↓
              System 1 starts with the clarified task

3. The intended developer experience

The snippet below communicates the direction, not a working API contract. No `preflight` setting or `PreflightQuestions` type is included in the SDK scaffold from PR #437. Field names, answer handling, and runtime semantics remain subject to implementation.

Proposed configuration shape

Python
# Planned API — illustrative only; not supported by PR #437. settings = JevAgentSettings( name="support-agent", system_prompt="Help the user resolve account questions.", provider="openai", model_name="gpt-4.1-mini", preflight=PreflightQuestions(enabled=True), # proposed shape )
Do not rely on this configuration in an application today. The current JevAgent scaffold has no preflight setting and does not call the Jev decision model during its agent loop.

4. Ask only when the answer can change the work

Target missing details that materially affect the plan or output.

Keep questions focused; do not ask for context the request already supplies.

Let the normal generative model handle the task after clarification rather than asking Jev to write the user-facing response.

Treat question counts, confidence thresholds, interruption policy, and timeout behavior as undecided until the SDK defines them.