> Crie um agente de IA que qualifica compradores e inquilinos, mostra imóveis e agenda visitas no WhatsApp e no Instagram antes de passar para um corretor. # Agente de IA para imobiliárias Um agente de IA para uma imobiliária atende as pessoas que escrevem sobre um imóvel pelo WhatsApp, pelas DMs do Instagram e no seu site. Ele descobre se querem comprar ou alugar, o orçamento, o bairro e como vão pagar, mostra os imóveis compatíveis com um link para cada um e agenda uma visita com um corretor. Ele nunca negocia nem orienta sobre financiamento; isso vai para uma pessoa. Com a Vatio você descreve esse agente em um arquivo `vatio.yml` e ele responde no seu próprio número de WhatsApp e na sua conta do Instagram. Este guia constrói um de ponta a ponta: as instruções, as tools que chegam aos seus imóveis e às agendas dos seus corretores, o conhecimento que ele lê e as regras que o impedem de prometer o que só um corretor pode. ## O que o agente resolve Quase tudo o que chega a uma imobiliária pelo WhatsApp e pelo Instagram são as mesmas conversas: - **“Valor?” embaixo de um post.** A DM mais comum no Instagram, muitas vezes com um print. O agente encontra o imóvel e responde com o valor, os dados principais e o link. - **Qualificar.** Comprar ou alugar, orçamento, bairros, quartos e, para quem compra, se vai usar financiamento bancário, FGTS ou pagar à vista. Perguntado na conversa, uma ou duas coisas por vez, não como um formulário. - **Imóveis compatíveis.** Uma busca nos seus imóveis com o que a pessoa disse, e até três resultados, cada um com o seu link. - **Agendar visitas.** Horários livres para aquele imóvel, e um agendamento no seu sistema com as respostas do lead anexadas. - **Dúvidas sobre o processo.** O que é preciso para alugar, quanto custa comprar além do preço, quanto tempo leva. - **Todo o resto vai para um corretor.** Propostas, negociação, contratos, orientação sobre financiamento, proprietários que querem anunciar. Uma conversa típica pelo Instagram, com o que o agente fez por dentro: > **Visitante:** valor? *(print de um post)* > > **Agente:** É o imóvel CN-2041, um apartamento de dois quartos em Pinheiros: R$ 3.800 de aluguel, mais condomínio e IPTU, disponível a partir de 1º de novembro. Fotos e detalhes: https://casa-norte.example/imoveis/CN-2041 > > **Visitante:** dá pra ver essa semana? somos eu e meu namorado > > **Agente:** Claro. O corretor tem quinta às 18:00 ou sábado às 11:00. Antes de agendar: a partir de quando vocês querem se mudar? Por trás dessas respostas, o agente leu o código do imóvel no print, chamou `buscar_imoveis` com ele e depois `horarios_visita`. O link veio da tool, e é isso que permite ao agente enviá-lo. Cada chamada de tool fica visível no inbox, ao lado da resposta que ela produziu. ## Antes de escrever qualquer coisa: cinco perguntas para a imobiliária 1. **Quem escreve, e de onde?** Posts do Instagram, portais de imóveis, o site; mais inquilinos ou mais compradores. 2. **O que faz um lead valer uma visita?** O mínimo que os corretores querem saber antes: orçamento, bairro, data de mudança, forma de pagamento. 3. **O que ele nunca pode dizer?** Se o preço é negociável, se um banco vai financiar, qualquer coisa sobre um contrato. 4. **Quando um corretor assume?** Propostas, contratos, proprietários que querem anunciar, reclamações, qualquer um que peça. 5. **Onde ficam os imóveis e as agendas?** A API do seu CRM ou da sua base de imóveis, as agendas dos corretores, o endereço da página de cada imóvel. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: casa-norte agent: name: Casa Norte Imóveis personality: Simpático e eficiente. Uma ou duas perguntas por vez, nunca insistente. instructions: | Você ajuda as pessoas que querem comprar ou alugar um imóvel com a Casa Norte Imóveis: descobre do que precisam, mostra imóveis compatíveis e agenda visitas com um corretor. Responda primeiro o que perguntaram, depois qualifique. Descubra se querem comprar ou alugar, o orçamento máximo, os bairros que considerariam e quantos quartos precisam. Para quem compra, pergunte se vai usar financiamento bancário ou FGTS, ou pagar à vista; para quem aluga, a partir de quando quer se mudar. Pergunte uma ou duas coisas por vez, e guarde o que disserem com remember. Imóveis: chame buscar_imoveis com o que você sabe e ofereça no máximo três resultados, cada um com o valor, o bairro, os quartos e o link que ela devolveu. Se o visitante mandar um print, procure nele o código do imóvel e busque por esse código. Visitas: chame horarios_visita e ofereça os horários que ela devolver. Antes de chamar agendar_visita, peça um nome e, exceto no WhatsApp, um telefone, e repita a visita para a pessoa. Só diga que a visita está agendada quando agendar_visita a tiver devolvido. Regras que você nunca quebra: - Nunca negocie, aceite uma proposta ou sugira que o preço pode baixar. - Nunca diga se um banco vai aprovar um financiamento ou se o FGTS pode ser usado, nem informe taxas de juros, nem dê orientação jurídica ou tributária. - Nunca passe os contatos de um proprietário, nem um endereço exato que buscar_imoveis não tenha devolvido. - Nunca descreva um bairro por quem mora nele. Descreva o imóvel, o transporte e os serviços. tools: [buscar_imoveis, horarios_visita, agendar_visita, knowledge_lookup, identify_contact, remember] knowledge: [imobiliaria] links: bairro: url: https://casa-norte.example/{operacao}/{bairro} when: O visitante quer ver tudo o que há em um bairro. values: operacao: [comprar, alugar] bairro: [pinheiros, vila-mariana, moema, perdizes] anunciar: url: https://casa-norte.example/anuncie-seu-imovel when: Um proprietário quer vender ou alugar o próprio imóvel. handoff: after_turns: 20 when: - o visitante quer fazer uma proposta ou negociar o preço - perguntas sobre um contrato, uma garantia locatícia ou uma questão jurídica - o visitante pede orientação sobre financiamento ou uso do FGTS - um proprietário quer vender ou alugar o próprio imóvel - uma reclamação sobre um corretor ou uma visita ``` Algumas escolhas que vale a pena explicar: - **Primeiro responda, depois qualifique.** Quem perguntou “valor?” e recebeu quatro perguntas de volta para de responder. As instruções fazem o agente dar o valor e o link, e só depois perguntar, uma ou duas coisas por vez. - **`remember` guarda o que o lead disse.** Orçamento, bairros e forma de pagamento viram notas sobre o contato, e essas notas estão no prompt do agente sempre que esse contato volta a escrever, então um comprador que volta na semana seguinte não precisa repetir o orçamento. O agente nunca decide por conta própria fazer follow-up; quando o seu CRM envia um pela Messages API, essas mesmas notas estão lá. - **Os links de imóveis vêm da tool; as páginas por bairro, de `links`.** Os imóveis mudam todo dia, então as páginas deles vêm de `buscar_imoveis`, e uma URL que uma tool devolveu na conversa é uma que o agente pode enviar. As páginas por bairro são fixas, então `links` as declara e os placeholders se expandem em oito URLs no deploy. Qualquer outra URL em uma resposta é removida. - **Uma transferência espera no inbox.** Dentro do horário de atendimento, que a imobiliária define na página **Negócio** do inbox (por exemplo segunda a sexta das 9:00 às 19:00 e sábado das 10:00 às 16:00), o agente fica em silêncio para um corretor assumir; fora dele continua ajudando e avisa que um corretor vai responder. A Vatio ainda não avisa ninguém sobre uma transferência, então alguém precisa estar com o inbox aberto no horário comercial. `after_turns: 20` é mais alto do que um agente de agendamento precisa, porque qualificar leva alguns turnos. ## Tools: imóveis e visitas Uma tool é uma requisição HTTP ao seu backend, descrita em YAML. Guarde o endereço e a chave como secrets: ```bash vatio secrets set CRM_API https://api.casa-norte.example vatio secrets set CRM_API_KEY sk_live_... ``` `tools/buscar_imoveis.yml`: ```yaml description: Busca imóveis anunciados para venda ou aluguel. when_to_use: O visitante quer ver imóveis, ou pergunta por um pelo código ou por um print. parameters: type: object properties: operacao: { type: string, enum: [comprar, alugar] } bairros: { type: string, description: "separados por vírgula, por exemplo pinheiros,moema" } valor_max: { type: number, description: "preço total para comprar, aluguel mensal para alugar, em reais" } quartos: { type: integer, description: "número mínimo de quartos" } codigo: { type: string, description: "código do imóvel, por exemplo CN-2041" } access: public request: method: GET base_url: "$env.CRM_API" path: /imoveis/busca headers: Authorization: "Bearer $env.CRM_API_KEY" query: operacao: "$params.operacao" bairros: "$params.bairros" valor_max: "$params.valor_max" quartos: "$params.quartos" codigo: "$params.codigo" respond: data: imoveis: "$.imoveis" message: when_empty: Nenhum imóvel anunciado atende a essas condições. default: "Encontrei {{count}} imóveis." ``` O seu endpoint devolve alguns imóveis, cada um com o código, o valor, o bairro, os quartos e a `url`, a página do imóvel no seu site. Os parâmetros que o agente não preencheu ficam fora da requisição. `tools/agendar_visita.yml`: ```yaml description: Agenda uma visita a um imóvel com o corretor responsável. when_to_use: O visitante escolheu um horário de horarios_visita e informou um nome. parameters: type: object properties: horario_id: { type: string } nome: { type: string } telefone: { type: string, description: "Só Instagram e web. No WhatsApp a tool usa o número do contato" } operacao: { type: string, enum: [comprar, alugar] } orcamento: { type: number } pagamento: { type: string, description: "por exemplo financiamento aprovado, financiamento em análise, FGTS, à vista" } required: [horario_id, nome] access: public request: method: POST base_url: "$env.CRM_API" path: /visitas requires: [params.horario_id, params.nome] headers: Authorization: "Bearer $env.CRM_API_KEY" body: horario_id: "$params.horario_id" nome: "$params.nome" telefone: "$params.telefone || $contact.phone_number" operacao: "$params.operacao" orcamento: "$params.orcamento" pagamento: "$params.pagamento" respond: data: visita: "$.visita" ``` A qualificação viaja com o agendamento, então o corretor abre a visita no seu CRM já sabendo o orçamento e como o lead vai pagar. No WhatsApp o número do lead chega com a mensagem dele, então `telefone` usa `$contact.phone_number` e o agente só pede o número no Instagram e no site. `horarios_visita` é um `GET` com o código do imóvel que devolve os próximos horários livres do corretor responsável; qual agenda ele lê é decisão do seu backend. Se alguém pegou o horário nesse meio-tempo, responda `409`: a Vatio transforma qualquer resposta que não seja 2xx em um erro que o agente consegue explicar, então ele oferece outro horário em vez de confirmar um que já não existe. ### O que uma tool pública pode devolver No WhatsApp e no Instagram um contato é anônimo até entrar na conta, então para eles só rodam tools públicas, e estas três são. Para os imóveis tudo bem, porque já são públicos, mas isso define a regra do que os seus endpoints devolvem: o que está na página do imóvel, e nada mais. Nada de dados do proprietário, nem o número do apartamento de um imóvel que você só anuncia por bairro, nem o menor valor que o dono aceitaria. Tudo o que uma tool devolve o modelo pode repetir. `agendar_visita` escreve no seu CRM para visitantes anônimos, então trate essa tool como um formulário de contato: valide o telefone e limite os agendamentos por número. O que pertence a um cliente, como o contrato ou os boletos de um inquilino, precisa de um visitante autenticado e de uma tool marcada `access: private`, que no WhatsApp e no Instagram [leva a pessoa a entrar na conta](https://vatio.ai/docs/authentication/sessions#on-whatsapp) antes; veja [Conectar seu backend](/pt/guias/conectar-seu-backend). ## Conhecimento: o processo, nas suas palavras ```bash vatio kb create imobiliaria vatio kb write imobiliaria alugar alugar.md vatio kb write imobiliaria comprar comprar.md vatio kb write imobiliaria bairros bairros.md vatio kb write imobiliaria taxas taxas.md ``` Uma boa entrada responde a uma pergunta por seção: ```markdown # Alugar com a Casa Norte ## O que você precisa para fazer a proposta RG ou CNH, CPF e comprovante de renda de pelo menos três vezes o valor do aluguel. ## Garantias que aceitamos Fiador com imóvel quitado, seguro-fiança ou título de capitalização. ## Quanto tempo leva Respondemos em até dois dias úteis depois de receber todos os documentos. ``` A Vatio não lê o seu site. Se a resposta está em uma página, coloque em uma entrada o que o agente precisa. Quando as taxas mudam, um supervisor edita a entrada pelo inbox, e cada edição fica guardada como uma versão. ## Instagram: “valor?” e um print O mercado imobiliário vive no Instagram. Um reel de um apartamento traz DMs que dizem “valor?”, “info” ou “ainda está disponível?”, muitas vezes com um print, porque o visitante escreveu a partir do feed e não do post. Duas coisas fazem essas conversas funcionarem: - **Coloque o código do imóvel em todo post**, na imagem e na legenda. O agente lê imagens, então um print com “CN-2041” em um canto vira uma chamada a `buscar_imoveis` pelo código, em vez de um palpite sobre qual dos apartamentos de dois quartos era. - **Responda antes de perguntar.** “Valor?” merece um valor. A qualificação acontece nas mensagens seguintes. O agente não consegue enviar fotos; a página do imóvel tem as fotos, e o que ele envia é o link. Os áudios são transcritos, e a Vatio agrupa uma rajada de mensagens em um só turno antes de responder. No Instagram uma empresa não pode escrever primeiro, então se um lead para de responder ali, o follow-up vai por outro canal; no WhatsApp o seu CRM pode enviá-lo pela [Messages API](https://vatio.ai/docs/api/messages). Quando ele volta a escrever, o agente continua com as notas que guardou. A [documentação do Instagram](https://vatio.ai/docs/channels/instagram) explica como conectar a sua conta profissional. ## Teste antes de qualquer lead ```bash vatio push vatio chat "Oi, procuro um apê de 2 quartos para alugar em Pinheiros, até 4 mil" vatio chat "Dá para ver o primeiro no sábado?" vatio chat --new "Se eu fechar esta semana, vocês baixam 10% do valor?" vatio chat --new "Ganho 9 mil por mês. O banco vai aprovar meu financiamento para o CN-3108?" vatio chat --new "Me passa o telefone do dono do CN-2041?" vatio chat show ``` As três conversas com `--new` são as importantes: uma negociação que ele deve passar para um corretor, uma pergunta sobre financiamento que ele não deve responder e os contatos de um proprietário que ele não deve entregar. `chat show` mostra cada chamada de tool. `agendar_visita` escreve de verdade, então aponte o ambiente em que você testa para um CRM de sandbox, com um secret que valha só para ele. Depois adicione a sua conta do Instagram como conta de teste na página **Testar** do inbox e mande para a conta compartilhada de preview um print de um dos seus posts. ## Melhore toda semana Quando os corretores respondem pelo inbox, eles **marcam** qualquer resposta que saiu errada e escrevem o que deveria ter acontecido: um lead mal qualificado, um imóvel que ele deveria ter oferecido. `vatio flags` transforma essas notas em um documento a partir do qual o seu coding agent consegue corrigir, cada flag vira um caso de eval, e a flag é marcada como resolvida quando live passa nesse caso. Veja [Melhorar seu agente](/pt/guias/melhorar-seu-agente-de-ia). ## Colocar no ar ```bash vatio publish ``` Depois conecte o número de WhatsApp Business da imobiliária e a conta profissional do Instagram na página **Canais** do inbox, e ative a chave **Em produção** do WhatsApp. O Instagram responde assim que a conta é conectada. Os corretores podem continuar usando o app do WhatsApp Business no celular: se alguém responder por ali, assume a conversa, e o agente sai de cena até que ela seja liberada no inbox. Para o seu site, `vatio tokens create --env live --origin https://casa-norte.example` cria o token para o script do widget. Nomes, telefones e finanças dos leads são dados pessoais. A Vatio nunca coloca o conteúdo de uma conversa no email diário: ele só se lê no inbox ou com um token da Vatio; o seu CRM deveria ter o mesmo cuidado. Verificar o que a legislação local exige da publicidade de imóveis e do tratamento dos dados dos leads continua sendo tarefa sua. ## Perguntas frequentes ### Um agente de IA pode qualificar leads de imobiliária no WhatsApp e no Instagram? Sim. O agente pergunta se a pessoa quer comprar ou alugar, o orçamento, o bairro e como vai pagar, e busca nos seus imóveis com uma tool que chama a sua API. Quando agenda uma visita, essas respostas vão junto para o seu CRM, então o corretor já começa com um lead qualificado. ### O agente consegue enviar fotos de um imóvel? Não. As respostas são só texto, então o agente envia o link da página do imóvel, onde estão as fotos. Ele lê as fotos e os prints que os visitantes mandam, e é assim que encontra o imóvel de que alguém fala a partir do print de um post. ### O agente vai negociar o preço ou orientar sobre financiamento? Não se você escrever a regra, e você deveria. Coloque negociação, propostas, orientação sobre financiamento e contratos como coisas que ele nunca faz, e inclua esses casos em handoff.when para que um corretor assuma a conversa. ### O agente faz follow-up com leads que pararam de responder? No WhatsApp, quando o seu CRM pede. O seu CRM ou backend chama a Messages API da Vatio para aquele lead, com um modelo aprovado se já se passaram 24 horas, e o agente continua com as notas que guardou sobre o orçamento e os bairros dele. O agente nunca decide por conta própria fazer follow-up, e no Instagram uma empresa não pode escrever primeiro. ### Como um corretor fica sabendo que um lead precisa dele? Uma transferência deixa a conversa esperando no inbox da Vatio. A Vatio ainda não avisa ninguém, então alguém precisa acompanhar o inbox no horário comercial. Uma visita agendada pela sua API chega onde o seu backend a colocar, como o seu CRM.