Optional capability · Preview

Self-alignment: fit the working prompt to each task

Self-alignment lets Jev check whether your agent's instructions cover the task in front of it, then add focused, verified guidance for that one run. Your saved instructions and future runs stay unchanged.

Bring the right instructions into the current task

An agent's instructions may describe its job well but leave gaps for a particular request: which tool to use, which steps to follow, or what a finished answer should contain. Self-alignment has Jev compare the request with your agent's instructions and the tools it actually has.

Check fit, then make a verified run-local edit

Self-alignment · SDK PR #445 preview

Input

Current prompt + request + configured tools

Jev · System 2

Does the task fit, and what guidance is missing?

Out of scope
Use the original prompt
No edit is made; the task still runs.
Owner-only gap
Developer reviews it
Role, scope, boundaries, and permissions stay developer-owned.

Editable gap
Add guidance, then verify
Only additive guidance for configured tools or task steps is proposed.
1. Verified
  Use the addition for this run only.
2. Not verified
  Discard it; use the original prompt.

Self-alignment does not change tools, permissions, or the developer's base prompt. Any verified addition applies to this run only; if Jev or the editor is unavailable, the main run uses the original prompt.

What Jev checks

Jev works through 21 fixed yes/no questions. When the request fits your agent's job and helpful guidance is missing, short guidance for that kind of task is added before your agent starts.

Setup questions — Look at your agent's setup in general and are reused while that setup stays the same.
Request questions — Look at this specific request and run every time.
Skipped questions — Questions that don't apply, such as tool guidance for an agent with no tools, are skipped.

Requests outside your agent's job are left alone

Jev first checks that the request falls within your agent's job, stays within its limits, and keeps it in its intended role. If it doesn't, no guidance is added; your agent still handles the request with its original instructions.

Outside your agent's job — If the request falls outside your agent's job, the original instructions are used unchanged.
Yours to decide — Your agent's role, scope, limits, audience, background knowledge, and permissions are reported as suggested actions for you to review, never changed automatically.
Your own instructions — Self-alignment is skipped when your app supplies its own instructions for a run.

Guidance is only added, never replaced, and always checked

When the request fits and a gap can be filled, a separate editor adds short guidance to the right part of your agent's instructions. Nothing you wrote is removed or replaced, and every addition must address a specific gap Jev found.

What can be added — How to use its tools, the method to follow, what the output should look like, how to handle exceptions, what to prioritize, or what terms mean.
Tools stay the same — Tool guidance only explains when to use tools you already gave your agent. Self-alignment never adds or removes tools or changes what they are allowed to do.
Verified before use — After an edit, Jev checks again that the gap is closed and that nothing contradicts. Only verified additions are kept, and if an addition creates a conflict, every change is thrown out.
Fails safe — If Jev or the editor is unavailable, your agent runs with its original instructions.

Turn on self-alignment

Self-alignment is a single on/off setting in your agent's Jev settings. It needs a TypeSafe API key so Jev can review the instructions; without one, your agent simply runs with its original instructions.

Enable the preview and run a task

Python

import asyncio

from vidbyte import JevAgent, JevAgentSettings, JevRuntimeSettings

async def main():
    agent = JevAgent(
        JevAgentSettings(
            name="support-agent",
            system_prompt="You help account admins with subscription questions.",
            provider="openai",
            model_name="gpt-4.1-mini",
        ),
        JevRuntimeSettings(
            self_align=True,
        ),
    )
    result = await agent.arun("Summarize the renewal options for this account.")
    print(result.content)

asyncio.run(main())

See what self-alignment did

Your agent's reply comes back as usual. Alongside it, each run includes an alignment report: whether guidance was added, which gaps Jev found, which additions were kept or thrown out, and any suggested actions for you.

Review one run's alignment result

Python

alignment = result.metadata["jev_alignment"]
print("status:", alignment.status.value)

for gap in alignment.gaps:
    print("gap:", gap.question, gap.section.value)

for edit in alignment.edits:
    outcome = "kept" if edit.kept else "reverted"
    print(outcome, edit.section.value, edit.content)

for action in alignment.owner_actions:
    print("developer action:", action)

if alignment.detail:
    print("detail:", alignment.detail)

Use the report to tell a run that got extra guidance apart from one that ran unchanged. A suggested action is something for you to decide about your agent's instructions; nothing is changed for you.

Different gaps lead to different safe outcomes

These are example scenarios, not exact Jev answers or wording. Results depend on your agent's own instructions and tools.

Your agent has a lookup_plan tool, but its instructions don't say when to use it.: Possible statusaligned; What happensJev can verify added guidance on when to use the tool; the tool catalog stays unchanged.
The request needs a specific answer format, but the instructions don't describe one.: Possible statusaligned; What happensJev can verify added guidance on the output format; only this run uses it.
A support agent is asked to prepare a tax filing, which is outside its job.: Possible statusout_of_scope; What happensNo guidance is added. The original instructions are used, and a suggested action asks you to review the decision.
The instructions already cover the method, output, and tools.: Possible statusno_gaps; What happensNothing needs adding; the run uses the original instructions.
The instructions are missing a fact or permission rule that only you can decide.: Possible statusno_gaps; What happensThe editor leaves it alone, and a suggested action tells you what to clarify.
An addition can't be verified, or it creates a contradiction.: Possible statusedits_rejected; What happensThe addition is thrown out; the run uses the original instructions.
The TypeSafe key is missing, or Jev or the editor is unavailable.: Possible statusunavailable; What happensSelf-alignment steps aside and the task runs with the original instructions.
Your app supplies its own instructions for this run.: Possible statusskipped; What happensSelf-alignment leaves them untouched.

Example situations and their self-alignment outcomes
Situation	Possible status	What happens
Your agent has a lookup_plan tool, but its instructions don't say when to use it.	aligned	Jev can verify added guidance on when to use the tool; the tool catalog stays unchanged.
The request needs a specific answer format, but the instructions don't describe one.	aligned	Jev can verify added guidance on the output format; only this run uses it.
A support agent is asked to prepare a tax filing, which is outside its job.	out_of_scope	No guidance is added. The original instructions are used, and a suggested action asks you to review the decision.
The instructions already cover the method, output, and tools.	no_gaps	Nothing needs adding; the run uses the original instructions.
The instructions are missing a fact or permission rule that only you can decide.	no_gaps	The editor leaves it alone, and a suggested action tells you what to clarify.
An addition can't be verified, or it creates a contradiction.	edits_rejected	The addition is thrown out; the run uses the original instructions.
The TypeSafe key is missing, or Jev or the editor is unavailable.	unavailable	Self-alignment steps aside and the task runs with the original instructions.
Your app supplies its own instructions for this run.	skipped	Self-alignment leaves them untouched.

A status of no_gaps means there was nothing the editor could add. You may still get suggested actions to review.

See one verified addition

An illustrative run-local addition: the editor adds one line under the existing output section, and only this run uses it.

One verified section edit

BASE SYSTEM PROMPT
You help account admins with subscription questions.

EXISTING OUTPUT SECTION
For renewal summaries, list the available options and the next action.

VERIFIED ADDITION UNDER THE OUTPUT SECTION · THIS RUN ONLY
For renewal summaries, compare each option by term and renewal date, then end with the next action.

Your saved instructions and future runs stay untouched

Additions apply to the current run only. Your saved instructions are never rewritten, and the next request starts fresh from your original instructions.

Bounded editor — The editor works within a fixed limit, and its usage is reported separately, along with Jev's.
Reused setup checks — Checks about your agent's general setup are reused while that setup stays the same; checks about the request run every time.

View self-alignment on GitHub