Arquitectura de la API de Agentes de Mistral
En esta página
Actualizado el 3 de noviembre de 2026. El ejemplo anterior de agente completo pasaba
guardrails={"enabled": True}, un formato que no existe: el parámetro oficial es una lista de configuracionesmoderation_llm_v2. La entradatool.executionexpone el nombre de la herramienta enentry.name, no enentry.tool_name, lo que anteriormente provocaba unAttributeError. Fuentes: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Los tres objetos fundamentales
La API de Agentes de Mistral se basa en tres objetos que interactúan entre sí: Agent, Conversation y Entry. La mayoría de los errores de diseño que surgen al inicio de un proyecto —volver a crear un agente para cada solicitud, reutilizar un conversation_id caducado o un análisis de respuesta que falla ante una entrada inesperada— provienen de la confusión entre estos tres niveles. Comprender sus funciones y relaciones es un requisito previo para escribir siquiera una línea de código.
El objeto Agent
Un Agent es un conjunto de configuración que define el comportamiento del modelo. No contiene datos de conversación: es una plantilla reutilizable que creas una vez y a la que pueden hacer referencia miles de conversaciones.
La creación requiere, como mínimo, un modelo, un nombre y una descripción.
agent = client.beta.agents.create(
model="mistral-large-latest", # Modelo LLM que se va a utilizar
name="My Agent", # Identificador legible por humanos
description="Agent for financial analysis" # Descripción orientada a la tarea
)
El parámetro model designa el modelo que impulsará al agente, elegido entre los modelos de finalización de chat disponibles, como mistral-medium-latest o mistral-large-latest. El name es un identificador legible por humanos que utilizas para encontrar y referenciar al agente: en un proyecto con veinte de ellos, esto es lo que te evita tener que revisar los registros para averiguar cuál está respondiendo a los clientes. La description, por su parte, está orientada a la tarea y sirve para algo más que la documentación interna; ayuda al modelo a comprender el rol que se espera de él, lo que explica la formulación «agente para análisis financiero» en lugar de un vago «agente número 3».
El resto se configura de forma opcional, y aquí es donde cobra forma la verdadera personalidad del agente.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions: el prompt del sistema del agente (define su personalidad, reglas y estilo).tools: lista de herramientas disponibles:web_search,web_search_premium,code_interpreter,image_generation,document_libraryo funciones personalizadas.completion_args: parámetros del muestreador (temperature, top_p, max_tokens, etc.).guardrails: una lista de configuraciones de moderación (moderation_llm_v2) aplicadas al mensaje entrante de cada una de las conversaciones del agente; aquí, el jailbreaking se bloquea por encima de 0,2 y la categoríafinancialse desactiva (umbral1), ya que el agente está diseñado para hablar de finanzas. Los detalles se encuentran en el curso Moderación y seguridad de la IA con Mistral.
En el ejemplo anterior, el agente financiero hereda un requisito de fuentes de sus instrucciones, la capacidad de verificar una cifra gracias a sus herramientas y una temperatura baja que limita la creatividad donde se espera rigor.
El objeto Conversation
Una Conversation es el historial de interacciones entre un usuario y un agente, o entre un usuario y un modelo por sí solo. Contiene mensajes, resultados de ejecución de herramientas y eventos de traspaso (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Recuperar el ID de la conversación para continuar más tarde
conversation_id = response.conversation_id
El comportamiento de este objeto encierra algunas sorpresas. La conversación es persistente: el historial se almacena en el lado de Mistral, a menos que pases store=False. Es independiente del agente, lo que significa que una conversación puede existir perfectamente sin un agente, en modo de modelo directo. Por último, es inmutable: cada adición devuelve un nuevo conversation_id, mientras que el anterior permanece accesible. Este último punto es el más sorprendente: si almacenas el ID inicial en tu base de datos y lo reutilizas en el tercer turno, volverás al contexto del primer intercambio.
El objeto Entry
Un Entry es una acción individual dentro de una conversación: la unidad atómica del historial. Cuando recibes una respuesta, el campo outputs contiene una lista de entradas cuyo tipo depende de lo que haya hecho el agente. Una entrada message.output lleva una respuesta de texto del agente, es decir, el texto que mostrará tu interfaz. Una entrada tool.execution lleva el resultado de la ejecución de una herramienta, como código o una búsqueda web: el script lanzado y su salida, o las páginas devueltas por el motor. Una entrada agent.handoff señala un evento de traspaso a otro agente y, por tanto, solo aparece en escenarios multiagente.
Una sola respuesta suele mezclar estos tipos. Si pides a un agente con herramientas que realice un cálculo, recibirás la ejecución y luego el comentario que la acompaña: tu código debe, por tanto, iterar sobre esta lista en lugar de leer un único campo.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Relaciones entre objetos
El siguiente diagrama resume la articulación de los tres niveles: una configuración reutilizable, un hilo de historial y acciones unitarias.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Opciones de Conversation
Iniciar una conversación acepta configuraciones que afectan tanto a tu cumplimiento normativo como a tu arquitectura, y es mejor decidirlo tú que sufrirlo. En primer lugar, el almacenamiento: store=False impide cualquier guardado en el lado de Mistral, algo que utilizarás para procesar datos que tu política interna prohíbe dejar en un servidor de terceros.
# Desactivar el almacenamiento en la nube
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
La segunda configuración define quién ejecuta los traspasos (handoffs). En modo server, el valor por defecto, Mistral encadena las transferencias de agentes sin tu intervención; en modo client, recibes los eventos de traspaso y mantienes el control para registrarlos, filtrarlos o rechazarlos.
# Modo server (por defecto) — Mistral gestiona los traspasos automáticamente
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Modo client — Recibes los eventos de traspaso y decides qué hacer
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Puntos clave
- Agent = configuración reutilizable (modelo, instrucciones, herramientas, guardrails).
- Conversation = historial persistente almacenado en el servidor, independiente del agente.
- Entry = acción unitaria (mensaje, ejecución de herramienta, traspaso).
- Las conversaciones pueden existir sin un agente (modo de modelo directo).
- Cada adición a una conversación crea un nuevo
conversation_id. - El modo
store=Falseimpide el almacenamiento en el lado de Mistral.