Como rotear tarefas de agentes de IA com a Gemini Decisions API

TL;DR

Para rotear tarefas de agentes de IA com a Gemini Decisions API, envie o título e a descrição da tarefa para o gemini-decision-1 com três perguntas: uma do tipo choice para definir qual Agent assumirá o trabalho, um score para avaliar o nível de dificuldade e um noul para verificar se uma pessoa precisa decidir primeiro. Faça a atribuição automática quando a confiança superar o seu limite. Encaminhe todo o restante para revisão humana.

Introdução

Toda equipe que gerencia múltiplos agentes de código se depara com a mesma rotina: alguém precisa ler cada nova tarefa e decidir quem cuidará dela. O Agent de backend ou o de frontend? O modelo econômico ou o mais avançado? A tarefa já pode começar ou ainda falta uma decisão?

O Google lançou uma ferramenta sob medida para essa demanda em 11 de novembro de 2026. A Gemini Decisions API responde a perguntas fechadas com probabilidades calibradas em vez de texto gerado. O Google já a utiliza internamente no Gemini Notebook para direcionar cada consulta ao nível de modelo e profundidade de raciocínio adequados, afirmando que isso reduziu a latência em consultas rotineiras em até 40%.

Neste artigo, vamos construir esse mesmo roteador para um quadro de agentes: uma chamada por tarefa, três perguntas, um limite de confiança e uma transferência fluida para um humano quando o roteador estiver em dúvida. Se você procura um quadro para testá-lo na prática, o Sharkly oferece início gratuito. Para entender a política de roteamento em si (quais tarefas justificam o uso do modelo mais avançado), leia antes o artigo sobre como rotear tarefas de agentes por dificuldade. Este post é focado na chamada de API que coloca essa política em prática.

O que a Gemini Decisions API faz

A Gemini Decisions API é um endpoint que avalia perguntas tipadas com base em uma entrada compartilhada e retorna uma probabilidade e uma pontuação de confiança para cada uma. Ela não gera texto, portanto os tokens de saída são sempre zero. Seu código toma decisões diretamente a partir dos números, sem etapas intermediárias de parsing.

Três tipos de perguntas cobrem todo o roteamento:

Uma única requisição suporta até 1.000 perguntas sobre a mesma entrada. Segundo a documentação da Decisions API, as perguntas rodam em uma única passagem (forward pass) e não têm visibilidade umas das outras; portanto, incluir uma nova pergunta não altera as outras respostas. O Google estima a latência de ponta a ponta entre 150 e 250 ms, praticamente estável de 1 a 100 perguntas.

Se você acompanhou nosso artigo sobre o Jev e modelos de decisão acima de agentes de código, o fluxo parecerá familiar. A diferença aqui é prática: um modelo hospedado pelo Google, três perguntas bem definidas e a integração direta com um quadro de tarefas.

A chamada de roteamento: três perguntas por tarefa

Aqui está o roteador. Ele requer a versão 3.2 ou posterior do google-genai e uma GEMINI_API_KEY obtida no Google AI Studio.

import json
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

AGENTS = {
    "backend": "Server code, APIs, database migrations, and backend tests.",
    "frontend": "UI components, styling, client state, and frontend tests.",
    "docs": "README files, docs pages, and changelogs. No code changes.",
    "other": "Work that fits none of the options above.",
}

DIFFICULTY = [
    "Trivial: one file, obvious change, no design decision.",
    "Routine: a few files, follows a pattern already in the repo.",
    "Involved: several modules or a new pattern, needs new tests.",
    "Hard: cross-cutting, touches auth or data migrations, or the spec is thin.",
]

def ask(task):
    state = json.dumps({
        "title": task["title"],
        "description": task["description"][:8000],
    })
    result = client.decisions.create(
        model="gemini-decision-1",
        input=state,
        questions={
            "agent": {
                "type": "choice",
                "instructions": "Which agent should take the task in `title` and `description`?",
                "criteria": AGENTS,
            },
            "difficulty": {
                "type": "score",
                "instructions": "How hard is this task for a coding agent working alone?",
                "criteria": DIFFICULTY,
            },
            "needs_human": {
                "type": "noul",
                "instructions": "Does a person need to make a decision before any agent starts?",
                "criteria": {
                    "true_description": "The spec is ambiguous, contradicts itself, or asks for a product, security, or pricing call.",
                    "false_description": "The spec is clear enough to implement as written.",
                },
            },
        },
    )
    return result.answers

Quatro detalhes nesse código vêm direto da documentação oficial e passam facilmente despercebidos.

O modelo nunca enxerga suas chaves. Ele lê apenas instructions e criteria; por isso, formule a pergunta por extenso em instructions e descreva cada uma das opções.

As chaves das opções são ordenadas alfabeticamente. A API organiza as chaves de escolha pela ordem de bytes UTF-8 antes da avaliação. É exatamente por isso que a opção padrão de escape é other e não none_of_the_above, que ficaria antes das opções reais na lista ordenada.

Os níveis de score devem ser lineares. O valor retornado em score é uma média ponderada pelas probabilidades dos índices de cada nível — neste caso, de 0 a 3. Garanta que níveis adjacentes sejam claramente distintos entre si.

Envie apenas o que as perguntas exigem. A documentação alerta que detalhes irrelevantes prejudicam a precisão. O título e a descrição quase sempre trazem um resultado melhor do que enviar toda a discussão dos comentários.

Defina o limite de confiança com base nas suas próprias tarefas

O valor da resposta define a ação a tomar. A confiança indica se você pode executá-la de forma autônoma. Em uma resposta choice, a confiança equivale à probabilidade da opção vencedora. Para um noul, é dada por max(noul, 1 - noul).

Aqui está a camada de decisão:

AUTO = 0.75      # assign without a person above this
HARD = 2.4       # difficulty score that earns the strong-model Agent

def decide(a):
    if a["needs_human"].noul >= 0.5:
        return ("human", "needs a decision first")
    if a["agent"].choice == "other" or a["agent"].confidence < AUTO:
        return ("human", f"router unsure ({a['agent'].confidence:.2f})")
    tier = "strong" if a["difficulty"].score >= HARD else "default"
    return (f"{a['agent'].choice}-{tier}", "auto")

Evite adotar o valor 0.75 sem critério. A recomendação do Google é calibrar os limites usando exemplos rotulados do seu próprio fluxo de trabalho. Selecione suas últimas 50 a 100 tarefas concluídas, veja qual Agent finalizou cada uma e passe todas por ask(). Defina o menor limite no qual as tarefas roteadas automaticamente correspondam ao que seu time fez na prática. Um roteamento automático incorreto gera uma execução com falha e exige reatribuição; uma retenção desnecessária para revisão humana custa apenas alguns minutos. Pese esses dois fatores entre si, sem recorrer a números redondos arbitrários.

Atenção a duas armadilhas: a probabilidade de um noul nunca ultrapassa 0.99, o que significa que uma verificação como > 0.99 jamais será atendida. Além disso, um score de 1.5 pode indicar tanto "dúvida dividida entre os níveis 1 e 2" quanto "incerteza distribuída entre os quatro". Sempre que essa distinção for crítica, inspecione também o campo probabilities.

Conectando o roteador a um quadro do Sharkly

Como o roteador é feito em Python padrão, ele pode rodar em qualquer ambiente. Em um quadro do Sharkly, o momento ideal de disparo é quando uma tarefa fica pronta para execução.

1. Crie um Agent para cada fluxo e nível. Por exemplo, backend-default, backend-strong e frontend-default. Conforme a documentação do Sharkly Agents, cada Agent utiliza o modelo padrão de seu Runtime, e o campo Model permite selecionar outro modelo do catálogo desse Runtime. É nesse ponto que a dificuldade se traduz na escolha do modelo adequado.

2. Aplique a decisão usando a CLI do sharkly.

import subprocess

def apply(task_id, target, reason, a):
    note = (f"Router: agent={a['agent'].choice} ({a['agent'].confidence:.2f}), "
            f"difficulty={a['difficulty'].score:.1f}, "
            f"needs_human={a['needs_human'].noul:.2f}")
    if target == "human":
        subprocess.run(["sharkly", "task", "comment", task_id,
                        "--body", f"{note}. Held for a person: {reason}."], check=True)
        return
    subprocess.run(["sharkly", "task", "edit", task_id,
                    "--delegate-agent", target], check=True)
    subprocess.run(["sharkly", "task", "comment", task_id, "--body", note], check=True)

Atribuir um Agent inicia sua execução assim que a tarefa entra em status de pronta. Registrar as probabilidades em um comentário é muito mais valioso do que parece: é assim que você auditará as decisões do roteador no futuro.

3. Configure o disparo por mudança de status. Uma Automation no Sharkly reúne instruções, o Agent responsável e os gatilhos. Configure um Router Agent básico com a instrução “run route.py on the task that triggered you” e crie um gatilho para o status que sua equipe usa para indicar tarefas "prontas". As execuções iniciadas por esse tipo de gatilho mantêm vínculo direto com a tarefa, preservando o histórico de roteamento junto ao trabalho. Pela CLI:

sharkly automation trigger create <automation-id> --kind task_event --to-status "Ready"

Quanto custa uma chamada de roteamento

O Gemini Decision 1 cobra US$ 0,10 por 1 milhão de tokens de entrada e US$ 0 por tokens de saída, conforme o anúncio oficial do Google. A entrada compartilhada é faturada uma única vez por chamada, não importa quantas perguntas você faça.

O custo do roteamento é inferior ao de uma única execução de agente em uma tarefa. O Google também disponibiliza um plano gratuito no AI Studio para fase de testes e prototipagem.

Limitações importantes antes de adotar a ferramenta

A API foi lançada na versão v1beta na Gemini Developer API, com suporte no Google Cloud sinalizado como "em breve". A documentação esclarece que ainda não há suporte para cache de contexto, Batch API ou inferência Flex e Priority; portanto, dados repetidos de entrada são cobrados integralmente em todas as chamadas. Os limites de requisição por plano estão descritos na página de rate limits do Google; confira suas cotas antes de centralizar todas as tarefas em uma única chave.

Considere as descrições das tarefas como entradas não confiáveis (untrusted input). A documentação alerta que textos fornecidos pelo usuário podem conter argumentos para induzir sua própria classificação. Caso pessoas de fora do time possam abrir tarefas, mantenha a exigência de aprovação humana para qualquer demanda envolvendo autenticação, pagamentos ou dados em produção, independentemente da resposta do roteador.

Os números de benchmark divulgados pelo Google (menor erro de calibração de todo o catálogo e custo quase 5 vezes menor que o Gemini 3.5 Flash-Lite via Interactions API) são dados do próprio Google. As tarefas rotuladas da sua equipe continuam sendo o parâmetro definitivo que realmente importa.

Quando uma chamada de roteamento não é a ferramenta certa

Utilize a Decisions API quando o volume de tarefas for maior do que uma pessoa consegue triar manualmente e as opções forem fixas: um grupo predefinido de Agents, níveis claros de modelo ou um filtro de sim/não. Prefira regras condicionais simples quando uma etiqueta já trouxer essa resposta. Se toda tarefa com a tag docs é destinada ao Agent de documentação, um if no código custa menos e não comete erros.

Recorra a um modelo generativo tradicional quando você precisar que o roteador explique a lógica da escolha em texto, reescreva o escopo da tarefa ou divida a demanda em subtarefas. A Decisions API retorna exclusivamente números, não texto. Para dividir o trabalho entre diferentes papéis, uma Crew com um líder encarregado de detalhar as metas funciona melhor; confira mais em roteamento de modelos para Crews de agentes.

Conclusão

O roteamento é uma tomada de decisão sobre um conjunto fechado de opções, e a Gemini Decisions API foi concebida justamente para isso: uma única chamada, respostas tipadas, uma métrica de confiança para aplicar limites e um custo na escala de frações de centavo. A parte estratégica continua com você: descrever as opções com clareza, calibrar os limites com base no histórico das suas tarefas e direcionar casos de baixa certeza para revisão humana.

Comece com um escopo pequeno. Roteie novas tarefas de backend durante uma semana, compare as escolhas do roteador com as decisões que sua equipe tomaria e então amplie o uso. Para rodar o roteador em um quadro de verdade com Agents, Automations e revisão humana integrados, comece a usar o Sharkly.

FAQ

O que é a Gemini Decisions API?

É um endpoint da Gemini API, lançado em 11 de novembro de 2026, projetado para responder a perguntas de sim/não, múltipla escolha e pontuação sobre texto, imagens, áudio, vídeo ou arquivos PDF. Ela utiliza o modelo gemini-decision-1 e retorna probabilidades calibradas e índices de confiança em vez de texto gerado.

Quanto custa o Gemini Decision 1?

O Google estabelece US$ 0,10 por 1 milhão de tokens de entrada e US$ 0 para saída, sendo a entrada compartilhada cobrada apenas uma vez por requisição. Há também uma camada sem custo no Google AI Studio voltada para prototipagem.

Quantas perguntas podem ser feitas em uma mesma requisição?

De 1 a 1.000 perguntas, limitadas por uma janela de contexto total de 262.144 tokens para a entrada somada a todas as perguntas. Perguntas do tipo choice suportam entre 2 e 255 opções.

Qual limite de confiança devo adotar para o roteamento?

Não há um número padrão universal. A recomendação do Google é definir esse valor com base em amostras reais e rotuladas da sua equipe. Teste retrospectivamente de 50 a 100 tarefas concluídas e selecione o limite em que as atribuições automáticas correspondam com segurança ao histórico humano.

A Decisions API pode escolher qual modelo um agente deve usar?

Indiretamente. Você pode fazer uma pergunta de score para avaliar a dificuldade e associar notas mais altas a um Agent configurado com um modelo mais potente. No Sharkly, cada Agent pode ter seu modelo definido a partir do catálogo do seu Runtime.

A Gemini Decisions API já está disponível no Vertex AI?

Ainda não. O post de lançamento do Google informa que a integração do Gemini no Google Cloud chegará em breve. No momento, o recurso está acessível pela Gemini Developer API na versão v1beta.