Mejores prácticas y siguientes pasos
En esta página
Lo que has aprendido
Has recorrido toda la API de Mistral Agents. Hagamos un repaso antes de adentrarnos en las prácticas de producción, ya que cada parte de este curso se basa en la anterior.
Las tres primeras lecciones sentaron las bases: un agente de IA es un sistema autónomo con un bucle de percepción-acción; la API se sustenta en tres objetos: Agent, Conversation y Entry; y lo que separa a un agente de un chatbot es la persistencia, las herramientas y las transferencias. Las lecciones 4 a 7 hicieron utilizables estos objetos: creación y configuración de agentes con client.beta.agents.create(), mantenimiento de conversaciones persistentes con conversations.start() y conversations.append(), y uso del modo directo sin agente cuando estás creando prototipos y la persistencia no aporta valor.
Las lecciones 8 a 11 añadieron capacidades. web_search te da acceso a información actual con citas automáticas; code_interpreter ejecuta Python en un entorno aislado (sandbox), proporcionando al agente resultados exactos allí donde el modelo por sí solo aproximaría; image_generation produce elementos visuales a partir de indicaciones de texto; document_library aporta RAG integrado a tus propios documentos. Las lecciones 12 a 16 mostraron luego cómo varios agentes trabajan juntos: las transferencias pasan el control de un agente a otro, la arquitectura de referencia empareja un enrutador central con especialistas, el modo servidor automatiza donde el modo cliente te mantiene en el bucle, y el encadenamiento ilimitado se desglosa en patrones lineales, en estrella e híbridos. Finalmente, la lección 17 lo cerró todo con barreras de seguridad, el principio de mínimo privilegio y la moderación aguas arriba.
Diseño de agentes robustos
Una frase resume todo el curso: un agente, una responsabilidad, una descripción que indique cuándo llamarlo. El contraste siguiente hace tangible la diferencia.
# CORRECTO — agente especializado con descripción precisa
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# INCORRECTO — agente genérico y vago
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
El segundo agente fallará de dos maneras a la vez. Ningún enrutador sabrá cuándo derivarle una solicitud, porque «un agente útil» no describe ninguna situación concreta. Y cuando se le llame, sus tres herramientas le dejarán libertad para buscar en la web algo que debería haber calculado, o para ilustrar algo que se le pidió analizar.
Gestión de errores
Las llamadas de red fallan tarde o temprano. Un reintento con retroceso exponencial absorbe incidentes transitorios sin convertir una ralentización momentánea en una interrupción visible.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Conversación con gestión de errores y reintentos."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Retroceso exponencial
return None
El retroceso exponencial —un segundo, luego dos, luego cuatro— distingue un reintento civilizado de machacar un servicio que ya está sufriendo. Observa también que el último intento vuelve a lanzar la excepción en lugar de devolver None: tu llamador necesita saber que la operación ha fallado.
Observabilidad del sistema
En producción, un flujo de trabajo multiagente que no puedes observar se vuelve imposible de depurar. El modo cliente te ofrece exactamente los ganchos que necesitas.
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Conversación con monitorización."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Esos dos contadores valen más de lo que sugiere su simplicidad: una desviación en el número medio de transferencias señala un enrutador que duda; un pico en las llamadas a herramientas apunta a consultas costosas.
El control de costes se reduce entonces a decisiones concretas. Monitoriza los tokens por conversación, ya que esa es la unidad real de facturación. Usa mistral-medium-latest siempre que mistral-large-latest no aporte nada: el primer nivel de soporte es un ejemplo de libro de texto. Limita max_tokens en completion_args para evitar respuestas interminables a preguntas simples, y desactiva el almacenamiento con store=False cuando no se requiera persistencia.
Pruebas de enrutamiento
Prueba un sistema multiagente como cualquier centralita: aliméntalo con casos cuyo destino esperado conozcas y verifica dónde aterrizan.
def test_agent_routing():
"""Verifica que el enrutador distribuye correctamente."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
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 = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Construye esta suite de pruebas con el tiempo: cada solicitud mal enrutada que captures en producción se convierte en otra línea en test_cases, y sabrás que reescribir una descripción arregla el caso objetivo sin romper otro.
Arquitectura de referencia
Para un proyecto de producción, esta es una arquitectura recomendada:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Reúne todo lo visto en este curso: el moderador filtra antes de cualquier ejecución, el enrutador dirige sin responder nunca él mismo, cada especialista lleva una herramienta y una responsabilidad, y la observación envuelve todo el sistema.
Hacia dónde ir ahora
Cuatro direcciones amplían lo que puedes hacer ahora. Function calling te permite construir tus propias herramientas personalizadas más allá de las integradas: llamar a una API de negocio, consultar una base de datos, activar un servicio interno. MCP Servers integran el Model Context Protocol, que estandariza cómo se exponen las herramientas. Structured outputs fuerzan las respuestas a un esquema JSON, lo cual lo cambia todo cuando la salida de un agente alimenta otro sistema en lugar de a un lector humano. Finalmente, streaming devuelve las respuestas en tiempo real en lugar de en un solo bloque: decisivo en cadenas largas, donde la espera silenciosa resulta incómoda.
Tres recursos acompañan este siguiente paso: la documentación oficial en docs.mistral.ai/agents, los cookbooks de Mistral que proporcionan ejemplos de implementación completos, y la Referencia de la API que documenta cada endpoint en detalle.
Puntos clave
- Especializa tus agentes: un agente = una responsabilidad
- Monitoriza: registra cada transferencia y ejecución de herramienta
- Prueba: valida el enrutamiento y las respuestas de cada agente
- Asegura: barreras de seguridad, mínimo privilegio, moderación aguas arriba
- Optimiza costes: modelo de tamaño adecuado, max_tokens, store=False cuando sea posible
- Mistral Agents está en beta: mantente al día con los cambios de la API
Pon a prueba tus conocimientos
Agentes, herramientas integradas, transferencias: ¿queda algún punto ciego en la API de Agents?
1. ¿Cuándo es necesario un agente y cuándo basta con un chatbot?
Respuesta: Un agente está justificado cuando necesitas herramientas, persistencia y decisiones en varios pasos; para preguntas y respuestas simples, basta una conversación estándar: la arquitectura sigue a la necesidad.
2. ¿Qué gestionan las conversaciones persistentes en la API de Agents?
Respuesta: El historial en el lado de Mistral: continúas una conversación por su ID sin reenviar todo el contexto; el estado se convierte en un servicio.
3. Enumera las herramientas integradas disponibles y su uso.
Respuesta: web_search (información en tiempo real), code_interpreter (ejecutar Python), image_generation (crear imágenes), document_library (preguntas y respuestas sobre tus archivos): capacidades listas para usar, sin necesidad de implementación.
4. ¿Cómo funciona un sistema multiagente con transferencias?
Respuesta: Un enrutador califica la solicitud y la pasa al agente especialista competente; cada agente se mantiene simple, la orquestación proporciona cobertura y las transferencias se encadenan en profundidad.
5. ¿Cómo se aseguran los agentes en producción?
Respuesta: Con barreras de seguridad en entradas/salidas, herramientas de alcance estrecho, trazabilidad de acciones y validación humana en decisiones de alto riesgo: la autonomía se gana mediante el control.
Agentes especializados, herramientas integradas, enrutamiento, barreras de seguridad: la arquitectura completa cabe en cuatro palabras, y este curso te ha hecho construir cada una.