Ejemplo práctico: CRM automatizado
En esta página
Un CRM impulsado por conversación
Imagina un CRM donde los comerciales ya no necesitan navegar por interfaces complejas. Hablan con un asistente que crea, actualiza y recupera contactos automáticamente. Esto es exactamente lo que la llamada a funciones te permite construir. La diferencia respecto al rastreador de pagos de la lección anterior es significativa: hasta ahora, el modelo solo leía datos. Aquí, escribe datos, lo que desplaza el foco del ejercicio hacia la validación, la confirmación y la gestión de duplicados.
Vas a implementar un CRM conversacional con operaciones CRUD (Crear, Leer, Actualizar, Borrar) sobre una base de datos de contactos.
La base de datos simulada
Un diccionario de Python sirve de base de datos para esta demostración. Dos contactos son suficientes: un cliente y un posible cliente (prospect). Esta configuración nos permite probar más adelante en la lección una transición de estado.
import json
import os
from mistralai.client import Mistral
# Base de datos de contactos en memoria (en producción: PostgreSQL, MongoDB, etc.)
contacts_db = {
"CT001": {
"name": "Marie Dupont",
"email": "[email protected]",
"company": "TechCorp",
"role": "Chief Technology Officer",
"phone": "+33 6 12 34 56 78",
"status": "client",
"notes": "Interested in the enterprise solution"
},
"CT002": {
"name": "Pierre Martin",
"email": "[email protected]",
"company": "StartupIO",
"role": "CEO",
"phone": "+33 6 98 76 54 32",
"status": "prospect",
"notes": "Meeting scheduled for April"
}
}
next_id = 3 # Contador para nuevos contactos
Las funciones CRUD
get_contact y search_contacts gestionan las operaciones de lectura. Esta última acepta un argumento de campo de búsqueda para evitar crear múltiples funciones casi idénticas. create_contact es la primera función que modifica el estado del sistema, e ilustra una regla que a menudo se pasa por alto en los modos conversacionales: las comprobaciones de unicidad deben residir en tu código, nunca en el prompt dado al modelo. Nada impide que un comercial dicte el mismo contacto dos veces; la verificación del correo electrónico al inicio de la función devuelve duplicate_email con el ID existente, lo que permite al modelo explicar el rechazo con precisión.
update_contact utiliza un enfoque de campos opcionales: solo se modifican los campos proporcionados, y la función devuelve una lista de lo que realmente ha cambiado. Esta lista no es decorativa; permite al asistente confirmar la modificación con una frase exacta en lugar de un vago «hecho».
def get_contact(contact_id: str) -> str:
"""Recupera la información de un contacto."""
if contact_id in contacts_db:
contact = contacts_db[contact_id].copy()
contact["contact_id"] = contact_id
return json.dumps(contact, ensure_ascii=False)
return json.dumps({"error": f"Contact {contact_id} not found"})
def search_contacts(query: str, field: str = "name") -> str:
"""Busca contactos por nombre, empresa o estado."""
results = []
for cid, contact in contacts_db.items():
if field in contact and query.lower() in contact[field].lower():
entry = contact.copy()
entry["contact_id"] = cid
results.append(entry)
if results:
return json.dumps({"results": results, "count": len(results)},
ensure_ascii=False)
return json.dumps({"results": [], "count": 0,
"message": f"No contact found for '{query}' in '{field}'"})
def create_contact(name: str, email: str, company: str,
role: str = "", phone: str = "",
status: str = "prospect", notes: str = "") -> str:
"""Crea un nuevo contacto en el CRM."""
global next_id
# Comprobar si el correo electrónico ya existe
for cid, contact in contacts_db.items():
if contact["email"].lower() == email.lower():
return json.dumps({
"error": "duplicate_email",
"message": f"A contact with this email already exists: {cid}"
})
contact_id = f"CT{next_id:03d}"
next_id += 1
contacts_db[contact_id] = {
"name": name,
"email": email,
"company": company,
"role": role,
"phone": phone,
"status": status,
"notes": notes
}
return json.dumps({
"success": True,
"contact_id": contact_id,
"message": f"Contact {name} created with ID {contact_id}"
}, ensure_ascii=False)
def update_contact(contact_id: str, **fields) -> str:
"""Actualiza uno o más campos de un contacto existente."""
if contact_id not in contacts_db:
return json.dumps({"error": f"Contact {contact_id} not found"})
updated_fields = []
for key, value in fields.items():
if key in contacts_db[contact_id]:
contacts_db[contact_id][key] = value
updated_fields.append(key)
if updated_fields:
return json.dumps({
"success": True,
"contact_id": contact_id,
"updated_fields": updated_fields,
"message": f"Contact {contact_id} updated: {', '.join(updated_fields)}"
}, ensure_ascii=False)
return json.dumps({"error": "No valid fields to update"})
El parámetro ensure_ascii=False presente en varias devoluciones no es un detalle cosmético: sin él, «Interested» se convierte en una cadena de secuencias de escape Unicode en el contexto del modelo, lo cual es menos legible y más costoso en tokens.
Especificaciones de la herramienta JSON
Dos mecanismos aportan la mayor parte de la fiabilidad aquí. El enum en status evita que el modelo invente valores: debe elegir entre prospect, client, partner e inactive, protegiendo la integridad de tus datos sin validación adicional. El array required hace el resto distinguiendo campos obligatorios de opcionales; para create_contact, un contacto sin nombre, correo electrónico o empresa no tiene sentido, mientras que un número de teléfono puede añadirse más tarde.
tools = [
{
"type": "function",
"function": {
"name": "get_contact",
"description": "Retrieves all information for a contact by ID",
"parameters": {
"type": "object",
"properties": {
"contact_id": {
"type": "string",
"description": "Contact ID (e.g., CT001)"
}
},
"required": ["contact_id"]
}
}
},
{
"type": "function",
"function": {
"name": "search_contacts",
"description": "Searches for contacts by name, company, or status",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search term"
},
"field": {
"type": "string",
"enum": ["name", "company", "status", "role"],
"description": "Field to search in (default: name)"
}
},
"required": ["query"]
}
}
},
{
"type": "function",
"function": {
"name": "create_contact",
"description": "Creates a new contact in the CRM",
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Full name of the contact"
},
"email": {
"type": "string",
"description": "Email address of the contact"
},
"company": {
"type": "string",
"description": "Company name"
},
"role": {
"type": "string",
"description": "Job title or function within the company"
},
"phone": {
"type": "string",
"description": "Phone number"
},
"status": {
"type": "string",
"enum": ["prospect", "client", "partner", "inactive"],
"description": "Contact status"
},
"notes": {
"type": "string",
"description": "Free-form notes about the contact"
}
},
"required": ["name", "email", "company"]
}
}
},
{
"type": "function",
"function": {
"name": "update_contact",
"description": "Updates information for an existing contact",
"parameters": {
"type": "object",
"properties": {
"contact_id": {
"type": "string",
"description": "ID of the contact to modify (e.g., CT001)"
},
"name": {"type": "string", "description": "New name"},
"email": {"type": "string", "description": "New email"},
"company": {"type": "string", "description": "New company"},
"role": {"type": "string", "description": "New job title"},
"phone": {"type": "string", "description": "New phone number"},
"status": {
"type": "string",
"enum": ["prospect", "client", "partner", "inactive"],
"description": "New status"
},
"notes": {"type": "string", "description": "New notes"}
},
"required": ["contact_id"]
}
}
}
]
Despacho y el bucle
Dado que las funciones no dependen de objetos externos, el diccionario de despacho se reduce a una asignación directa. El mensaje del sistema, sin embargo, contiene dos restricciones de comportamiento ausentes en el código: confirmar cada acción de creación o actualización con detalles, y solicitar la información faltante antes de crear un contacto. Sin esa segunda instrucción, el modelo tiende a rellenar los campos obligatorios con valores plausibles.
available_functions = {
"get_contact": get_contact,
"search_contacts": search_contacts,
"create_contact": create_contact,
"update_contact": update_contact,
}
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"
messages = [
{
"role": "system",
"content": "You are a CRM assistant. You help sales reps "
"manage their contacts. Respond in English. "
"When you create or modify a contact, confirm "
"the action with details. Request missing "
"information before creating a contact."
}
]
Cuatro escenarios y lo que enseñan
El primer escenario muestra al modelo eligiendo field="company" por su cuenta aunque el usuario no especificó nada: el enum del esquema proporcionó las opciones, y la formulación de la pregunta hizo el resto. El segundo proporciona información desordenada, sin etiquetas, y el modelo la distribuye correctamente entre nombre, correo electrónico, empresa y título. El tercero es el más rico: «Switch Pierre Martin to client» no contiene ningún ID, por lo que el modelo debe encadenar una búsqueda y luego una actualización, infiriendo la nota contextual en el proceso. El cuarto nos recuerda que el modelo puede reutilizar una función de su uso literal para responder a una pregunta de conteo.
# Escenario 1: Buscar un contacto
chat("Find me contacts at TechCorp")
# -> El modelo llama a search_contacts(query="TechCorp", field="company")
# -> "I found 1 contact at TechCorp: Marie Dupont (CT001),
# Chief Technology Officer, status client."
# Escenario 2: Crear un contacto
chat("Add a new contact: Sophie Laurent, [email protected], "
"DataViz, Data Scientist")
# -> El modelo llama a create_contact(name="Sophie Laurent",
# email="[email protected]", company="DataViz", role="Data Scientist")
# -> "Contact created successfully! Sophie Laurent (CT003) has been added
# as a prospect at DataViz."
# Escenario 3: Actualizar un estado
chat("Switch Pierre Martin to client, he just signed")
# -> El modelo busca primero a Pierre Martin, luego llama a
# update_contact(contact_id="CT002", status="client",
# notes="Contract signed in April 2026")
# -> "Pierre Martin (CT002) is now marked as a client.
# I added a note about the contract signature."
# Escenario 4: Pregunta sin una función dedicada
chat("How many prospects do we have?")
# -> El modelo llama a search_contacts(query="prospect", field="status")
# -> "You currently have 1 prospect: Sophie Laurent at DataViz."
Pasar a producción sin reescribirlo todo
El diccionario en memoria obviamente desaparece en cuanto hay múltiples usuarios. Sustituirlo por una base de datos real, sin embargo, requiere tocar solo una capa: la función consulta el ORM o la API de tu CRM y sigue devolviendo la misma cadena JSON.
# Las funciones llaman al ORM o API de tu CRM
def get_contact_production(contact_id: str) -> str:
"""Versión de producción con PostgreSQL."""
contact = db.session.query(Contact).filter_by(id=contact_id).first()
if contact:
return json.dumps(contact.to_dict(), ensure_ascii=False)
return json.dumps({"error": f"Contact {contact_id} not found"})
El resto del código —herramientas, despacho, bucle de conversación— permanece idéntico. Esta es la fuerza de esta arquitectura: solo cambian las funciones de lógica de negocio, y la capa conversacional permanece ajena a tus elecciones de persistencia.
Puntos clave
- La llamada a funciones convierte un LLM en una interfaz natural para un CRM
- Las operaciones CRUD se mapean directamente a funciones con JSON Schema
- El modelo puede encadenar búsqueda y luego actualización dentro de una sola conversación
- La arquitectura está desacoplada: cambia la base de datos sin tocar la lógica de conversación
- El mensaje del sistema es crucial para guiar al modelo en las confirmaciones y la información faltante