Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Exemplo Prático: CRM Automatizado

Aula 13 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Um CRM Orientado por Conversação
  2. A Base de Dados Simulada
  3. As Funções CRUD
  4. Especificações das Ferramentas JSON
  5. Despacho e o Ciclo
  6. Quatro Cenários e o Que Ensinam
  7. Migrar para Produção Sem Reescrever Tudo
  8. Pontos-chave

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