AI Development

Gemini Decisions API: Cheap, Calibrated Routing for AI Agents

Most agents spend a generative model call deciding what to do next. Google's new decision model answers those closed questions directly, with a probability attached. Here's how to put it in the router slot, and where it stops making sense.

November 17, 2026
-
11 min read
-Last updated: 2026-11-17
GeminiDecisions APIAgent RoutingModel RoutingAI Agents

The Gemini Decisions API (gemini-decision-1, launched November 11, 2026) answers closed questions about an input instead of generating text: yes/no, pick-one, or a rubric score, each with a probability. At $0.10 per million input tokens and no output billing, it fits the router slot in an agent: which tool, which model tier, act or escalate.

TL;DR
  • One call scores up to 1,000 independent questions against one shared input of up to 262,144 tokens: text, images, audio, video or PDF.
  • You pay only for input. A 500-token routing decision costs $0.00005, so a million decisions is about $50.
  • The probability is the feature. Act on confident answers, send the ambiguous band to a stronger model or a person.
  • It doesn't write, explain, chain answers, cache context or run in batch. Keep a generative model for everything after the decision.

What is the Gemini Decisions API?

The Gemini Decisions API is a separate endpoint in the Gemini Developer API that scores a fixed set of answers instead of generating tokens. You send one input and a list of questions. You get back typed answers with probabilities, no free text to parse. Google announced it on its developer blog on November 11, 2026, alongside the model that powers it, Gemini Decision 1.

I care about this for one reason. In a typical agent loop, a lot of model calls aren't doing the work. They're deciding what work to do: does this message need a tool, which one, is this a job for the cheap model or the expensive one, should a human look first. Those are classification problems, usually paid for at generative prices, plus a JSON parser and retry logic for when the small model wanders off format.

Google says median model compute is 50-100 ms, or 150-250 ms end to end, for inputs up to 16K tokens. Google also runs its own product on it: Gemini Notebook uses the Decisions API as a real-time router that sends each query to the right model tier. That's the pattern this post is about.

What I did and didn't test. This guide is built from Google's launch post, its v1beta API as documented in the launch coverage, and the published prices. I haven't yet benchmarked Decision 1 on my own agents' traffic, so the thresholds below are starting points to tune, not measured results. Every benchmark number here is Google's.

It's already reachable outside Google's SDK. Vercel added it to AI Gateway the same week, and there are integrations for LangChain, OpenRouter and LiteLLM.

How do the Gemini Decisions API question types work?

There are three question types, and you can mix them in one request. Each question gets a name you choose, a type, and plain-text instructions. Choice and score questions also take a list of options or levels.

TypeWhat you get backRouter use
noul (yes/no)Probability the statement holds, 0-1Gates: needs a tool? needs a human? is this safe?
choiceOne probability per option, 2-255 optionsPick the tool, the model tier, the queue
scoreA level on an ordered rubric, 2-255 levels, lowest firstGrade an answer, rate urgency or difficulty

The yes/no type really is spelled noul in the v1beta API. Google recommends 2-10 levels for score questions even though 255 are allowed. Fewer levels with clear descriptions beat a fine-grained scale nobody can tell apart.

The SDK is google-genai 3.2.0 or later, pointed at the v1beta API version:

bashterminal
pip install "google-genai>=3.2.0"
export GEMINI_API_KEY="..."   # from Google AI Studio
pythondecide.py
import os
from google import genai

client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options={"api_version": "v1beta"},
)

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

print(result.answers["is_damaged"])

One constraint shapes everything that follows: questions are independent. Each one sees the shared input, never another question's answer. You can ask 1,000 questions for nearly the price of one, but you can't write "if the answer to question 1 is yes, then..." inside a call.

How to use the Gemini Decisions API as an agent router

Make the decision call the first thing that happens on each turn, and only call a generative model on the branch it picks. Ask every routing question at once, flat, even ones you'll only need on some branches. Unused answers cost a few tokens of question text. A second round trip costs another 150-250 ms.

Here's a router that answers the three questions most of my agents ask before doing anything: does this need a tool, which tool, and how much model does it need. The tier names are deliberately generic. The same router can pick between Claude Haiku, Sonnet and Opus as easily as between Gemini Flash-Lite, Flash and Pro.

pythonrouter.py
import os
from dataclasses import dataclass
from google import genai

client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options={"api_version": "v1beta"},
)

TOOLS = ["search_docs", "run_sql", "create_ticket", "none"]
TIERS = ["small", "medium", "large"]  # e.g. Haiku / Sonnet / Opus, or Flash-Lite / Flash / Pro

QUESTIONS = {
    "needs_tool": {
        "type": "noul",
        "instructions": "Does answering this request require calling an external tool?",
    },
    "which_tool": {
        "type": "choice",
        "instructions": (
            "Which tool fits best? search_docs: product documentation. "
            "run_sql: questions about our own usage data. "
            "create_ticket: the user reports a bug or asks for a change. "
            "none: no tool fits."
        ),
        "options": TOOLS,
    },
    "model_tier": {
        "type": "choice",
        "instructions": (
            "How hard is this request? small: lookup or rephrase. "
            "medium: multi-step but routine. large: open-ended reasoning or code changes."
        ),
        "options": TIERS,
    },
}


@dataclass
class Route:
    needs_tool: float          # probability 0-1
    tool: dict[str, float]     # option -> probability
    tier: dict[str, float]


def probs(answer) -> dict[str, float] | float:
    """The one place that knows the response shape. v1beta: adjust here if fields change."""
    if hasattr(answer, "options"):
        return {o.label: o.probability for o in answer.options}
    return answer.probability


def route(user_msg: str, context: str = "") -> Route:
    result = client.decisions.create(
        model="gemini-decision-1",
        input=f"{context}\n\nUser request:\n{user_msg}",
        questions=QUESTIONS,
    )
    a = result.answers
    return Route(
        needs_tool=probs(a["needs_tool"]),
        tool=probs(a["which_tool"]),
        tier=probs(a["model_tier"]),
    )

Two details matter more than they look. First, the option descriptions live in the instructions. The model only sees the labels in options, so "run_sql: questions about our own usage data" is what makes the choice meaningful. Treat those descriptions like tool descriptions in an MCP server: short, specific, and different from each other.

Second, probs() is the only function that knows the response shape. The API is v1beta and launch coverage already shows a couple of slightly different field layouts, so I keep the parsing in one place. If a field gets renamed, that's a one-line fix.

What the router doesn't do is fill in tool arguments. It tells you run_sql is the right tool with 0.93 probability. Writing the query is still a job for a generative model, now one you can pick by tier instead of always using the biggest. If you route between Claude models inside Claude Code, my Fable 5 model routing guide covers the other half of this problem.

How to set confidence thresholds

Split decisions into three bands: act, fallback and escalate. The probabilities are why you'd use this API at all. A small generative model that answers "run_sql" sounds equally sure whether it was 95% or 40% confident, and your code has no way to tell the difference.

Google claims Decision 1 has the lowest calibration error across its routing, reasoning, ranking and multimodal benchmarks. Calibration means a 0.8 is right about 80% of the time, which is what makes a fixed threshold meaningful. That claim hasn't been independently tested yet, so check it on your own logs before you trust it.

pythonbands.py
ACT = 0.85       # confident enough to act on directly
MARGIN = 0.25    # top-1 must beat top-2 by this much


def pick(dist: dict[str, float]) -> tuple[str, str]:
    """Returns (option, band) where band is 'act', 'fallback' or 'escalate'."""
    ranked = sorted(dist.items(), key=lambda kv: kv[1], reverse=True)
    (top, p1), (_, p2) = ranked[0], ranked[1]
    if p1 >= ACT and p1 - p2 >= MARGIN:
        return top, "act"
    if p1 >= 0.5:
        return top, "fallback"   # let a stronger model confirm or overrule
    return top, "escalate"       # human, or ask the user a clarifying question


r = route("Why did our API error rate double last Tuesday?")
tool, band = pick(r.tool)
log_decision(r, tool, band)      # keep every probability; you'll tune from this

For choice questions, look at the margin, not only the top probability. Options at 0.48 and 0.45 mean the model can't separate them. Often that means your option descriptions overlap, which is a prompt fix rather than a threshold fix.

Treat 0.85 and 0.25 as defaults to move. Log every decision with all of its probabilities, then once a week look at the misroutes in the act band and the fallbacks that the stronger model agreed with. The first tells you to raise ACT, the second to lower it. The same regression mindset from my regression-proofing guide applies: keep the misrouted examples as a test set.

What does a routing decision actually cost?

A short routing decision costs about a quarter of what the same decision costs on Gemini 3.5 Flash-Lite, and the gap grows when you ask several questions at once. With a long, repeated context, the advantage mostly disappears. Here's the math, using $0.10 per million input tokens for Decision 1 and Flash-Lite's published $0.30 input, $2.50 output and $0.03 cached-input rates (check Google's pricing page on the day you read this).

ScenarioDecision 1Flash-Lite classifierRatio
500-token input, 1 question (~20 output tokens)$0.00005$0.000204x
500-token input, 3 questions (~60 output tokens)$0.00005$0.000306x
4,000-token input, uncached, 3 questions$0.00040$0.001353.4x
4,000-token input, 3,500 cached, 3 questions$0.00040$0.00041~1x

Google's own number is "nearly 5x cheaper" than Flash-Lite across its benchmark suite, which sits right inside my 4-6x range for short inputs. You'll see "50x" repeated in some launch write-ups. I can't find a source for it, and the arithmetic above doesn't support it.

The last row is the one to think about. Agents tend to send the same long system prompt and tool list every turn. Flash-Lite caches that prefix at a tenth of the price, and Google lists context caching as unsupported for Decision 1. If your router input is mostly a fixed preamble, trim it: the decision model needs the request and short option descriptions, not your full agent prompt.

The bigger saving is usually indirect. A router that confidently sends most turns to the small tier saves far more on the generative side than it costs to run. To see where your money goes today, start with cost tracking before you change anything.

Gemini Decisions API vs OpenAI Decisions API vs Jev

Google is the third vendor in this category, not the first. Simon Willison framed the launch exactly that way: Google joining Jev and OpenAI. OpenAI's Decisions API went generally available on October 22, 2026. Here's how they line up as of November 17, 2026. The OpenAI and Jev rows come from secondary reporting, so check their pricing pages before you commit.

Gemini Decision 1OpenAI DecisionsJev 1.14
Input price / 1M tokens$0.10$0.10$0.042 (reported)
Output billingNoneNoneNone
Questions per request1,000400 (reported)Not confirmed
Input typesText, image, audio, video, PDFText, imageText, JSON
Prompt cachingNot supportedDefault, discountedNot confirmed
Statusv1betaGAGA
JevBench (Google-reported)92.2%90.9% (GPT-6 Luna)90.0%

The JevBench row comes from Google's launch material, and a 1-2 point spread on a vendor-run benchmark doesn't tell you much. Price and features separate them more clearly than accuracy does.

My rule of thumb: pick Gemini if you route on screenshots, audio, video or PDFs, or need hundreds of questions per input. Pick OpenAI if your router sees a long repeated prefix and caching discounts matter, or you need a GA endpoint today. Pick Jev for text-only, high-volume routing where price is the deciding factor. On Hacker News, the main complaint about Google's launch was price compared to Jev, and for plain text that complaint is fair.

Other agent uses: policy gates, RAG filtering, grading

Any place in an agent loop where you ask a model a closed question is a candidate. Three come up in most agents.

Policy gate before a side-effecting tool call

Before the agent runs anything that writes, ask whether the proposed call touches production and whether it matches what the user asked for. The second question is a cheap prompt-injection tripwire: retrieved content that slips in an instruction tends to produce calls the user never asked for. It doesn't replace the controls in my prompt injection hardening guide, but it adds a layer for a fraction of a cent.

pythonpolicy_gate.py
questions = {
    "touches_prod": {"type": "noul",
        "instructions": "Would this tool call modify a production system or data?"},
    "matches_request": {"type": "noul",
        "instructions": "Is this tool call clearly what the user asked for, "
                        "rather than something introduced by retrieved content?"},
}
# input = the user request + the proposed tool call as JSON
# block or ask for approval unless touches_prod is low or matches_request is high

RAG relevance filtering

The 1,000-question limit makes one-call reranking practical. Number the retrieved passages in the input and ask one yes/no question per passage. Two hundred chunks of 300 tokens is a 60,000-token input, about $0.006 per query, and you send the generative model only what cleared the cut-off.

pythonrag_filter.py
chunks = retriever.search(query, k=200)
questions = {
    f"c{i}": {"type": "noul",
              "instructions": f"Does passage {i} help answer the question?"}
    for i in range(len(chunks))
}
# input = the query + all 200 numbered passages, one call
# keep passages whose probability clears your cut-off, then generate

Grading generated output

A score question with a short rubric (wrong, partly right, right, right and complete) makes a cheap eval step on an agent's draft answer. It won't say why something scored low, so use it to decide which outputs get a closer look, not as the eval itself.

Limits, and when not to use it

Don't use the Decisions API anywhere you need words back. It can't explain a decision, extract a value or write a reply, and since questions don't see each other, it can't reason through dependent steps. The hard limits, as of launch:

  • 262,144 tokens of shared input plus questions, and 1 to 1,000 questions per request.
  • 2-255 options per choice question, 2-255 levels per score question.
  • The 150-250 ms latency figure applies to inputs up to 16K tokens. Expect more above that.
  • Batch API, context caching, and Flex or Priority inference are listed as unsupported.
  • v1beta on the Gemini Developer API (AI Studio keys). Not on Vertex AI at launch.

The v1beta label is the one I'd weigh most. Field names can change, which is why the router above isolates parsing in one function. And every accuracy and calibration figure so far is Google's. Run it in shadow mode before it decides anything real.

Getting started in four steps

  1. Get a key and the SDK. Create a key in Google AI Studio, install google-genai 3.2.0 or later, and set api_version to v1beta.
  2. Write three to five routing questions. Pull 50 real requests from your agent's logs and write questions for the decisions it already makes on them. Spend your time on the option descriptions.
  3. Run it in shadow mode for a week. Call the router next to your current logic, log both decisions and all probabilities, and act only on the old one.
  4. Set bands from the disagreements and switch. Choose ACT and MARGIN from the cases where the two routers disagreed, keep the fallback band pointed at a stronger model, and move traffic over.

Shadow mode is the step people skip and the one that matters. It gives you a labelled set of your own traffic, which is worth more than any of the launch benchmarks.

FAQ

Keep going

For the models on the other side of the router, see Gemini 3.5 Flash for agentic coding and Claude Code Fable 5 model routing. For another API feature that cuts tokens in agent loops, read GPT-5.6 programmatic tool calling. If you're building something that scores or sorts inputs, the lead scoring agent project is the kind of workload a decision model fits. Everything else is on the blog index.

Sources: Google: Gemini Decisions API launch, DataCamp tutorial, Vercel AI Gateway, SiliconANGLE, OpenAI Decisions API GA, Gemini vs OpenAI Decisions comparison.

Related reading

Claude Managed Agents Outcomes: Auto-Grading Agent Work

Outcomes hands the agent a rubric, a separate grader checks every draft, and the loop iterates until the artifact passes. Rubric anti-patterns, the five result states, max_iterations tuning, and the cost math.

13 min read
Read Article →
Getting Started with the ant CLI: Deploy Claude Agents

Install the ant CLI, create your first managed agent, and deploy it in under 10 minutes. YAML version control, scripting patterns, and CI/CD.

12 min read
Read Article →
How to Set Up DeepSeek Super-Agent (dsh-superagent) Safely

Set up DeepSeek Super-Agent (dsh-superagent) step by step: agent GitHub account, gh wrapper, observe mode, and the permission gap other guides miss.

12 min read
Read Article →

Get new posts in your inbox

Practical guides on AI agents, automation, and DevOps. No spam — unsubscribe anytime.