Decision Layer: System One, Jev, Clef, and giving AI "decisions with a type"

Article 8/20 in the AgentKit v3 onboarding series. About an 8 minute read.

Before we start, I have to correct something: "Decision Layer" is not yet the name of a feature in AgentKit. You will not find this phrase in ak, in the docs, or on the site. It is just how I refer to an experimental direction: using small models that specialize in structured judgments to help the agent choose correctly instead of guessing.

What exists in ak 3.0.0 is shadow mode 🧪. The rest is direction 🗺️. Read it with that mindset.

1/ The problem to solve

An agent makes hundreds of small decisions every day:

• Which skill should this request use?

• Is this bug simple or complex, and which process does it need?

• Is it risky to split this job across several agents running in parallel?

Right now, those decisions rely on hard rules (regex, lookup tables) or on the big model guessing while it is busy with something else. Hard rules break on unfamiliar questions. The big model burns tokens, and answers differently each time.

The idea: pull those small judgments out and hand them to a model that specializes in judgments, returning a typed result with a probability, so ordinary code can use it like a function.

2/ System One and Jev

System One is TypeSafe's model family, which includes Jev. They turn natural language plus application state into typed, probabilistic judgments: pick one of N, score something, yes/no... Code composes those judgments like composing functions.

The kit has a typesafe-ai skill that guides the agent to build features using TypeSafe.

3/ Clef

Clef (clef and clef-flash) is the model name when you pick the Cloudflare provider in the semantic decision config. For now it only appears as a model name in the provider config.

4/ What exists in ak 3.0.0: shadow mode 🧪

ak eval decision runs a shadow comparison: it hands the same situation to the semantic judgment, then compares it with the decision the old rules made. It never replaces the old decision, it only prints the result so you can see whether the new judgment is better.

There are 4 profiles: domain-routing, fix-complexity, orchestration-risk, skill-routing-eval.

Turning it on (by hand, at user scope)

ak config prefs set semantic_decision.enabled true --scope user
ak config prefs set semantic_decision.provider typesafe --scope user

or use Cloudflare:

ak config prefs set semantic_decision.provider cloudflare --scope user

Credentials never live in config. Set them via environment variables or in ~/.agentkit/.env:

• Provider typesafe: TYPESAFE_API_KEY

• Provider cloudflare: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN

The project's .env is not read for these keys. That is deliberate: a stranger's repo cannot switch on a paid provider on your behalf. Project-level config can only turn it off, never on.

Checking

ak doctor --check semantic_decision

Trial run

ak eval decision request.json --validate-only   # check the input file, no provider call
ak eval decision request.json --json

A few safety points I designed in on purpose:

• Calling the command does not turn on a provider by itself.

• It only sends summarized and redacted facts, never raw files, transcripts or credentials.

• It does not store the input.

• It may incur charges from the provider, which is why it demands your explicit consent at user scope.

5/ Why go this slowly?

Because one wrong judgment in skill routing is merely annoying. One wrong judgment in "is this job risky" can be a disaster.

So my process is: shadow first, measure enough, and only then give it real decisions. Only when the shadow numbers show the semantic judgment steadily beating the old rules does it get promoted. For today, it is just the person sitting next to the agent taking notes.

Next article: Installing AgentKit on cloud and CI →

Sources

• ak eval decision --help, ak config prefs set --help (ak 3.0.0): shadow profiles, user scope consent, "never changes the legacy decision"

• Real output of ak doctor --check semantic_decision in a temporary HOME, 02/11/2026

• TypeSafe System One docs: https://docs.typesafe.ai/concepts/system-one.md (cited in the typesafe-ai skill)