Introdução à criação de AI Agents com LangChain : Criando um Agente de Cobrança
- #SQL
- #Python
- #Inteligência Artificial (IA)
Como a Inteligência Artificial Está Transformando a Cobrança
A inteligência artificial está revolucionando diversos setores, e o segmento de cobrança não é exceção. Com o avanço dos agentes inteligentes, as empresas buscam automatizar processos, reduzir custos e melhorar a experiência do cliente. Este artigo fala como agentes de IA podem ser aplicados à cobrança, fala de como funciona e compartilha um estudo de caso real de implementação.
Desmistificando Agentes Inteligentes
Os agentes de IA são sistemas capazes de compreender o ambiente, tomar decisões e agir de forma independente para atingir objetivos específicos. Eles podem variar desde agentes simples, que seguem regras pré-definidas, até agentes independentes que aprendem e se adaptam com o tempo.
Desmistificando LangChain
O LangChain é um framework desenvolvido para a criação de aplicações que utilizam modelos de IA em suas funcionalidades. Ele possibilita a construção de chatbots, geração de texto, análise de sentimentos e muito mais. Além disso, o LangChain já vem com um kit robusto para o uso de IA e integração com múltiplos modelos, facilitando o desenvolvimento de agentes e outras ferramentas baseadas em inteligência artificial.
Caso de Uso: O Desafio da Cobrança Tradicional
O processo tradicional de cobrança envolve equipes grandes realizando ligações, enviando e-mails e negociando pagamentos. Esse modelo apresenta desafios como alto custo operacional, baixa escalabilidade, inconsistência nas abordagens e, muitas vezes, uma experiência negativa para o cliente. Além disso, a capacidade de personalização é limitada, dificultando a adaptação ao perfil de cada devedor.
Além disso, as vezes os próprios devedores querem fazer um acordo ou acompanhar as suas dívidas, coisa que acaba gastando mão de obra a mais apenas para tratar esses casos que poderia ser feita de forma muito melhor e automática. Esse é o caso que vamos usar nesse artigo e vamos desenvolver nosso agente para abordar esses clientes.
Montando Nosso Ambiente de Desenvolvimento
Para que o agente saiba como agir, é necessário que ele tenha acesso às informações relevantes. Para isso, vamos criar um banco de dados de estudo que servirá para alimentar o nosso agente.
Criando a tabela.
create database if not exists sistema_negociacao;
use sistema_negociacao;
CREATE TABLE negociadores (
id INT AUTO_INCREMENT PRIMARY KEY,
nome VARCHAR(100) NOT NULL,
data_admissao DATE NOT NULL,
status BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE TABLE devedores (
id INT AUTO_INCREMENT PRIMARY KEY,
nome VARCHAR(100) NOT NULL,
cpf_cnpj VARCHAR(20) NOT NULL
);
CREATE TABLE dividas (
id INT AUTO_INCREMENT PRIMARY KEY,
devedor_id INT NOT NULL,
valor DECIMAL(12,2) NOT NULL,
data_venc DATE NOT NULL,
descricao TEXT,
FOREIGN KEY (devedor_id) REFERENCES devedores(id)
);
CREATE TABLE acordos (
id INT AUTO_INCREMENT PRIMARY KEY,
divida_id INT NOT NULL,
negociador_id INT NOT NULL,
valor_acordo DECIMAL(12,2) NOT NULL,
qtd_parcelas INT NOT NULL,
data_acordo DATE NOT NULL,
cancelado BOOLEAN NOT NULL DEFAULT FALSE,
FOREIGN KEY (divida_id) REFERENCES dividas(id),
FOREIGN KEY (negociador_id) REFERENCES negociadores(id)
);
Com essa pequena tabela vamos preenchê-la com alguns dados.
sql
INSERT INTO negociadores (nome, data_admissao, status) VALUES
('João Silva', '2023-01-15', TRUE),
('Maria Santos', '2023-03-20', TRUE),
('Pedro Oliveira', '2023-06-10', TRUE),
('Ana Costa', '2023-08-01', FALSE);
INSERT INTO devedores (nome, cpf_cnpj) VALUES
('Carlos Mendes', '123.456.789-00'),
('Empresa XYZ Ltda', '12.345.678/0001-90'),
('Mariana Souza', '987.654.321-00'),
('José Pereira', '456.789.123-00'),
('Amanda Lima', '789.123.456-00'),
('Roberto Almeida', '234.567.890-11'),
('Fernanda Castro', '345.678.901-22'),
('Supermercado ABC Ltda', '23.456.789/0001-12'),
('Paulo Ribeiro', '456.789.012-33'),
('Lucia Ferreira', '567.890.123-44');
INSERT INTO dividas (devedor_id, valor, data_venc, descricao) VALUES
(1, 1500.00, '2023-12-15', 'Empréstimo pessoal'),
(1, 800.00, '2023-11-30', 'Cartão de crédito'),
(2, 5000.00, '2023-10-20', 'Fornecedores'),
(3, 2300.00, '2023-12-01', 'Financiamento'),
(4, 1200.00, '2023-11-15', 'Empréstimo pessoal'),
(5, 3500.00, '2023-12-10', 'Cartão de crédito'),
(6, 4200.00, '2024-01-15', 'Empréstimo comercial'),
(6, 1800.00, '2024-02-10', 'Cartão de crédito'),
(7, 3500.00, '2024-01-20', 'Financiamento pessoal'),
(8, 12000.00, '2024-02-01', 'Dívida com fornecedores'),
(8, 8500.00, '2024-01-25', 'Empréstimo capital de giro'),
(9, 2800.00, '2024-02-05', 'Empréstimo pessoal'),
(10, 5600.00, '2024-01-30', 'Financiamento veículo');
INSERT INTO acordos (divida_id, negociador_id, valor_acordo, qtd_parcelas, data_acordo, cancelado) VALUES
(1, 1, 1200.00, 6, '2024-01-10', FALSE),
(2, 2, 700.00, 3, '2024-01-15', FALSE),
(3, 1, 4500.00, 10, '2024-01-05', FALSE),
(4, 3, 2000.00, 5, '2024-01-20', TRUE),
(5, 2, 1000.00, 4, '2024-01-25', FALSE);
Vamos prosseguir com a instalação das bibliotecas necessárias em nosso ambiente virtual Python.
python –m venv venv
(venv) pip install –r ./requirements.txt
Com o ambiente pronto, vamos começar a estruturar o nosso agente.
No primeiro arquivo, faremos as configurações básicas para estabelecer a conexão com o banco de dados.
db.py
import os
import pymysql
from dotenv import load_dotenv
load_dotenv()
def get_db_connection():
return pymysql.connect(
host=os.getenv("DB_HOST"),
port=int(os.getenv("DB_PORT")),
user=os.getenv("DB_USER"),
password=os.getenv("DB_PASSWORD"),
database=os.getenv("DB_NAME"),
cursorclass=pymysql.cursors.DictCursor
)
Após configurar o banco de dados, precisamos criar as 'tools' que o agente irá analisar para decidir qual método utilizar.
tools.py
from langchain.tools import tool
from db import get_db_connection
from datetime import datetime
class NegociacaoTools:
@tool("consultar_cpf")
def consultar_cpf(cpf: str):
"""
Use esta ferramenta SEMPRE que precisar iniciar uma negociação ou consultar dados do cliente.
Informe o CPF do cliente para obter o nome e o ID do devedor.
"""
conn = get_db_connection()
with conn.cursor() as cursor:
cursor.execute("SELECT id, nome FROM devedores WHERE cpf_cnpj = %s", (cpf,))
result = cursor.fetchone()
conn.close()
return result or {}
@tool("ver_divida")
def ver_divida(devedor_id: int):
"""
Use esta ferramenta APÓS consultar o CPF e obter o ID do devedor.
Informe o ID do devedor para obter o valor total das dívidas pendentes.
"""
conn = get_db_connection()
with conn.cursor() as cursor:
cursor.execute("SELECT SUM(valor) as total FROM dividas WHERE devedor_id = %s", (devedor_id,))
result = cursor.fetchone()
conn.close()
return result.get('total') if result else 0
@tool("ver_acordo")
def ver_acordo(devedor_id: int):
"""
Use esta ferramenta APÓS consultar o CPF e obter o ID do devedor.
Informe o ID do devedor para verificar se já existe um acordo ativo e seu valor.
"""
conn = get_db_connection()
with conn.cursor() as cursor:
cursor.execute("""
SELECT valor_acordo FROM acordos a
JOIN dividas d ON a.divida_id = d.id
WHERE d.devedor_id = %s AND a.cancelado = FALSE
ORDER BY a.data_acordo DESC LIMIT 1
""", (devedor_id,))
result = cursor.fetchone()
conn.close()
return result.get('valor_acordo') if result else "Nenhum acordo encontrado."
@tool("registrar_acordo")
def registrar_acordo(devedor_id: int, negociador_id: int, valor_acordo: float, qtd_parcelas: int):
"""
Use esta ferramenta APÓS consultar CPF e dívida, quando o cliente aceitar um acordo.
Informe o ID do devedor, ID do negociador, valor do acordo e quantidade de parcelas.
"""
conn = get_db_connection()
with conn.cursor() as cursor:
cursor.execute("SELECT id FROM dividas WHERE devedor_id = %s ORDER BY data_venc DESC LIMIT 1", (devedor_id,))
divida = cursor.fetchone()
if not divida:
conn.close()
return "Nenhuma dívida encontrada para registrar acordo."
cursor.execute("""
INSERT INTO acordos (divida_id, negociador_id, valor_acordo, qtd_parcelas, data_acordo)
VALUES (%s, %s, %s, %s, %s)
""", (divida['id'], negociador_id, valor_acordo, qtd_parcelas, datetime.now().date()))
conn.commit()
conn.close()
return "Acordo registrado com sucesso."
Observe que, sempre que criamos um método, incluímos uma docstring explicando claramente o que a função faz. Isso não serve apenas para manter o código organizado, mas também é fundamental para que o agente possa escolher a ferramenta mais adequada. Por isso, ao criar uma ferramenta, procure sempre deixar a docstring o mais detalhada e clara possível, pois isso aumenta a assertividade do agente.
Uma boa descrição das ferramentas faz muita diferença na qualidade do agente, e o prompt também é um fator importante nesse processo. Assim, para o nosso agente de cobrança, vamos utilizar um prompt adequado para garantir que ele siga o fluxo correto e não se perca durante a execução.
prompts.py
from langchain.schema import SystemMessage
system_message = SystemMessage(content="""
Você é um assistente virtual especializado em negociações de dívidas. Siga SEMPRE este fluxo:
1. Solicite o CPF do cliente.
2. Consulte o CPF usando a ferramenta 'consultar_cpf' para obter o ID do devedor.
3. Verifique se o cliente já possui um acordo ativo usando a ferramenta 'ver_acordo'. Se houver acordo ativo, informe o valor ao cliente e pergunte se deseja algo mais.
4. Caso não haja acordo ativo, consulte a dívida usando a ferramenta 'ver_divida' com o ID obtido.
5. Informe ao cliente o valor da dívida e pergunte se deseja fazer um acordo.
6. Se o cliente aceitar, pergunte o valor e a quantidade de parcelas desejadas.
7. Registre o acordo usando a ferramenta 'registrar_acordo'.
Nunca pule etapas. Sempre confirme claramente cada etapa com o cliente antes de prosseguir.
""")
Após prepararmos o ambiente, vamos para a parte central do nosso projeto. Neste arquivo, vamos reunir tudo o que desenvolvemos até agora para, de fato, criar o nosso agente de cobrança.
agent.py
from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI
from langchain.memory import ConversationBufferMemory
from langchain.prompts import MessagesPlaceholder
from tools import NegociacaoTools
from prompts import system_message
llm = ChatOpenAI(model="gpt-4.1-mini-2025-04-14", temperature=0)
tools = [
NegociacaoTools.consultar_cpf,
NegociacaoTools.ver_divida,
NegociacaoTools.ver_acordo,
NegociacaoTools.registrar_acordo
]
memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
agent_kwargs = {
"extra_prompt_messages": [MessagesPlaceholder(variable_name="chat_history"), system_message]
}
agent = initialize_agent(
tools, llm,
agent=AgentType.OPENAI_FUNCTIONS,
memory=memory,
agent_kwargs=agent_kwargs,
verbose=True
)
Neste agente, utilizei a API da OpenAI, mas o LangChain é compatível com diversos outros modelos. Optei pelo GPT-4.1 mini por ser uma opção mais econômica, mas recomendo testar outros modelos, pois isso pode trazer melhorias ao agente. Lembre-se: o modelo de IA é importante, mas não é tudo, de nada adianta usar o melhor modelo se o prompt e as docstrings não forem bem elaborados.
Com isso, nosso agente está praticamente pronto. Para tornar a interação mais agradável, vamos criar uma interface simples que permita interagir facilmente com o agente.
app.py
import streamlit as st
from agent import agent
st.set_page_config(page_title="Negociação de Dívidas com IA", page_icon="💬", layout="centered")
st.title("💬 Agent - IA de Negociação de Dívidas")
if "messages" not in st.session_state:
st.session_state.messages = []
for message in st.session_state.messages:
with st.chat_message(message["role"]):
st.markdown(message["content"])
if prompt := st.chat_input("Digite sua mensagem aqui..."):
st.session_state.messages.append({"role": "user", "content": prompt})
with st.chat_message("user"):
st.markdown(prompt)
with st.chat_message("assistant"):
with st.spinner("Processando..."):
resposta = agent.invoke({"input": prompt})
if isinstance(resposta, dict) and "output" in resposta:
resposta_texto = resposta["output"]
else:
resposta_texto = str(resposta)
st.markdown(resposta_texto)
st.session_state.messages.append({"role": "assistant", "content": resposta_texto})
Com isso nosso agente está funcionando e com uma interface bacana. Podendo visualizar utilizando o comando.
(venv) streamlit run ./app.py
Agora vamos ver nosso agente em ação fazendo uma pergunta como se fossemos um cliente que já tem um acordo
Agora vamos simular um cliente que não tem nenhum acordo.
Parabéns, você criou seu primeiro agente! Esse é só o começo. Com prática, testes e ajustes, você vai descobrir quais modelos, prompts e ferramentas funcionam melhor para o seu caso.
Agora que o agente está pronto, talvez você esteja se perguntando para que servem alguns elementos do código. Por isso, vou explicar os principais pontos desse agente.
Como as Coisas Funcionan Debaixo do Capô
inicialize_agent, AgentType : Funções e enums do LangChain para criar e configurar agentes conversacionais.
ChatOpenAI: Classe que representa o modelo de linguagem da OpenAI
ConversationBufferMemory: Objeto de memória que armazena o histórico da conversa, permitindo que o agente lembre do contexto
MessagesPlaceholder: Permite inserir o histórico de mensagens no prompt do agente.
AgentType.OPENAI_FUNCTIONS: Define o tipo de agente.
OPENAI_FUNCTION: permite que o modelo escolha e chame funções Python (tools.py) de acordo com a necessidade da conversa.
verbose=True: Exibe logs detalhados do que o agente está fazendo.
Como Funciona a Parte Crucial?: agent.invoke()
O agent.invoke() é um método que envia a mensagem do usuário para o agente processar. O agente monta o contexto da conversa adicionando o histórico da conversa, as ferramentas disponíveis no sistema e a mensagem atual. Envia para o modelo de IA, o modelo decide se é necessário usar alguma função ou se pode finalizar o chat.
Casos Reais
Forbes Brasil:
Segundo reportagem da Forbes, empresas como a C&A conseguiram aumentar em torno de 30% a recuperação em todas as faixas de cobrança após a adoção de IA, além de reduzir despesas de cobrança em até cinco vezes. A efetividade da cobrança digital subiu de 50% para 70% para pessoas com até 60 dias de atraso, e o nível de satisfação do cliente aumentou em 10 pontos.
Gazeta do Povo:
Ferramentas de IA melhoram a experiência do cliente e trazem eficiência e inovação para o setor de cobrança, segundo pesquisa com 411 organizações brasileiras em 2024.
EM/Mundo Corporativo:
Dados de 2024 do SPC Brasil e CNDL mostram que 72% das empresas já utilizam alguma estratégia de IA, sendo que o uso de chatbots e negociação por WhatsApp já é realidade em grandes empresas de cobrança.
Benefícios e Impactos
A automação trouxe ganhos claros: redução de custos operacionais, aumento da eficiência e melhora na experiência do cliente. O agente também permitiu que a equipe focasse em casos mais complexos, enquanto o sistema cuidava do volume.
Links Úteis
Conclusão
Os Agentes de IA representam uma evolução significativa nos processos de cobrança, combinando eficiência operacional com melhor experiência para o cliente. O estudo de caso apresentado mostra que, com planejamento e monitoramento adequado, é possível obter resultados expressivos. Para empresas que desejam inovar, investir em agentes inteligentes pode ser o diferencial competitivo necessário para o futuro.
