JevAgent Specialist Routing

Write focused agents, let Jev pick the right one

One set of instructions that tries to cover billing, debugging, and release notes does each job less well. Build one focused agent per kind of work, describe what each handles, and your app still talks to just one agent.

At the start of every run, Jev reads the user's request and your specialist descriptions, then picks the one specialist whose job covers the main goal of the request, or none. The chosen specialist handles the entire task with its own instructions, model, tools, and permissions. If none fits, your main agent handles it.

One request, one best-fit agent

Illustrative · no Jev output shown

Request

Refund a double charge

Jev · System 2

Which scope covers the request's main outcome?

Best-fit specialist
Billing agent runs the whole task
Uses its own prompt, model, tools, and permissions.
Reserved option · None
Main JevAgent keeps the task
Used when no specialist scope covers the main outcome.

This is an illustrative route, not recorded Jev output. Jev chooses its top-ranked option; there is no match threshold. When no single scope covers the request's main outcome, `none` keeps the task on the main JevAgent.

Set up specialist routing

Three steps: build each specialist, describe the work it handles, and add the specialists to a JevAgent. Setting up specialists never calls Jev; routing needs a TypeSafe API key only when a run starts.

Build each specialist as an ordinary agent
A specialist is just a regular agent. Give each one focused instructions and only the tools its job needs. Specialists don't have to share a provider or a model, so you can put a low-cost model on routine work and a stronger one on hard problems.
Looks up invoices and handles refunds, payment failures, and plan changes.
Create a focused agent
Python
1from vidbyte import Agent, tool 2 3@tool 4def lookup_invoice(invoice_id: str) -> dict[str, str]: 5 """Return the status, amount, and due date for one invoice.""" 6 return billing_api.invoice(invoice_id) 7 8billing = Agent( 9 name="billing", 10 system_prompt=( 11 "You resolve invoices, refunds, and plan changes. " 12 "Always look up the invoice before quoting an amount." 13 ), 14 provider="openai", 15 model_name="gpt-4.1-mini", 16 tools=[lookup_invoice], 17)
When Jev picks a specialist, that agent handles the request exactly as it would on its own.

Describe what each specialist handles

Give each specialist a unique name and a description of the work it handles. Jev routes using only the request and these descriptions; it never reads a specialist's instructions and doesn't guess from the name.

Describe the work, not the persona

Python

from vidbyte import JevSpecialist

specialists = (
    JevSpecialist(
        title="billing",
        description="Invoices, refunds, payment failures, and plan upgrades or downgrades for an existing account.",
        agent=billing,
    ),
    JevSpecialist(
        title="debugger",
        description="Diagnosing errors, stack traces, failed API requests, and unexpected responses from the public API.",
        agent=debugger,
    ),
    JevSpecialist(
        title="release_notes",
        description="Writing or editing release notes and changelog entries from merged pull requests.",
        agent=release_writer,
    ),
)

# Weak descriptions Jev cannot route on reliably:
#   description="Billing agent."                          -> no scope to compare against
#   description="You are a friendly expert. Always..."    -> persona instructions, not scope

Name: RuleRequired, unique, and never “none”.; Why“none” is reserved for keeping a request on your main agent.
Description: RuleRequired.; WhyJev reads it on every run to decide where requests go.
Agent: RuleAny regular agent.; WhyThe chosen specialist handles the request just as it would on its own.
Number of specialists: RuleUp to 254 per JevAgent.; WhyOne more slot is reserved for “none”.

Rules for each specialist
Setting	Rule	Why
Name	Required, unique, and never “none”.	“none” is reserved for keeping a request on your main agent.
Description	Required.	Jev reads it on every run to decide where requests go.
Agent	Any regular agent.	The chosen specialist handles the request just as it would on its own.
Number of specialists	Up to 254 per JevAgent.	One more slot is reserved for “none”.

Add your specialists to JevAgent
Add the specialists to your JevAgent's agent settings. The JevAgent's own instructions and model make up your main agent, which answers whenever no specialist fits, so write its instructions for a capable generalist, not a router.
One front door
Python
1from vidbyte import JevAgent, JevAgentSettings, JevRuntimeSettings 2from vidbyte.lib.config import DecisionModelConfig 3 4# load_secret stands in for your own secret store. 5 6agent = JevAgent( 7 JevAgentSettings( 8 name="support-desk", 9 system_prompt=( 10 "You are a general product support agent. Answer questions about the product " 11 "and hand off clearly when you cannot resolve something." 12 ), 13 provider="openai", 14 model_name="gpt-4.1-mini", 15 agents=specialists, 16 ), 17 JevRuntimeSettings( 18 decision=DecisionModelConfig(api_key=load_secret("typesafe")), # or set TYPESAFE_API_KEY 19 ), 20)
Routing uses Jev, so it needs a TypeSafe API key. With no specialists added, JevAgent skips routing entirely.

What happens when a request comes in

Run your agent as usual. Routing happens once, before any work starts, and it is decided together with any preflight checks you've turned on, so it never adds an extra Jev call. Pick a scenario to trace its path.

If a preflight check stops the run to ask the user a question, no agent runs. Otherwise, if Jev picks a specialist, that specialist handles the request and its reply is returned. Every other path leads to your main agent. Jev only looks at the current request.

Trace one run

Illustrative

“Refund one of the two charges on INV-2291” → Jev ranks billing first. The billing agent runs with its lookup_invoice tool.

1
One combined Jev request
Your enabled preflight questions plus the specialist Choice question, in a single TypeSafe call.
↳ missing key, provider error, or no answer → main JevAgent
2
Preflight presets
An enabled preset such as CLARITY can stop the run to ask the user a clarifying question.
↳ gate stops → no agent runs
3
Catalog check
With agents=() the request carried no specialist question.
↳ empty catalog → main JevAgent
4
Jev's top-ranked option
One specialist title, or the reserved none.
↳ none → main JevAgent

Specialist runs the whole task

Runs the task

specialist.agent.arun(prompt) with its own prompt, model, tools, and loop

Main JevAgent loop

JevAgent's own prompt, model, tools, and tool selector

Every exit that leads to the main JevAgent is fail-open: the task still runs, and agent.response.specialist is None. Only a preflight preset can stop a run.

Combine routing with preflight checks

You can turn on preflight checks alongside routing, and all of Jev's questions are still asked together in one go.

Clarity check — An unclear request stops before any specialist runs, and the reply is a short list of clarifying questions.
Tool selector — Jev trims your main agent's tools for each run. A chosen specialist always keeps its own tools.

Routing plus preflight

Python

from vidbyte import JevAgent, JevAgentSettings, JevPreflightPreset, JevRuntimeSettings

# search_docs and open_ticket stand in for your own @tool functions.

agent = JevAgent(
    JevAgentSettings(
        name="support-desk",
        system_prompt="You are a general product support agent.",
        provider="openai",
        model_name="gpt-4.1-mini",
        tools=[search_docs, open_ticket],
        agents=specialists,
    ),
    JevRuntimeSettings(
        preflight=(JevPreflightPreset.CLARITY, JevPreflightPreset.TOOL_SELECTOR),
        tool_selector_threshold=0.2,  # the default; applies to the main agent's tools only
    ),
)

See which agent answered

The reply comes back like any other. After each run, the response tells you which specialist handled the task, or that your main agent did, along with Jev's usage and whether the run stopped for clarification.

Inspect the response record

Python

reply = await agent.arun("I was charged twice for invoice INV-2291. Can you refund one of them?")
print(reply.content)

response = agent.response
if response.needs_clarification:
    print("Jev asked the user to clarify first")
elif response.specialist is not None:
    print(f"{response.specialist} answered")
else:
    print("the main JevAgent answered")

if response.usage:
    print("Jev decision tokens:", response.usage.input_tokens, response.usage.output_tokens)

A specialist's name: WhenJev picked that specialist, and it handled the whole task.
None: WhenJev picked none, Jev was unavailable, no specialists are set up, or a preflight check stopped the run.

What the response says about who answered
Who answered	When
A specialist's name	Jev picked that specialist, and it handled the whole task.
None	Jev picked none, Jev was unavailable, no specialists are set up, or a preflight check stopped the run.

The response always describes the most recent run. Check whether the run stopped for clarification to tell a stopped run apart from one your main agent handled.

Isolation and failure behavior

Routing is designed so the work always gets done and a task never runs twice.

One decision per run — Routing is decided once, before any work starts. Specialists never hand work to each other partway through.
No score to tune — Jev's top pick always wins. Clear, narrow descriptions are how you control routing.
Fails open — If Jev is unavailable, your main agent handles the task, so your app keeps answering even without a TypeSafe key.
No silent retry — If a specialist fails after it starts, you get the error. The task isn't retried on your main agent, because the specialist may already have taken actions.
Tools stay separate — Each specialist keeps its own tools. The tool selector only applies when your main agent handles the task.

Example: a support desk with three specialists

One agent fronts billing, API debugging, and account security, and each specialist gets only the tools its job needs. Only the billing specialist can issue refunds, so a request that mixes kinds of work never reaches that tool: it goes to the main agent, which has no tools.

support_desk.py

Python

import asyncio

from vidbyte import Agent, JevAgent, JevAgentSettings, JevRuntimeSettings, JevSpecialist, ToolPermission, tool
from vidbyte.tools.security import PermissionPolicy

# billing_api, logs_api, and auth_api stand in for your own service clients.

@tool
def lookup_invoice(invoice_id: str) -> dict[str, str]:
    """Return the status, amount, and due date for one invoice."""
    return billing_api.invoice(invoice_id)

@tool(permission=ToolPermission.WRITE)
def issue_refund(invoice_id: str, amount_cents: int) -> str:
    """Refund part or all of one paid invoice."""
    return billing_api.refund(invoice_id, amount_cents)

@tool
def search_request_logs(request_id: str) -> list[dict[str, str]]:
    """Return gateway log lines for one API request ID."""
    return logs_api.search(request_id)

@tool
def list_active_sessions(account_id: str) -> list[dict[str, str]]:
    """List signed-in devices and API keys for one account."""
    return auth_api.sessions(account_id)

billing = Agent(
    name="billing",
    system_prompt="You resolve invoices and refunds. Look up the invoice before quoting or refunding any amount.",
    provider="openai",
    model_name="gpt-4.1-mini",
    tools=[lookup_invoice, issue_refund],
    permission_policy=PermissionPolicy.allow_all(),  # billing may call its WRITE refund tool
)

debugger = Agent(
    name="debugger",
    system_prompt="You diagnose failed API calls from request IDs and stack traces, then propose the smallest fix.",
    provider="anthropic",
    model_name="claude-sonnet-5",
    tools=[search_request_logs],
)

security = Agent(
    name="security",
    system_prompt="You help users secure their account: review sessions and explain how to rotate keys. Never reveal secrets.",
    provider="openai",
    model_name="gpt-4.1",
    tools=[list_active_sessions],
)

desk = JevAgent(
    JevAgentSettings(
        name="support-desk",
        system_prompt="You are a general support agent. Answer product questions and say clearly when a human is needed.",
        provider="openai",
        model_name="gpt-4.1-mini",
        agents=(
            JevSpecialist(
                title="billing",
                description="Invoices, charges, refunds, and payment failures on an existing account.",
                agent=billing,
            ),
            JevSpecialist(
                title="api_debugging",
                description="Diagnosing failed or unexpected public API requests from request IDs, status codes, or stack traces.",
                agent=debugger,
            ),
            JevSpecialist(
                title="account_security",
                description="Reviewing signed-in sessions and API keys, suspected account compromise, and key rotation.",
                agent=security,
            ),
        ),
    ),
    JevRuntimeSettings(),  # TypeSafe key read from TYPESAFE_API_KEY
)

TICKETS = [
    "I was charged twice for INV-2291. Please refund the duplicate.",
    "Request req_8f2c returned 500 from /v1/roadmaps. What broke?",
    "I don't recognize a device signed in to my account. What should I do?",
    "What's the difference between the Pro and Team plans?",
]

async def main():
    for ticket in TICKETS:
        reply = await desk.arun(ticket)
        handler = desk.response.specialist or "main agent"
        print(f"[{handler}] {ticket}")
        print("   ", reply.content[:120], "...")

asyncio.run(main())

What a run might print

Illustrative output: each ticket goes to the specialist whose description covers it, and the plan question stays on the main agent.

What a run might print

[billing] I was charged twice for INV-2291. Please refund the duplicate.
    I found two charges of $49.00 on INV-2291 and refunded the second one ...
[api_debugging] Request req_8f2c returned 500 from /v1/roadmaps. What broke?
    The gateway log shows an upstream timeout after 30s while generating module 4 ...
[account_security] I don't recognize a device signed in to my account. What should I do?
    There are three active sessions. The one from an unfamiliar Linux device ...
[main agent] What's the difference between the Pro and Team plans?
    Pro is for one person; Team adds shared workspaces and seat management ...

Example: an engineering copilot with clarity preflight

The specialists run on different model providers, and one of them can query a copy of the production database. Its description is kept narrow, so only questions that need a metrics answer reach that tool, and the clarity check asks about unclear requests before any agent runs.

eng_copilot.py

Python

import asyncio

from vidbyte import Agent, JevAgent, JevAgentSettings, JevPreflightPreset, JevRuntimeSettings, JevSpecialist, tool
from vidbyte.lib.config import DecisionModelConfig

# replica and load_secret stand in for your own database client and secret store.

@tool
def run_readonly_sql(query: str) -> list[dict[str, object]]:
    """Run one SELECT statement against the analytics replica and return at most 200 rows."""
    return replica.select(query, limit=200)

reviewer = Agent(
    name="code-reviewer",
    system_prompt=(
        "You review diffs for correctness, security, and readability. "
        "Rank findings by severity and quote the exact lines."
    ),
    provider="anthropic",
    model_name="claude-sonnet-5",
)

analyst = Agent(
    name="sql-analyst",
    system_prompt="You answer product-metrics questions by writing and running read-only SQL, then explain the result.",
    provider="openai",
    model_name="gpt-4.1",
    tools=[run_readonly_sql],
    max_iterations=6,
)

scribe = Agent(
    name="incident-scribe",
    system_prompt="You turn incident timelines and chat logs into blameless postmortems with action items.",
    provider="openai",
    model_name="gpt-4.1-mini",
)

copilot = JevAgent(
    JevAgentSettings(
        name="eng-copilot",
        system_prompt="You are a senior engineer who answers general engineering questions concisely.",
        provider="openai",
        model_name="gpt-4.1-mini",
        agents=(
            JevSpecialist(
                title="code_review",
                description="Reviewing a pasted diff or code snippet for bugs, security issues, and readability.",
                agent=reviewer,
            ),
            JevSpecialist(
                title="metrics_sql",
                description="Answering questions about product usage metrics that require querying the analytics database. Not schema design or database advice.",
                agent=analyst,
            ),
            JevSpecialist(
                title="postmortem",
                description="Writing a postmortem or incident summary from a pasted timeline or chat log.",
                agent=scribe,
            ),
        ),
    ),
    JevRuntimeSettings(
        decision=DecisionModelConfig(api_key=load_secret("typesafe")),
        preflight=(JevPreflightPreset.CLARITY,),
    ),
)

async def ask(prompt: str) -> None:
    reply = await copilot.arun(prompt)
    response = copilot.response
    if response.needs_clarification:
        print("→ Jev asked for clarification first")
    else:
        print(f"→ {response.specialist or 'main agent'}")
    print(reply.content, "\n")

async def main():
    await ask("How many workspaces created a roadmap in the last 7 days?")
    await ask("Review this diff:\n- if user.is_admin:\n+ if user.is_admin or DEBUG:")
    await ask("Should we pick Postgres or DynamoDB for an append-only event log?")

asyncio.run(main())

Example: a study coach that routes every message

A learning app can route each message on its own. Jev reads only the current message, and the chosen specialist only sees that message, so each message should carry its own topic.

A bare follow-up like "now quiz me on it" still reaches the quiz maker, but that agent never saw the earlier conversation, so include the subject in the message.

study_coach.py

Python

import asyncio

from vidbyte import Agent, JevAgent, JevAgentSettings, JevRuntimeSettings, JevSpecialist

socratic_tutor = Agent(
    name="socratic-tutor",
    system_prompt=(
        "You coach learners through problems with guiding questions. "
        "Never state the final answer; ask one question at a time."
    ),
    provider="anthropic",
    model_name="claude-sonnet-5",
)

explainer = Agent(
    name="concept-explainer",
    system_prompt="You explain a concept from first principles in under 200 words, then give one concrete example.",
    provider="openai",
    model_name="gpt-4.1-mini",
)

quiz_maker = Agent(
    name="quiz-maker",
    system_prompt="You write 5 retrieval-practice questions on the topic being studied, with answers hidden at the end.",
    provider="openai",
    model_name="gpt-4.1-mini",
)

coach = JevAgent(
    JevAgentSettings(
        name="study-coach",
        system_prompt="You are a friendly study coach. Help plan study sessions and answer general learning questions.",
        provider="openai",
        model_name="gpt-4.1-mini",
        agents=(
            JevSpecialist(
                title="homework_help",
                description="Helping a learner work through a specific homework or practice problem they are stuck on.",
                agent=socratic_tutor,
            ),
            JevSpecialist(
                title="explain_concept",
                description="Explaining what a concept, term, or theorem means.",
                agent=explainer,
            ),
            JevSpecialist(
                title="make_quiz",
                description="Creating practice questions or a quiz on a topic.",
                agent=quiz_maker,
            ),
        ),
    ),
    JevRuntimeSettings(),
)

CONVERSATION = [
    "What does the chain rule actually say?",
    "I'm stuck on d/dx of sin(x^2). Can you help me get there myself?",
    "Now quiz me on the chain rule.",
    "How should I split 6 hours of study across calculus and physics this week?",
]

async def main():
    for message in CONVERSATION:
        reply = await coach.arun(message)
        who = coach.response.specialist or "general coach"
        print(f"you:   {message}")
        print(f"{who}: {reply.content[:100]} ...\n")

asyncio.run(main())

Where each message went

Illustrative routing for the four messages in the script.

Where each message went

"What does the chain rule actually say?"            → explain_concept
"I'm stuck on d/dx of sin(x^2)..."                   → homework_help   (asks, never tells)
"Now quiz me on the chain rule."                     → make_quiz       (the topic is in the message)
"How should I split 6 hours of study..."             → general coach   (none)

View specialist routing on GitHub

Specialist routing: one agent front door, many experts behind it

Write focused agents, let Jev pick the right one

One request, one best-fit agent

Set up specialist routing

Build each specialist as an ordinary agent

Describe what each specialist handles

Add your specialists to JevAgent

What happens when a request comes in

Combine routing with preflight checks

See which agent answered

Isolation and failure behavior

Example: a support desk with three specialists

Example: an engineering copilot with clarity preflight

Example: a study coach that routes every message

Next steps

Pair routing with continuation

Preflight questions

Usage and pricing

JevAgent