Temperatura y sampling en agentes: el knob no es creatividad

Un agente no “se vuelve más creativo” porque subas temperature. Ese número solo cambia cómo se elige el siguiente token después de que el modelo ya calculó una distribución. Si el agente llama tools, emite JSON o actúa en nombre de un usuario, el sampling es un contrato de runtime: se pinnea, se loguea y se evalúa. No se mueve “a ojo” entre turnos.

Esto no es structured outputs: el schema obliga la forma; la temperatura no. Tampoco es reasoning.effort: el esfuerzo decide cuánto piensa un modelo de razonamiento, no la aleatoriedad del sampler. Y no es fallback de modelos: un 503 no se arregla subiendo el dial.

Contrato: un valor pinneado por superficie. Temperatura o top_p, no ambos. Cero no es determinista. En Claude post–Opus 4.6 el knob ya no existe.

Qué mueve cada knob

Knob	Qué recorta	Rango típico	Cuándo tocarlo
temperature	Qué tan plana o picuda queda la distribución antes de muestrear	OpenAI 0–2; Anthropic 0–1 (legado)	Default operativo. Bájalo en tools/JSON; no lo uses de “creatividad”
top_p (nucleus)	Solo los tokens cuya masa acumulada llega a p	0–1	Alternativa a temperatura. OpenAI: altera esto o temperatura, no ambos
top_k	Solo los k tokens más probables	entero ≥ 0	Gemini/Vertex y Claude legado. No es el dial principal en Responses
reasoning.effort	Cuánto “piensa” un reasoning model	none…max (según modelo)	Calidad vs latencia/costo. Distinto del sampler

Create a model response (docs 2026-09-06): temperatura 0–2; 0.8 más random, 0.2 más enfocado. We generally recommend altering this or top_p but not both. top_p 0.1 = solo el 10 % de masa. En los ejemplos del endpoint, ambos salen en 1.0.

Anthropic Messages (docs 2026-09-06): default 1.0, rango 0.0–1.0. Even with temperature of 0.0, the results will not be fully deterministic. Post–Opus 4.6: deprecated — solo 1.0 por compatibilidad; otro valor → 400. top_k se rechaza; top_p solo >= 0.99.

Google Cloud — Content generation parameters (docs 2026-09-06): topP/topK recortan candidatos; después muestrea temperatura. Cero ≈ argmax with a small amount of variation. Arranque 1.0. Generación infinita: subir al menos a 0.1.

Valores que un agente puede defender

No hay un número mágico. Hay superficies con evals distintos. Fija uno por superficie y no lo mezcles con el del chat de marketing.

Superficie	OpenAI / Gemini	Claude post–Opus 4.6	Por qué
Tool calling + JSON / schema	temperature 0–0.2; top_p default (no toques ambos)	omite el campo o manda 1.0	Menos cola larga; el schema ya cierra la forma
Clasificar / extraer / rúbrica	0–0.2	1.0 o ausente	Quieres repetibilidad para evals
Redacción con voice	0.4–0.8	1.0	Aquí sí hay margen; el agente no debe “inventar tools”
Reasoning model (GPT-5.5/5.6, GPT-6 Astra)	deja sampling en default; mueve reasoning.effort	n/a	Reasoning: gpt-5.5 default medium; none en GPT-6 Astra → HTTP 400

Regla práctica: si el output alimenta otra máquina (tool, webhook, JSON, SQL), temperatura baja y pinneada. Si alimenta a un humano, puedes subir un poco — nunca en la misma llamada que el function calling.

Lo que el dial no arregla

1. JSON roto. Si el modelo se sale del schema, no bajes temperatura “a ver”. Usa structured outputs (json_schema + strict, response_format, output_config.format). El sampler no es un validador.

2. 429 / 5xx / 529. Eso es reintentos y fallback de modelo. Cambiar sampling en un retry mezcla dos experimentos: no sabes si mejoró el modelo o el azar.

3. Costo de thinking. En Responses, reasoning.effort (none / low / medium / high / xhigh / max) guía how much to think. Bajar temperatura no recorta tokens de razonamiento. Subir effort a xhigh o max sin eval que lo justifique quema latencia.

4. Cache del prefijo. Prompt caching vive del prefijo estático (system, tools, docs). Meter la temperatura en el texto del prompt —“sé más creativo”— ensucia el cache y no sustituye el campo del API.

5. Tests de tools. Los handlers se testean sin LLM (tests de tools). Si tu suite “flaky” es el modelo, no el handler, el bug es el sampling o la falta de schema — no Vitest.

Cómo pinnearlo en el runtime

Un agente en producción trata el sampling como config versionada, no como sugerencia del system prompt.

1. Un valor por surface. Ejemplo: agent.tools, agent.classify, agent.draft. Tres techos, tres evals. No un global “0.7 porque ChatGPT”.
2. El campo va en el request, no en el texto. temperature: 0.2 en Responses / generateContent; no “responde de forma determinista” en el system.
3. Loguea el valor efectivo. Igual que effective_model en el fallback: temperature, top_p, reasoning.effort, model. Si Claude post–4.6 rechaza el campo, el log debe decir omitted, no 0.
4. Congela el valor en el dataset de eval. Un juez o un golden case con otra temperatura es otro experimento. El llm-as-judge también corre con sampling pinneado.
5. Nunca ambos knobs. OpenAI lo dice dos veces en el mismo endpoint. Si heredas un wrapper que manda temperature: 0.2 y top_p: 0.9, estás recortando dos veces y no puedes atribuir regresiones.

const SAMPLING = {
  tools: { temperature: 0.2 },
  classify: { temperature: 0 },
  draft: { temperature: 0.6 },
} as const;

await client.responses.create({
  model: process.env.AGENT_MODEL,
  temperature: SAMPLING.tools.temperature,
  // no top_p aquí
  input,
  tools,
});

En Gemini/Vertex el orden es el de la doc: candidatos con topP/topK, luego temperatura. No copies el 0.2 de OpenAI y un topP: 0.95 “por si acaso”: es el mismo anti-patrón de tocar ambos.

En Claude nuevo: omite temperature / top_p / top_k. Si un SDK mete 0 por default, el 400 no es rate limit — es el modelo diciendo que el knob murió.

Checklist antes de tocar el dial

1. ¿Esta llamada emite JSON, SQL o un tool call? Entonces temperatura baja o el default del proveedor, nunca 0.8.
2. ¿El wrapper manda temperature y top_p a la vez? Quita uno. OpenAI lo pide explícito.
3. ¿El modelo es Claude posterior a Opus 4.6? No envíes el campo. Un 400 aquí no se reintenta con otro valor.
4. ¿Querías “que piense más”? Eso es reasoning.effort, no temperatura.
5. ¿El golden set se rompió al cambiar el dial? Restaura el valor, no parches el dataset.
6. ¿Hay effective_temperature en el log/traza? Si no, no puedes debuggear un flake.
7. ¿El system prompt pide “sé determinista”? Bórralo. El campo del API es la fuente; un loop se corta con max turns, no con el sampler.

FAQ

¿Temperature 0 deja el agente determinista? No. OpenAI describe 0.2 como more focused, no como hash. Anthropic: even with 0.0, the results will not be fully deterministic. Google: mostly deterministic, but a small amount of variation is still possible. Si necesitas un bit idéntico, no uses un LLM para esa rama.

¿Puedo poner temperatura 2 para brainstorm y 0 para tools en la misma sesión? Sí, en llamadas distintas con surface distinta. No en el mismo responses.create que ya va con tools. Mezclar en un solo request es cómo un agente “inventa” un argumento de tool.

¿top_p 0.1 es lo mismo que temperatura 0.1? No. top_p recorta masa de probabilidad; temperatura reescala logits. OpenAI recomienda uno. Tratarlos como sinónimos es el bug más común en wrappers.

¿Y seed? Responses (create, 2026-09-06) documenta temperature y top_p; no hay seed en ese contrato. No lo prometas en el runbook.

¿Construir o AgentOps? El cliente se arma una vez; el valor se opera (log, eval, techo). Hub: seguridad, coste y operación. Para el agente desde cero: construir agentes y el curso.

Fuentes verificadas (2026-09-06)

• OpenAI — Create a model response: temperatura 0–2, top_p nucleus, no ambos.
• OpenAI — Reasoning: reasoning.effort independiente del sampler; defaults por modelo.
• Anthropic — Messages: 0–1, no determinista en 0; deprecado post–Opus 4.6.
• Google Cloud — generation parameters: topP/topK primero, temperatura después; 0 ≈ argmax con residuo.