Ejecución en servidor frente a cliente
En esta página
Lección actualizada el 3 de noviembre de 2026 según el SDK
mistralai3.7.0 y la documentación de Handoffs de Mistral: una entradaagent.handoffidentifica al agente de destino mediantenext_agent_id(noto_agent), yconversations.appendno acepta un parámetroagent_id; el código antiguo fallaría. La reanudación del agente de destino aquí se produce mediante una nueva conversación, a la que se le pasa el contexto. Fuentes: Handoffs · client-python.
Dos formas de gestionar las transferencias
Cuando un agente transfiere el control a otro, la API de Mistral ofrece dos modos de ejecución: servidor (automático) y cliente (manual). La configuración es una sola palabra, pero determina quién dirige realmente el flujo de trabajo. En modo servidor, delegas toda la coreografía en Mistral y recibes el resultado. En modo cliente, recuperas el control entre cada paso. Todo lo demás —los agentes, sus herramientas, sus objetivos de transferencia— permanece exactamente igual.
Modo servidor, el predeterminado
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Predeterminado — puede omitirse
)
El flujo está totalmente gestionado: el enrutador recibe la solicitud, decide transferirla al agente de investigación y Mistral ejecuta la transferencia; el agente de investigación realiza su trabajo y luego transfiere al calculador, y Mistral ejecuta eso también; el calculador produce el resultado. Recibes la respuesta final, acompañada de todas las salidas intermedias, de modo que ves lo que ha ocurrido, pero a posteriori.
Este modo tiene tres cualidades que explican por qué es el predeterminado. Es sencillo, ya que no escribes lógica de control por tu parte. Es rápido, porque toda la cadena se ejecuta en Mistral sin idas y vueltas de red en cada relevo. Es fiable, pues la gestión de errores y los tiempos de espera entre agentes se encargan por ti.
Sus limitaciones son exactamente la contrapartida. No tienes control intermedio: es imposible validar o modificar una transferencia mientras ocurre. El coste es opaco, en el sentido de que todos los agentes de la cadena se ejecutan sin que puedas interrumpir a mitad de flujo una solicitud que se dirige en una dirección innecesaria. Y no puedes insertar ninguna lógica personalizada entre pasos: ni registro detallado, ni validación, ni decisiones de negocio.
Modo cliente, cuando quieres control
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
El enrutador recibe la solicitud y decide transferirla, exactamente como antes. Pero en lugar de ejecutarse la transferencia, recibes un evento agent.handoff y la cadena se detiene ahí. Depende de ti reiniciarla llamando al agente de destino, lo que te deja la libertad de validar, registrar, enriquecer el contexto o simplemente rechazarla.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Search for the latest tech news.",
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target_agent_id = entry.next_agent_id
print(f"Handoff requested to: {target_agent_id}")
# Validar y luego pasar al agente de destino, con contexto útil
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Procesar la respuesta del agente de destino
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Un punto merece atención: la documentación de Mistral describe el modo client —el control vuelve a ti en el momento de la transferencia—, pero no proporciona ningún método para que el agente de destino reanude la misma conversación, y conversations.append no acepta un parámetro agent_id. Por ello, el ejemplo inicia una conversación con el agente de destino, al que transmites explícitamente lo que necesita: la solicitud original y, si procede, un resumen de lo que ya se ha hecho. Esta es también una oportunidad para transmitir solo lo que deben ver.
El fragmento anterior gestiona solo un relevo. Una cadena real enlaza varios, lo que requiere un bucle.
def execute_with_control(router_id, query):
"""Ejecuta un flujo de trabajo multiagente con control en cada paso."""
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
conversation_id = response.conversation_id
results = []
while True:
handoff_found = False
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_found = True
target = entry.next_agent_id
print(f"[LOG] Transferencia a {target}")
# Aquí puedes añadir: validación, registro, métricas
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # la solicitud original, enriquecida si es necesario
handoff_execution="client",
)
conversation_id = response.conversation_id
break
elif entry.type == "message.output":
results.append(entry.content)
if not handoff_found:
break
return results
La estructura es la de una bomba: mientras aparezca una transferencia en las salidas, la procesas y reinicias; tan pronto como una iteración del bucle no encuentra ninguna, la cadena ha terminado y sales con los mensajes acumulados. El comentario en medio marca la ubicación que justifica todo este modo: es ahí, y solo ahí, donde tu código se interpone entre dos agentes.
Elegir entre los dos
El modo servidor cubre la producción estándar. Si tu flujo de trabajo es predecible, si confías en los agentes que has escrito o si estás creando un prototipo y quieres ver resultados rápidamente, la automatización total es la opción correcta, y escribir un bucle de control sería un esfuerzo inútil.
El modo cliente se justifica tan pronto como entra en juego un requisito externo. Validación humana, cuando un operador debe aprobar una transferencia a un agente que desencadena acciones sensibles. Necesidad de registro y auditoría, cuando el cumplimiento exige rastrear cada paso con tus propios identificadores y tus propias marcas de tiempo. Enrutamiento condicional, cuando la decisión depende de reglas de negocio que el modelo no puede conocer: estado del cliente, hora del día, una cuota. Un límite o limitación de tasa, cuando quieres acotar el número de agentes ejecutados para una solicitud. Una estrategia de reserva, finalmente, cuando el fallo de un agente debe desencadenar algo distinto a un error mostrado al usuario.
Así es como se ve la primera de estas situaciones, reducida a su esqueleto.
def workflow_with_validation(router_id, query):
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = entry.next_agent_id
approval = input(f"¿Autorizar transferencia a {target}? (y/n) ")
if approval.lower() == "y":
response = client.beta.conversations.start(
agent_id=target,
inputs=query,
)
else:
print("Transferencia rechazada.")
break
El input de la consola sirve como demostración; en una aplicación, será reemplazado por una notificación a un operador y por la reanudación del flujo de trabajo cuando llegue la respuesta. El principio sigue siendo el mismo: la transferencia solo ocurre si tu código la desencadena.
El enfoque correcto es empezar en modo servidor y cambiar solo el día que una restricción específica lo requiera. Cambiar al modo cliente «por si acaso» te hace pagar inmediatamente la complejidad de un bucle y las idas y vueltas de red, por un control que aún no estás utilizando.
Puntos clave
- Modo servidor = totalmente automático, sencillo y rápido, sin control intermedio
- Modo cliente = recibes eventos de transferencia y decides qué hacer
- El modo cliente permite validación, registro, enrutamiento condicional y gestión de errores
- Para la mayoría de los casos, el modo servidor es suficiente; cambia al modo cliente cuando necesites control
- Ambos modos admiten las mismas cadenas de agentes; solo difiere el control