La mayoría de las colas de soporte funcionan con juicios pequeños. ¿Es esto una solicitud de reembolso? ¿Qué equipo lo posee? ¿Qué tan malo es? Los equipos a menudo pagan a un modelo de chat para responder cada juicio en prosa, y luego pagan de nuevo para analizar la prosa de vuelta a un valor que el código pueda usar. Google entregó una herramienta más estrecha para ese trabajo el 11 de noviembre de 2026. La API Gemini Decisions, impulsada por el modelo Gemini Decision 1, no genera texto en absoluto. Puntúa las opciones que le das y devuelve números.
Este tutorial construye un verificador en lote sobre esa API. Una solicitud lleva un ticket de soporte y cuatro preguntas sobre él. Las respuestas regresan como probabilidades con puntuaciones de confianza, y un bloque corto de enrutamiento envía los casos seguros hacia adelante y retiene los casos inseguros para una persona. Los pasos siguen la documentación publicada y los ejemplos de código en la guía oficial. Aquí no se afirma una ejecución en vivo con una clave real. La sección de Verificación te dice cómo demostrar que el verificador funciona en tu propia cuenta.
Lo que vas a construir o aprender
Terminarás con un script pequeño en Python que envía un ticket a la API Decisions y obtiene cuatro juicios de vuelta en una llamada. El script pregunta si el ticket pide un reembolso, qué departamento debería manejarlo, qué tan grave es el problema y si una persona debería revisarlo antes de que alguien actúe. Luego imprime cada respuesta con su confianza y enruta el ticket por reglas que tú controlas.
También aprenderás los tres tipos de pregunta y los límites que dan forma a cualquier diseño en lote. Una pregunta de sí o no es de tipo noul en la API. Una elección de un conjunto fijo es de tipo choice. Una calificación en una escala ordenada es de tipo score. Cada pregunta se juzga por su cuenta contra la entrada compartida. Agregar una pregunta no cambia las respuestas a las demás, y la entrada compartida puede mezclar texto con imágenes, audio, video y archivos PDF.
Una entrada entra, muchos juicios salen. La máquina clasifica. Tu código decide lo que significa cada pila. Ilustración: Dirty Static
Antes de empezar
Decide qué juicios en tu cola son verdaderamente acotados. La API encaja con preguntas con un conjunto fijo de respuestas, como enrutamiento, revisiones de políticas, selección de herramientas y calificación contra una rúbrica. No puede explicar una decisión, extraer un valor de un documento ni razonar mediante una cadena de pasos. Si un ticket necesita una respuesta escrita o una cadena de pensamiento, esa parte aún pertenece a un modelo de chat o a una persona.
El precio da forma al diseño, así que anótalo antes de construir. Google cobra 0.10 dólares por millón de tokens de entrada en el nivel pago, y la salida nunca se factura porque el modelo produce cero tokens de salida. La entrada compartida se factura una vez por solicitud sin importar cuántas preguntas viajen en ella. No hay caché de contexto ni soporte de Batch API, así que una solicitud que repitas factura su entrada en su totalidad cada vez. Google informa tiempos completos de solicitud de unos 150 a 250 milisegundos, casi planos de 1 a 100 preguntas en entradas de hasta 16K tokens. Esas son cifras de Google. Mídelas en tus propios tickets antes de diseñar alrededor de ellas.
Paso 1: Obtén una clave e instala el SDK
Acción: abre Google AI Studio, crea una clave de API y guárdala en una variable de entorno con un nombre marcador en tus notas. Luego instala el SDK en versión 3.2 o posterior. Las versiones más antiguas no llevan el namespace decisions en absoluto.
export GEMINI_API_KEY="YOUR_API_KEY"
pip install -U google-genai
Resultado esperado: la variable está definida para tu sesión de shell y la instalación informa google-genai en versión 3.2 o posterior. También puedes probar preguntas sin código en el Decisions Playground en AI Studio, que exporta código ejecutable cuando estés listo.
Paso 2: Haz una pregunta de sí o no
Acción: empieza con la llamada más pequeña que da la guía. El cliente debe nombrar la versión de API v1beta, o el namespace decisions no aparece. Este ejemplo usa el texto de la taza dañada de la guía oficial.
from google import genai
client = genai.Client(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?",
},
},
)
answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")
Resultado esperado: la llamada devuelve un mapa de respuestas bajo la misma clave que enviaste, más un bloque de uso donde los tokens de salida se leen como cero. La guía muestra un valor noul de 0.99 con una confianza de 0.99 para este texto. El campo noul es la probabilidad de que la respuesta sea sí, y siempre cae entre 0.01 y 0.99. La confianza para este tipo es el mayor entre el valor y uno menos el valor, así que un valor de 0.03 lleva una confianza de 0.97 de que la respuesta es no. La misma llamada por REST va a POST https://generativelanguage.googleapis.com/v1beta/decisions con tu clave en el encabezado x-goog-api-key. Anota la ruta. Este modelo no responde en la ruta generateContent que usan otros modelos de Gemini.
Paso 3: Convierte una llamada en una revisión en lote
Acción: mantén el mismo cliente y haz crecer el mapa de preguntas. Este lote ejecuta cuatro revisiones en un ticket. Mezcla los tres tipos, y agrega una revisión de alcance que pregunta si el mensaje concierne a un pedido en absoluto. Esa revisión de alcance importa en el Paso 5.
ticket = "I was charged twice for my order and the export page crashes in Safari."
result = client.decisions.create(
model="gemini-decision-1",
input=ticket,
questions={
"about_order": {
"type": "noul",
"instructions": "Is this message about an order, a payment or a delivery?",
},
"is_refund": {
"type": "noul",
"instructions": "Does the customer ask for a refund or a charge reversal?",
},
"department": {
"type": "choice",
"instructions": "Which department should handle this request?",
"criteria": {
"billing": "Payments, invoices, and refunds.",
"technical": "Problems using the product.",
"shipping": "Delivery and tracking.",
"other": "Anything outside these categories.",
},
},
"severity": {
"type": "score",
"instructions": "How severe is this issue for the user?",
"criteria": [
"Cosmetic: appearance only, no lost functionality.",
"Workaround available: a task fails, but another way works.",
"Fully blocked: a task fails with no workaround.",
],
},
},
)
Resultado esperado: una respuesta contiene cuatro respuestas, una por clave. La respuesta choice nombra la opción superior y da una probabilidad para cada opción. La respuesta score da un promedio ponderado entre los niveles, así que puede caer entre niveles, y lleva una probabilidad para cada nivel más una leyenda que mapea números de nivel a tu texto de nivel. Tres datos de la documentación dan forma a cómo escribes estas preguntas. El modelo nunca ve tus claves de pregunta, así que la pregunta completa debe vivir en el texto de instrucciones. Las claves deben tener de 1 a 64 caracteres formados por letras, dígitos, guiones bajos y guiones. La API ordena las opciones de elección por clave antes de puntuarlas, y un empate en probabilidad exacta va a la opción cuya clave se ordena primero. Nombra tu opción de red de seguridad other, como en este ejemplo. Un nombre como none_of_the_above se ordena antes que las opciones reales y puede ganar empates que debería perder.
Paso 4: Agrega una foto o un PDF a la misma entrada
Acción: cuando una revisión necesita más que el texto del ticket, envía la entrada como una lista de bloques en lugar de una cadena. Los bloques pueden ser texto, imagen, audio, video o documento, y documento significa solo PDF. Define el tipo de medio verdadero en cada bloque, porque la API rechaza application/octet-stream. Los datos en línea están limitados a 100 MB por solicitud, y a 50 MB para archivos PDF. Los archivos en URL externas están limitados a 15 MB cada uno, y los enlaces de YouTube y las direcciones gs:// no son compatibles. Usa la Files API, una dirección HTTPS pública o firmada, o bytes en línea en cambio.
import base64
with open("photo.jpg", "rb") as f:
image_b64 = base64.b64encode(f.read()).decode("utf-8")
result = client.decisions.create(
model="gemini-decision-1",
input=[
{"type": "text", "text": "Customer photo for return 8821.\n"},
{"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
],
questions={
"visible_damage": {
"type": "noul",
"instructions": "Does the photo show physical damage to the item? Ignore the packaging.",
},
},
)
Resultado esperado: la foto se une al texto como una entrada compartida, y cada pregunta en la misma solicitud puede juzgar ambos. El ajuste resolution intercambia detalle visual por tokens, con valores low, medium, high y ultra_high, y el último de ellos sirve solo a imágenes. Un lote puede crecer hasta 1,000 preguntas por solicitud, dentro de un límite total de 262,144 tokens compartidos por la entrada y las preguntas.
Paso 5: Enruta por probabilidad y confianza
Acción: lee el valor para elegir una acción y lee la confianza para decidir si la acción puede ejecutarse por su cuenta. Los números abajo son puntos de partida de los ejemplos de la guía. Reemplázalos con cortes que te ganes en el Paso 6.
a = result.answers
dept = a["department"]
if a["about_order"].noul < 0.5:
route_to("general_intake")
elif dept.confidence >= 0.7 and dept.choice != "other":
route_to(dept.choice)
elif dept.confidence >= 0.4:
route_to_fallback_model(ticket)
else:
route_to("human_review")
Resultado esperado: los casos seguros avanzan, los casos intermedios obtienen una segunda mirada de un modelo más grande que puede razonar, y los casos débiles esperan a una persona. Dos reglas de la documentación protegen este bloque. Una pregunta choice siempre divide su probabilidad entre las opciones que le diste, incluso cuando ninguna de ellas encaja, que es por qué la revisión de alcance se ejecuta primero en este código. Un valor score es un promedio, no un nivel. Cuando necesites un nivel, toma el nivel con la probabilidad más alta y lee su texto desde la leyenda, como hace este bloque corto.
sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])
Paso 6: Prueba con tus propios tickets etiquetados
Acción: construye un conjunto pequeño de tickets pasados donde una persona ya ha registrado el departamento correcto, la gravedad correcta y la decisión de reembolso. Ejecuta el lote en cada uno y compara las respuestas superiores con las etiquetas. Cuenta con qué frecuencia cada banda de confianza resulta correcta, y luego define tus cortes de enrutamiento a partir de esos conteos. Google aconseja exactamente esto. Los umbrales deberían venir de ejemplos etiquetados de tu propio tráfico, y el mismo conjunto te dice si las probabilidades significan lo que afirman en tus datos.
Resultado esperado: tienes un corte medido para cada ruta, más una lista de tickets que el lote se equivoca que puedes estudiar. Conserva el conjunto y vuelve a ejecutarlo después de cualquier edición a instrucciones o criterios. Un bloque de seguridad también necesita cuidado en este paso. Cuando el filtro de entrada bloquea una solicitud, la API devuelve HTTP 400 con un código de error como safety o prohibited_content y ninguna respuesta en absoluto. Registra ese resultado como ninguna decisión y envía el ticket a una persona. Un ticket bloqueado a menudo es el que más necesita ojos humanos.
La pila que espera a una persona es una característica del diseño, no una falla de él. Ilustración: Dirty Static
Verificación
Ejecuta estas comprobaciones y registra los resultados. El script envía una solicitud para un solo ticket y el bloque de uso informa cero tokens de salida. El mapa de respuestas contiene cada clave que enviaste, y cada respuesta lleva una confianza entre 0 y 1. El texto de la taza del Paso 2 devuelve un valor noul alto, y un ticket sin contenido de pedido se enruta a la entrada general mediante la revisión de alcance. Tu conjunto etiquetado del Paso 6 pasa a la tasa que tus cortes suponen, y una entrada bloqueada llega a revisión humana en lugar de a una cola.
Termina con la revisión de costos. Calcula el precio de una solicitud a mano desde su conteo de tokens de entrada a 0.10 dólares por millón de tokens, y luego compara esa cifra con el costo de las mismas revisiones enviadas como llamadas de chat separadas que reenvían el ticket cada vez. La brecha entre esas dos cifras es toda la razón por la que este endpoint existe.
Solución de problemas
| Problema | Causa probable | Solución |
|---|---|---|
| El namespace decisions no aparece en el cliente | El SDK está por debajo de la versión 3.2, o el cliente carece del ajuste v1beta | Instala google-genai en 3.2 o posterior y crea el cliente con la versión de API v1beta, como en el Paso 2 |
| Una llamada REST devuelve 404 o un error de modelo | La llamada fue a la ruta generateContent o a la versión v1 | Envía la solicitud a POST /v1beta/decisions con el modelo gemini-decision-1, como en el Paso 2 |
| Una regla de umbral nunca se activa | El corte está por encima de 0.99 o por debajo de 0.01, y los valores noul nunca salen de ese rango | Mantén los cortes de sí o no dentro de 0.01 a 0.99 y defínelos desde tu conjunto etiquetado |
| La respuesta de departamento elige una opción cuando ninguna encaja | Una pregunta choice debe repartir probabilidad entre las opciones que se le dieron | Ejecuta primero una revisión de alcance de tipo noul, como en los Pasos 3 y 5, y enruta las fallas lejos antes de confiar en la elección |
| Una puntuación se imprime como fracción y se ve mal | El campo score es un promedio ponderado entre niveles, no un índice de nivel | Lee el nivel con la probabilidad más alta e imprime su texto de leyenda, como en el Paso 5 |
| Toda la solicitud devuelve HTTP 400 sin respuestas | Un filtro de seguridad bloqueó la entrada, y el código de error nombra el bloqueo | Trata el resultado como ninguna decisión y envía el elemento a revisión humana. Nunca leas un bloqueo como un no en cada pregunta |
| Los costos suben en ejecuciones repetidas de la misma entrada | La API no ofrece caché de contexto, así que cada solicitud factura la entrada compartida en su totalidad | Agrupa más preguntas en cada solicitud y recorta llamadas repetidas en entradas que no han cambiado |
Próximos pasos
Haz crecer el lote donde la forma encaje. Un contrato o una captura de pantalla puede enfrentar docenas de reglas de políticas en una solicitud. Un enrutador puede preguntar qué herramienta encaja con una tarea y qué nivel de modelo debería tomarla, el mismo patrón de flujo de control que nuestra guía de sesiones de agente aisladas protege desde el otro lado. Mantén cada pregunta nueva independiente, agrégala primero al conjunto etiquetado y deja que sus respuestas se ganen la confianza en apuestas bajas antes de que muevan dinero o cierren tickets.
El hábito que vale la pena conservar es la división que esta API fuerza. Las decisiones que terminan en un conjunto fijo de respuestas van al lote. El trabajo que necesita palabras, razones o una cadena de pasos va a otro lugar. Las colas se vuelven más rápidas cuando cada tipo de trabajo se ejecuta en la herramienta que fue construida para él.
Datos verificados contra la documentación de la API Gemini Decisions y los ejemplos de la guía el 12 de noviembre de 2026. Los precios, límites y cifras de latencia son valores publicados por Google y pueden cambiar, así que confírmalos en la documentación antes de un despliegue más amplio. Este procedimiento se verificó contra esos documentos y no se presenta como una ejecución de prueba personal.
Fuentes
- Google, documentación y guía de la API Gemini Decisions, verificadas el 12 de noviembre de 2026: https://aistudio.google.com/docs/decisions-api
- Google, anuncio de la API Gemini Decisions, 11 de noviembre de 2026, mediante Google Blog
- Apidog, How to Use the Gemini Decisions API, noviembre de 2026: https://apidog.com/blog/how-to-use-gemini-decisions-api/
- TeamoRouter, Gemini Decision API: Price, the Three Question Types and How to Call It, 12 de noviembre de 2026: https://teamorouter.com/blogs/gemini-decision-api
- ImportStatic, Gemini Decisions API in Go: a REST client and its traps, 12 de noviembre de 2026: https://importstatic.com/ai/gemini-decisions-api-go
- Imágenes del héroe, clasificador y revisión: ilustraciones de Dirty Static
FIN DE LA TRANSMISIÓN
Mantén la curiosidad. Cuestiónalo todo.
