Razonamiento en agentes y conversaciones
En esta página
Lección reescrita el 2 de noviembre de 2026 para Mistral Small 4 y Large 4. La documentación de Mistral indica que
reasoning_effortestá disponible en los puntos de conexión de Agents y Conversations dentro del campocompletion_args. Fuentes: Reasoning · Python SDK — Conversations.
Tres formas de llamar a un modelo de razonamiento
En lecciones anteriores utilizaste la API de Chat Completions: enviabas el historial completo en cada llamada y reasoning_effort iba directamente en la solicitud. Mistral ofrece otras dos interfaces: la API de Agents, que guarda una configuración reutilizable (modelo, instrucciones, herramientas, parámetros), y la API de Conversations, que mantiene el historial en el servidor. En estas dos API, no configuras el razonamiento en el nivel superior; lo anidas dentro de completion_args junto con otros parámetros de generación.
Un agente que razona
Establecer el nivel de razonamiento en la definición del agente evita tener que repetirlo en cada llamada y garantiza que todo tu equipo utilice la misma configuración:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-small-2603",
name="Financial Analyst",
instructions=(
"You analyze financial situations for SMEs. "
"End every response with a quantified recommendation and its assumptions."
),
completion_args={"reasoning_effort": "high"},
)
reponse = client.beta.conversations.start(
agent_id=agent.id,
inputs="Our working capital requirement has doubled in a year while revenue grew by 15%. What should we look at first?",
)
Lectura de las salidas de una conversación
Una conversación no devuelve choices; devuelve una lista de entradas (outputs). La respuesta del modelo se encuentra en las entradas de tipo message.output. Al igual que con Chat Completions, el contenido es una cadena o una lista de fragmentos que pueden incluir un ThinkChunk. La función separer de la Lección 3 funciona exactamente igual:
for entry in reponse.outputs:
if entry.type == "message.output":
reflexion, texte = separer(entry.content)
print(texte)
Otras entradas describen lo ocurrido durante el turno, como la ejecución de una herramienta (tool.execution) o una llamada a función. Ignóralas si solo te interesa la respuesta final.
Una conversación sin agente
Para tareas puntuales, la API de Conversations acepta un modelo directamente, sin necesidad de configurar un agente previamente. El servidor guarda el historial y puedes continuar el intercambio con conversations.append, ajustando el nivel de razonamiento para un turno específico si es necesario:
conv = client.beta.conversations.start(
model="mistral-large-4-0",
inputs="Propose a migration plan for a 2 TB PostgreSQL database with zero downtime.",
completion_args={"reasoning_effort": "high"},
)
suite = client.beta.conversations.append(
conversation_id=conv.conversation_id,
inputs="Summarize this plan in five steps for executive leadership.",
completion_args={"reasoning_effort": "low"}, # a summary doesn't need deep reflection
)
Esta es una ventaja concreta frente a Chat Completions, donde la documentación exige reenviar el mensaje completo del asistente, incluida la reflexión, en cada nuevo turno (Lección 7). Con la API de Conversations, el servidor mantiene el historial; no tienes que reenviarlo en cada llamada.
Razonamiento y herramientas
Un agente puede combinar razonamiento y herramientas: tools y completion_args son campos independientes al crear un agente. Así, un agente de análisis puede disponer de búsqueda web y razonamiento profundo:
agent_veille = client.beta.agents.create(
model="mistral-small-2603",
name="Competitive Intelligence",
instructions="You compare competitor offers using cited public sources.",
tools=[{"type": "web_search"}],
completion_args={"reasoning_effort": "high"},
)
Vigila el coste, no obstante: la reflexión y las llamadas a herramientas se acumulan en la factura de un único turno.
Comparación de los tres enfoques
| Criterio | Chat Completions | Agents | Conversations |
|---|---|---|---|
| Dónde configurar el razonamiento | reasoning_effort en la solicitud | completion_args en el agente | completion_args en start o append |
| Historial | Reenviar en cada llamada, incluida la reflexión | Lo gestiona la conversación | Se mantiene en el servidor |
Herramientas integradas (web_search…) | No | Sí | Sí |
| Uso típico | Llamadas puntuales, control total | Configuración compartida y reutilizable | Intercambios de varios turnos |
Buenas prácticas de integración
Configura el nivel de razonamiento en el agente cuando la tarea sea uniforme, y por turno cuando varíe: un turno de análisis inicial con high, seguido de turnos de reformulación con low o none, según el modelo. Verifica que el valor sea adecuado para el modelo del agente: Small 4 acepta high y none; Large 4 acepta low, medium y high. Por último, registra el uso de tokens por turno; es la única forma de saber si el razonamiento compensa para tu caso de uso.
Puntos clave
- En las API de Agents y Conversations, pasa
reasoning_effortdentro decompletion_args - Las respuestas llegan en
outputs; el texto reside en entradas de tipomessage.output, incluida la reflexión - La API de Conversations mantiene el historial en el servidor: no hace falta reenviarlo en cada turno
- Puedes cambiar el nivel en cada turno con
conversations.append - Un agente puede combinar herramientas integradas y razonamiento, a costa de un uso acumulativo