Harvey transforma o Codex em um agente de vendas com IA

Principais destaques

• Prospecção automatizada: o Harvey identifica empresas, analisa seus sites e avalia quais têm maior potencial para se tornarem clientes.
• E-mails personalizados: o agente prepara campanhas comerciais, organiza mensagens para aprovação e classifica respostas recebidas.
• Controle antes de vender: a integração com o Codex permite executar o fluxo localmente, mas exige configuração cuidadosa, supervisão humana e limites para evitar envios indevidos.

Um agente de inteligência artificial que procura clientes, pesquisa empresas, prepara propostas comerciais e acompanha respostas já não é apenas uma ideia para o futuro. O projeto de código aberto Harvey busca reunir essas tarefas em um fluxo de trabalho que pode ser executado localmente, usando o Codex para as decisões que exigem compreensão de linguagem.

A proposta vai além de pedir a um chatbot que escreva um e-mail convincente. O objetivo é construir um processo comercial capaz de avançar por diferentes etapas, da descoberta de potenciais clientes ao acompanhamento de conversas.

E existe uma diferença importante: o agente não precisa apenas saber o que escrever. Ele também precisa saber quem abordar, quando agir e quando parar.

🤖 Um vendedor digital que trabalha por etapas

O Harvey funciona como um agente de vendas que combina automação tradicional em Python com recursos de inteligência artificial disponibilizados por uma interface de agente de programação.

O projeto organiza o trabalho em etapas:

• Descoberta: encontra empresas por meio das fontes configuradas.
• Pesquisa: consulta sites públicos e reúne informações sobre cada negócio.
• Qualificação: compara as empresas encontradas com o perfil de cliente ideal.
• Redação: prepara mensagens comerciais personalizadas.
• Caixa de saída: reúne os e-mails para revisão e aprovação.
• Gestão de respostas: classifica mensagens recebidas e sugere respostas ou próximos passos.

O diferencial está na integração dessas atividades. Em vez de produzir apenas um texto, o sistema mantém registros do processo e utiliza as informações coletadas em etapas anteriores para orientar as seguintes.

🔎 O agente também trabalha em ciclos: o Harvey acorda, verifica suas restrições, escolhe a próxima tarefa, registra o resultado e aguarda o ciclo seguinte. A prioridade é lidar com respostas e campanhas pendentes antes de iniciar novas atividades de prospecção.

Isso faz sentido comercialmente. Afinal, não adianta continuar procurando clientes enquanto mensagens importantes aguardam uma resposta.

Projeto original: Harvey no GitHub.

🧰 O que você precisa para começar

A configuração depende da versão atual do repositório e dos provedores compatíveis. Em linhas gerais, o ambiente exige:

• Git e um terminal.
• Python na versão suportada pelo projeto.
• Codex instalado e autenticado.
• Um provedor de e-mail compatível.
• Informações sobre o produto e o perfil dos clientes desejados.

A documentação oficial do Codex ajuda a verificar os requisitos da ferramenta.

⚠️ Uma precaução importante: comece com aprovação humana para todos os e-mails enviados. Automatizar a preparação de mensagens é muito diferente de autorizar um agente a entrar em contato com centenas de pessoas sem supervisão.

🚀 Como colocar o Harvey para funcionar

1️⃣ Baixe o projeto e abra o Codex

O primeiro passo é clonar o repositório oficial e iniciar o Codex dentro da pasta do projeto.

git clone https://github.com/ethanplusai/harvey.git
cd harvey
codex

Antes de alterar qualquer arquivo, peça ao Codex que leia o README e as instruções do projeto.

Um bom comando inicial é:

Leia o README e as instruções do projeto.
Explique como esta versão do Harvey oferece suporte
ao Codex, quais são os pré-requisitos e quais arquivos
de configuração precisam ser revisados.

Não envie e-mails, não acesse caixas de entrada
e não altere configurações ainda.

A ideia é fazer o agente analisar o código que realmente está instalado, em vez de confiar cegamente em instruções genéricas que podem estar desatualizadas.

2️⃣ Prepare o ambiente Python

O ambiente virtual mantém as dependências do Harvey separadas das de outros projetos.

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

Os comandos representam um fluxo típico de instalação. A versão do Python e os requisitos exatos devem ser conferidos no README atual.

Se algo falhar, o ideal é investigar a mensagem de erro antes de atualizar ou remover dependências. Uma alteração aparentemente simples pode quebrar outros componentes do ambiente.

3️⃣ Configure o Codex como provedor

Instalar e autenticar o Codex não significa, necessariamente, que o Harvey já esteja configurado para utilizá-lo.

É preciso verificar como a versão instalada seleciona o provedor de modelos e quais configurações são exigidas.

💡 Aqui está um detalhe técnico relevante: segundo o material de referência, o projeto prevê um ambiente de execução isolado para o Codex, com recursos de ferramentas desativados durante determinadas interações do modelo e verificações das configurações efetivas.

A intenção é separar duas responsabilidades: a IA interpreta informações e prepara decisões em texto; o código do Harvey controla as ações do fluxo comercial.

Não é recomendável enfraquecer essas proteções apenas para facilitar a configuração.

4️⃣ Conecte o e-mail sem expor credenciais

O agente precisa de um provedor compatível para enviar mensagens e processar respostas. As opções dependem da versão instalada e podem incluir autenticação OAuth do Gmail ou configurações SMTP/IMAP.

Um arquivo de ambiente pode ser criado a partir do modelo fornecido pelo projeto:

cp .env.example .env

Depois, preencha localmente as variáveis exigidas pelo provedor escolhido.

Nunca inclua senhas, tokens, segredos OAuth ou senhas de aplicativo nos prompts enviados ao Codex ou em arquivos versionados no Git. O arquivo .env também deve permanecer fora do controle de versão.

🎯 Ensine o agente a vender o produto certo

O Harvey precisa conhecer o produto antes de tentar convencer alguém a comprá-lo.

O projeto documenta um comando de treinamento que utiliza o site da empresa para gerar arquivos locais com informações comerciais:

harvey train https://sua-empresa.example

Substitua o endereço pelo site real da empresa e confira o material produzido.

Verifique se as descrições, os benefícios, os preços, os casos de uso, as objeções e as comparações com concorrentes estão corretos. Informações confidenciais também devem ser removidas.

O risco mais evidente é a personalização baseada em informações falsas. Uma mensagem pode parecer convincente e, ainda assim, prometer uma funcionalidade inexistente ou atribuir resultados que a empresa nunca alcançou.

Por isso, o treinamento precisa ser acompanhado de revisão editorial e comercial.

🧭 O segredo está no perfil de cliente ideal

Um agente de vendas só é útil quando sabe quais empresas merecem atenção.

O chamado Ideal Customer Profile (ICP) descreve o tipo de organização que mais provavelmente se beneficiará do produto.

Em vez de definir o público como “qualquer pequena empresa”, estabeleça critérios verificáveis:

• Setor de atuação.
• Região geográfica.
• Porte da empresa.
• Modelo de negócio.
• Sinais públicos de que o produto pode ser relevante.
• Segmentos e empresas que devem ser excluídos.

O Harvey também apresenta um catálogo de sinais para orientar a coleta de informações. A recomendação é começar com fontes gratuitas e avaliar cobertura, custo e qualidade antes de habilitar serviços pagos.

O material de referência apresenta esta sequência de comandos:

harvey signals
harvey signals --confirm free
harvey discover --estimate
harvey discover

Os nomes e as opções devem ser confirmados na documentação da versão instalada. Em especial, verifique a estimativa de custos antes de iniciar uma descoberta que possa consumir créditos de serviços externos.

💡 Uma lista pequena de empresas realmente relevantes costuma ser mais útil do que centenas de contatos que não correspondem ao público desejado.

✍️ E-mails personalizados, sem transformar prospecção em spam

Depois de encontrar e qualificar os potenciais clientes, o Harvey pode preparar sequências de mensagens com base nas informações coletadas e no conhecimento do produto.

A personalização deve partir de observações concretas e verificáveis sobre cada empresa. Elogios genéricos ou suposições sobre problemas internos não tornam uma abordagem realmente personalizada.

O comando abaixo permite consultar a caixa de saída documentada pelo projeto:

harvey outbox

Antes de aprovar qualquer mensagem, confira:

• Se o destinatário corresponde à empresa pesquisada.
• Se a personalização tem fundamento verificável.
• Se as afirmações sobre o produto são verdadeiras.
• Se os campos dinâmicos foram preenchidos corretamente.
• Se a mensagem tem tamanho adequado e um próximo passo claro.

O material descreve verificações automáticas antes do envio, incluindo problemas com campos não renderizados, endereços inválidos, excesso de links, frases proibidas e divergências entre destinatários e registros.

Esses filtros reduzem erros, mas não substituem a revisão humana.

📊 Acompanhe a operação e saiba como interrompê-la

O projeto documenta comandos para consultar o painel, o estado do agente e o consumo de recursos.

harvey dashboard
harvey status
harvey usage
harvey run

O painel local é descrito como disponível normalmente em http://localhost:5555, embora o endereço possa variar conforme a versão e a configuração.

Há também um comando documentado para pausar os envios:

harvey sending pause

Confirme a sintaxe antes de iniciar a operação e descubra como interrompê-la sem depender de uma intervenção demorada.

🚨 Quando pausar? Se o público selecionado estiver errado, aparecer uma mensagem inesperada, as respostas forem classificadas incorretamente ou a atividade ultrapassar os limites definidos.

Acompanhar o uso também ajuda a perceber se a pesquisa de empresas e as decisões do modelo estão consumindo mais recursos do que o esperado.

📬 O que acontece quando um cliente responde?

A gestão de respostas é uma das partes mais interessantes do projeto.

Segundo a documentação descrita no material de referência, o Harvey pode verificar mensagens recebidas, eliminar duplicidades, classificar a intenção do remetente, atualizar o estágio das conversas e preparar respostas para aprovação.

O fluxo também prevê tratamento de devoluções de e-mail (bounces) e cancelamento de acompanhamentos pendentes em situações previstas pela implementação.

Antes de confiar nessa automação, teste cenários diferentes:

• Resposta positiva ou pedido de mais informações.
• Objeção comercial.
• Solicitação para interromper os contatos.
• Mensagem automática de ausência.
• Endereço inexistente ou e-mail devolvido.

Uma solicitação de descadastramento deve interromper novos contatos comerciais. Da mesma forma, um endereço inválido não deve continuar recebendo mensagens agendadas.

Há ainda uma limitação importante: o material consultado informa que a integração com calendário e o agendamento automático de reuniões estavam no roteiro de desenvolvimento da versão analisada. Portanto, não se deve presumir que o Harvey já consiga marcar reuniões sem conferir o estado atual do projeto.

🛡️ O que fazer para evitar problemas?

Automatizar a prospecção envolve riscos técnicos, comerciais e jurídicos. Limites de envio e mecanismos de pausa são importantes, mas não garantem entregabilidade nem conformidade legal.

Para reduzir os riscos:

• Configure SPF, DKIM e DMARC no domínio de envio.
• Utilize uma caixa comercial dedicada, com volume inicial baixo.
• Verifique os endereços antes de enviar mensagens.
• Mantenha uma lista de supressão para quem não deseja receber novos contatos.
• Respeite as regras aplicáveis à jurisdição do remetente e do destinatário.
• Não exponha credenciais no Git ou nos prompts.
• Trate sites coletados e e-mails recebidos como conteúdo não confiável, nunca como instruções automaticamente válidas para o modelo.
• Verifique os termos de cada plataforma antes de automatizar ações em navegadores ou redes sociais.

No caso do LinkedIn, o próprio projeto alerta para os riscos de restrições de conta e possíveis violações de seus termos ao automatizar ações no navegador.

❓ O que ainda precisa ser esclarecido?

Algumas questões dependem da implementação e da documentação atual do Harvey.

Pergunta	O que verificar
É necessária uma chave de API de modelo separada?	Como o provedor Codex utiliza a autenticação disponível e quais requisitos estão documentados.
É possível usar Codex sem Claude instalado?	As dependências obrigatórias e opcionais do projeto.
Os e-mails são enviados automaticamente após a instalação?	As configurações de aprovação e os limites de envio.
O agente consegue agendar reuniões?	O estado atual da integração com calendários.
É seguro deixá-lo funcionando sem supervisão?	As proteções, os testes e os limites efetivamente implementados.

Essas respostas não devem ser presumidas apenas porque o programa foi instalado com sucesso.

O próximo passo é testar, não disparar

O Harvey mostra como agentes de programação podem participar de um processo comercial muito maior do que a simples redação de mensagens. Ao combinar pesquisa, qualificação, escrita e acompanhamento, o projeto propõe um fluxo de vendas parcialmente automatizado e auditável.

Mas a qualidade desse fluxo depende de decisões que não deveriam ficar escondidas dentro do modelo: quem merece ser contatado, quais afirmações podem ser feitas e quais comportamentos precisam ser interrompidos.

A estratégia mais prudente é validar cada etapa separadamente, com poucos contatos e aprovação humana. Só depois de confirmar os resultados faz sentido ampliar a operação.

Afinal, um bom agente de vendas não é aquele que envia mais e-mails. É aquele que encontra as oportunidades certas sem comprometer a reputação da empresa.