API de Responses: el objeto reasoning en detalle
En esta página
El objeto reasoning en la API de Responses
La API de Responses de xAI ofrece un control granular sobre el razonamiento mediante el objeto reasoning. Este parámetro solo está disponible en la API de Responses (no en Chat Completions) y te permite configurar tres aspectos del razonamiento: el esfuerzo, la generación de resúmenes y el formato del resumen.
Estructura completa del objeto reasoning
{
"model": "grok-4.20-0309-reasoning",
"input": "Your question here",
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
effort
Controla la profundidad del pensamiento del modelo. Tiene tres valores posibles:
low: pensamiento mínimo, adecuado para tareas sencillasmedium: equilibrio entre profundidad y velocidadhigh: pensamiento máximo para problemas complejos
Este parámetro es el equivalente en la API de Responses de reasoning_effort en Chat Completions, pero con un valor adicional: medium.
generate_summary
Un valor booleano que indica si el modelo debe producir un resumen de su razonamiento además de la respuesta final.
{
"model": "grok-4.20-0309-reasoning",
"input": "Compare the advantages of quicksort and mergesort.",
"reasoning": {
"effort": "high",
"generate_summary": true
}
}
Cuando generate_summary se establece en true, la respuesta contiene un elemento adicional con un resumen conciso del proceso de razonamiento. Este resumen está en texto plano (no cifrado), lo que lo distingue de reasoning.encrypted_content.
summary
Controla el formato del resumen generado. Por ahora, el único valor documentado es "auto", que deja que el modelo elija el formato más apropiado.
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
}
}
Diferencia entre resumen y razonamiento cifrado
Estos dos mecanismos son complementarios pero distintos:
| Aspecto | Resumen (generate_summary) | Cifrado (include) |
|---|---|---|
| Legibilidad | Texto plano, comprensible | Cifrado, opaco |
| Uso principal | Visualización para el usuario, auditoría | Reutilización en solicitudes posteriores |
| Activación | reasoning.generate_summary: true | include: ["reasoning.encrypted_content"] |
| Detalle | Resumen condensado | Razonamiento completo |
| Disponibilidad | Solo API de Responses | Solo API de Responses |
Puedes activar ambos simultáneamente para obtener tanto un resumen legible como el razonamiento cifrado completo:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Demonstrate the infinitude of prime numbers.",
reasoning={
"effort": "high",
"generate_summary": True,
"summary": "auto"
},
include=["reasoning.encrypted_content"]
)
Combinaciones habituales
Uso mínimo: solo esfuerzo
{
"reasoning": {
"effort": "low"
}
}
El modelo razona con el mínimo esfuerzo. No se devuelve ningún resumen ni razonamiento cifrado.
Uso intermedio: esfuerzo + resumen
{
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
El modelo razona y proporciona un resumen legible. Ideal para aplicaciones que quieren mostrar el proceso de pensamiento al usuario.
Uso completo: esfuerzo + resumen + cifrado
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
},
"include": ["reasoning.encrypted_content"]
}
Configuración máxima: razonamiento profundo, resumen legible y contenido cifrado para reutilización. Reserva esto para los casos en los que necesites todo.
Cuándo omitir el objeto reasoning
Si no necesitas controlar el razonamiento, puedes simplemente omitir el parámetro reasoning. El modelo usará su configuración predeterminada. Esto sigue siendo válido y el modelo seguirá razonando (ya que grok-4.20-0309-reasoning es un modelo de razonamiento por naturaleza).
Puntos clave
- El objeto
reasoningsolo está disponible en la API de Responses effortcontrola la profundidad (low,medium,high)generate_summaryproduce un resumen legible del razonamiento (texto plano)summary: "auto"deja que el modelo elija el formato del resumen- Puedes combinar resumen y razonamiento cifrado en la misma solicitud
- Omitir
reasoninges válido: el modelo razona con la configuración predeterminada