Self-alignment: fit the working prompt to each task
Self-alignment uses Jev to check whether the current request fits the existing system prompt and whether the agent has enough task-relevant guidance. A verified, additive prompt update can shape this run only; the developer's base prompt and later runs remain unchanged.
1. Bring the right instructions into the current task
A system prompt may describe an agent's job but leave gaps for a particular kind of request: which tool to consult, which steps to follow, what a finished answer should contain, or how to handle an exception. Self-alignment asks Jev to compare the request with the existing prompt and the tools the agent actually has.
PR #445 defines 21 fixed yes/no Jev questions. Some check stable prompt-and-tool guidance and can be reused for the same configuration; request-specific questions check whether this task fits and what it needs. Questions that cannot apply, such as tool guidance when the agent has no tools, are skipped.
When the task is in scope and an editable instruction is missing, a constrained editor can add general guidance for that kind of task before the main agent loop begins. The aim is better task-specific fit and fewer avoidable misses—not a guarantee of higher accuracy or a measured performance result. PR #445 does not report a labeled benchmark for its thresholds.
Self-alignment flow
Current system prompt + request + available tools
↓
Jev checks prompt fit
┌────────────┼─────────────┐
fit gate fails owner-only gap agent-owned gap
↓ ↓ ↓
original prompt developer editor adds text
for run action ↓
Jev verifies edit
┌────┴─────┐
confirmed conflict
↓ ↓
run-local original prompt
addition for run2. Fit gates can stop edits before they start
Jev checks whether the request falls within the prompt's scope, stays within its boundaries, and leaves the agent in its declared role. A failed gate returns an out-of-scope result and does not ask the editor to broaden the prompt. The main agent still runs with the original prompt: the fit gate controls self-alignment edits, not execution of the request.
Other gaps belong to the prompt owner, not the editor. Role, scope, boundaries, audience, knowledge, and permissions are developer-owned. Jev reports these as `owner_actions` so the person responsible for the agent can decide whether its base instructions should change.
A fit-gate failure leaves the original prompt in place.
Developer-owned sections are reported for review, never edited by self-alignment.
Self-alignment is skipped when the run supplies a separate caller-owned context system prompt.
3. Edits are additive, section-bound, and checked
If the request fits the agent and Jev finds a gap the editor may address, a separate editor agent uses one tool: `edit_system_prompt_section`. It can add text under tool guidance, method, output, exceptions, priorities, or glossary headings. It must cite the open Jev gap it closes. Existing prompt text is never replaced or removed, and the tool refuses owner-only sections or edits that do not match an identified gap.
Tool alignment means adding prompt guidance about when to use tools the developer already configured. It does not add or remove tools, change their schemas or permissions, or replace their implementations; the actual tool catalog stays under developer control.
After editing, Jev rechecks the cited gaps and consistency. Only sections whose gaps are confirmed closed are kept. If verification fails, edits are rejected; if the edit introduces a new contradiction, all proposed changes are reverted. If Jev or the editor fails, the main run continues with the original prompt.
4. Enable self-alignment for an agent
PR #445 adds the optional `self_align` boolean to `JevAgentSettings`. Set the TypeSafe decision-model credential through `TYPESAFE_API_KEY` or `DecisionModelConfig` for Jev to assess the prompt. Without a usable credential, alignment fails open and the main agent runs with its original prompt.
The API shown here is proposed in PR #445 and is not yet in the default SDK release.
Enable the preview and run a task
import asyncio
from vidbyte import JevAgent, JevAgentSettings
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",
self_align=True,
)
)
result = await agent.arun("Summarize the renewal options for this account.")
print(result.output)
asyncio.run(main())5. Inspect alignment status, edits, and owner actions
The main result keeps its normal output. PR #445 adds a typed `JevAlignmentResult` at `result.metadata["jev_alignment"]`. It records the status, prompt gaps, proposed edits and whether Jev kept each one, developer-facing owner actions, probabilities, usage, and an optional detail string. This is a Python object in result metadata, not a promised JSON response envelope.
Use the report to distinguish a verified prompt addition from an unchanged run. An `owner_actions` entry means the developer should decide whether to update an owner-only prompt section; it is not an automatic edit.
Review one run's alignment result
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)6. Different gaps lead to different safe outcomes
These are possible scenarios, not fixed Jev answers or exact editor-generated wording. Jev assesses each request against the agent's own prompt and configured tools, so the result depends on that configuration.
| Situation | Possible status | What happens |
|---|---|---|
| The prompt has a configured `lookup_plan` tool but does not say when to call it. | aligned | Jev can verify added tool-use guidance; the existing tool catalog stays unchanged. |
| The request needs a specific answer format, but the prompt has no output guidance. | aligned | Jev can verify an additive output-section edit; only this run uses it. |
| A support agent is asked to prepare a tax filing outside its declared scope. | out_of_scope | No prompt edit is made. The original prompt runs, and owner_actions tells the developer to review the fit decision. |
| The prompt already gives relevant method, output, and tool guidance. | no_gaps | No edit is needed; the current run uses the original prompt. |
| The prompt is missing an owner-only fact or permission rule. | no_gaps | The editor leaves it alone; owner_actions tells the developer what to clarify. |
| The editor proposes an addition Jev cannot verify, or that creates a contradiction. | edits_rejected | The proposed addition is reverted; the main run uses the original prompt. |
| The TypeSafe key is missing or Jev/editor service fails. | unavailable | Alignment fails open and the task proceeds with the original prompt. |
| A caller supplies its own context system prompt for this run. | skipped | Self-alignment leaves caller-owned context untouched. |
`no_gaps` means there was no editable gap. Developer-owned `owner_actions` can still be present.
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.7. The base prompt and future runs stay untouched
Verified additions are applied to the run's working context and runtime only. `JevAgentSettings.system_prompt`, the main agent's stored prompt, and the alignment editor's own fixed prompt are not rewritten. The next request begins from the developer's original prompt and is assessed on its own merits.
The editor has a bounded loop and its own generative usage accounting. Jev usage from assessment and verification is reported in the alignment result. Static prompt-and-tool questions are cached for identical configuration; request-dependent checks still run for each task.