Exemplo Prático: CRM Automatizado
Nesta página
Um CRM Orientado por Conversação
Imagine um CRM onde os representantes de vendas já não precisam de navegar em interfaces complexas. Eles falam com um assistente que cria, atualiza e recupera contactos automaticamente. É exatamente isto que a chamada de funções (function calling) lhe permite construir. A diferença face ao rastreador de pagamentos da lição anterior é significativa: até agora, o modelo apenas lia dados. Aqui, ele escreve dados, o que desloca o foco do exercício para a validação, confirmação e gestão de duplicados.
Vai implementar um CRM conversacional com operações CRUD (Create, Read, Update, Delete) numa base de dados de contactos.
A Base de Dados Simulada
Um dicionário Python serve de base de dados para esta demonstração. Dois contactos são suficientes: um cliente e um prospetor. Esta configuração permite-nos testar mais tarde na lição uma transição de estado.
import json
import os
from mistralai.client import Mistral
# Base de dados de contactos em memória (em produção: 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 novos contactos
As Funções CRUD
get_contact e search_contacts tratam das operações de leitura. Esta última aceita um argumento de campo de pesquisa para evitar a criação de múltiplas funções quase idênticas. create_contact é a primeira função que modifica o estado do sistema e ilustra uma regra frequentemente negligenciada nos modos conversacionais: as verificações de unicidade devem residir no seu código, nunca no prompt fornecido ao modelo. Nada impede um representante de vendas de ditar o mesmo contacto duas vezes; a verificação de e-mail no início da função devolve duplicate_email com o ID existente, permitindo ao modelo explicar a recusa com precisão.
update_contact utiliza uma abordagem de campos opcionais: apenas os campos fornecidos são modificados, e a função devolve uma lista do que realmente mudou. Esta lista não é decorativa — permite ao assistente confirmar a modificação com uma frase exata, em vez de um vago “feito”.
def get_contact(contact_id: str) -> str:
"""Recupera informações de um 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:
"""Procura contactos por nome, empresa ou 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:
"""Cria um novo contacto no CRM."""
global next_id
# Verifica se o e-mail já 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:
"""Atualiza um ou mais campos de um 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"})
O parâmetro ensure_ascii=False presente em vários retornos não é um detalhe cosmético: sem ele, “Interested” torna-se numa cadeia de sequências de escape Unicode no contexto do modelo, o que é menos legível e mais dispendioso em tokens.
Especificações das Ferramentas JSON
Dois mecanismos garantem aqui a maior parte da fiabilidade. O enum em status impede o modelo de inventar valores: ele deve escolher entre prospect, client, partner e inactive, protegendo a integridade dos seus dados sem validação adicional. O array required faz o resto, distinguindo campos obrigatórios de opcionais — para create_contact, um contacto sem nome, e-mail ou empresa não faz sentido, enquanto um número de telefone pode ficar para depois.
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 e o Ciclo
Como as funções não dependem de objetos externos, o dicionário de despacho reduz-se a um mapeamento direto. A mensagem do sistema, no entanto, carrega duas restrições comportamentais ausentes do código: confirmar cada ação de criação ou atualização com detalhes e solicitar informações em falta antes de criar um contacto. Sem essa segunda instrução, o modelo tende a preencher campos obrigatórios com valores plausíveis.
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."
}
]
Quatro Cenários e o Que Ensinam
O primeiro cenário mostra o modelo a escolher field="company" por conta própria, mesmo que o utilizador não tenha especificado nada: o enum do esquema forneceu as opções, e a formulação da questão fez o resto. O segundo fornece informações de forma desordenada, sem rótulos, e o modelo distribui-as corretamente entre nome, e-mail, empresa e cargo. O terceiro é o mais rico: “Mude Pierre Martin para cliente, ele acabou de assinar” não contém ID, pelo que o modelo deve encadear uma pesquisa e depois uma atualização, inferindo a nota contextual no processo. O quarto lembra-nos que o modelo pode reaproveitar uma função do seu uso literal para responder a uma pergunta de contagem.
# Cenário 1: Procurar um contacto
chat("Find me contacts at TechCorp")
# -> O modelo chama search_contacts(query="TechCorp", field="company")
# -> "I found 1 contact at TechCorp: Marie Dupont (CT001),
# Chief Technology Officer, status client."
# Cenário 2: Criar um contacto
chat("Add a new contact: Sophie Laurent, [email protected], "
"DataViz, Data Scientist")
# -> O modelo chama 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."
# Cenário 3: Atualizar um estado
chat("Switch Pierre Martin to client, he just signed")
# -> O modelo primeiro procura por Pierre Martin, depois chama
# 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."
# Cenário 4: Pergunta sem função dedicada
chat("How many prospects do we have?")
# -> O modelo chama search_contacts(query="prospect", field="status")
# -> "You currently have 1 prospect: Sophie Laurent at DataViz."
Migrar para Produção Sem Reescrever Tudo
O dicionário em memória obviamente desaparece assim que há múltiplos utilizadores. Substituí-lo por uma base de dados real, no entanto, requer tocar apenas numa camada: a função consulta o ORM ou a API do seu CRM e continua a devolver a mesma cadeia JSON.
# As funções chamam o ORM ou a API do seu CRM
def get_contact_production(contact_id: str) -> str:
"""Versão de produção com 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"})
O resto do código — ferramentas, despacho, ciclo de conversação — permanece idêntico. Esta é a força desta arquitetura: apenas as funções de lógica de negócio mudam, e a camada conversacional permanece alheia às suas escolhas de persistência.
Pontos-chave
- A chamada de funções transforma um LLM numa interface natural para um CRM
- As operações CRUD mapeiam diretamente para funções com JSON Schema
- O modelo pode encadear pesquisa e depois atualização numa única conversação
- A arquitetura está desacoplada: altere a base de dados sem tocar na lógica de conversação
- A mensagem do sistema é crucial para orientar o modelo sobre confirmações e informações em falta