Em destaque: Como criar um aplicativo Laravel sem conhecer o Laravel

Neste tutorial, você aprenderá a criar um serviço de concierge de viagens no WhatsApp por meio de um agente de IA, utilizando Laravel, OpenAI e a Messages API do Vonage.

WhatsApp chat interface showing the Vonage-powered travel concierge ready to receive and respond to user messages.

Introdução

Resumo: Pule esta parte e veja o código funcional no GitHub.

Há alguns meses, Jim Seconde me perguntou se eu gostaria de escrever algum conteúdo sobre PHP. O Jim já é uma celebridade do PHP há anos, tendo se dedicado a praticamente tudo que se pode imaginar sobre a linguagem. Mas e eu? Não mexo em PHP há provavelmente 12 anos.

Jim disse: “Não se preocupe. Tem uma novidade legal chamada Laravel Boost. É um servidor MCP específico para o Laravel, que ajuda a criar aplicativos com o Laravel. Não precisa de elefantes. Talvez você queira dar uma experimentada.”

Isso acabou se transformando em um pequeno experimento com uma restrição bem clara: será que eu conseguiria desenvolver um aplicativo Laravel não trivial em uma pilha de tecnologias que eu mal conhecia, usando um agente de programação baseado em IA como principal ferramenta de implementação?

Eu me propus um desafio deliberadamente difícil: criar um concierge de viagens no WhatsApp usando Laravel e PHP. O aplicativo não poderia se limitar a apenas exibir o texto recebido. Ele precisava receber mensagens do WhatsApp por meio da Messages API da Vonage, usar o OpenAI para gerar respostas, escolher o tipo correto de mensagem do WhatsApp para a resposta, oferecer suporte a elementos interativos como botões e listas e manter memória de conversa suficiente para parecer um assistente, em vez de um bot sem estado.

Isso fez com que fosse um caso de teste útil. Não se tratava de um aplicativo CRUD simples, nem de um tutorial de framework que eu pudesse simplesmente fingir que dominava. Envolvia webhooks, tarefas em segundo plano, autenticação de API, restrições de plataformas externas e formatos estruturados de mensagens.

Este artigo não é um tutorial passo a passo sobre o Laravel. Trata-se de um relato sobre como foi, na prática, desenvolver um aplicativo real dessa maneira: quais instruções foram úteis, quais etapas ajudaram a manter o trabalho sob controle, em que pontos o agente foi útil, em que pontos ele falhou e como a documentação baseada no MCP mudou o resultado quando as coisas ficaram difíceis.

O projeto todo levou cerca de oito horas, distribuídas ao longo de dois dias. No final, eu tinha uma demonstração funcional do Laravel WhatsApp. Mais importante ainda, eu tinha uma ideia muito mais clara do que o desenvolvimento com agentic realmente faz de melhor.

Pré-requisitos

• PHP

• PHP Composer

• Agente compatível com o Laravel Boost (por exemplo, GitHub CoPilot)

• Laravel Boost

• Account da API da OpenAI ou outro LLM

• ngrok

• Uma conta verificada WhatsApp Business Account (WABA)

• Account da API da Vonage

• Um número virtual da Vonage

Configurando o aplicativo da Vonage

Você precisará habilitar os recursos do Messages. Para o Messages, será necessário habilitar os webhooks. Por enquanto, basta adicionar placeholders. Mais tarde, quando o aplicativo local estiver em execução via ngrok, atualize o webhook de entrada para que aponte para o endpoint do Laravel.

1. Defina a URL de entrada como https://placeholder.com/inbound.

2. Defina a URL de status como https://placeholder.com/status.

Em seguida, vincule seu WhatsApp Business (WABA) clicando na aba “Vincular contas externas”:

Vonage dashboard showing a WhatsApp Business Account linked to an application in the “Link external accounts” section.Certifique-se de anotar o seguinte:

• ID do aplicativo

• Chave privada (baixada como um arquivo .key )

• Chave/segredo da API

Vamos precisar disso mais tarde para nosso aplicativo Laravel.

Configurando o agente

Em um tutorial normal, precisamos apenas configurar nosso aplicativo. Mas, em um tutorial sobre agentes como este, também precisamos configurar nosso agente.

Usei um arquivo de instruções simples do tipo “planejar primeiro” (copiado de Alex Finn):

1. Leia o código-fonte e analise bem o problema.

2. Elabore um plano para todo.md.

3. Aguarde a aprovação antes de iniciar a implementação.

4. Conclua as tarefas uma a uma.

5. Explique as mudanças de forma geral.

6. Mantenha as mudanças simples e mínimas.

Além disso, incentivei explicitamente o agente a utilizar duas ferramentas baseadas em MCP:

• O Laravel Boost MCP , para geração de esqueletos e convenções compatíveis com o framework

• A documentação da Vonage sobre o servidor MCP, para verificar a correção da API e obter detalhes sobre o formato das mensagens

Essa é uma das primeiras lições claras do projeto: a engenharia de prompts é, na verdade, engenharia de fluxo de trabalho, e as ferramentas do MCP são o que transformam esse fluxo de trabalho em algo confiável.

Primeiro, crie o arquivo Markdown onde suas regras ficarão:

touch ./github/instructions/workflow.instructions.md

Em seguida, adicione as instruções de acordo com a sintaxe das instruções do Copilot:

4 etapas para desenvolver o aplicativo

Quando comecei, não tinha ideia de quanto tempo isso levaria nem do que estaria envolvido. Mas, cada vez que o agente concluía uma lista de tarefas, eu renomeava o arquivo e o salvava. Assim, eu podia enviar as tarefas concluídas, juntamente com o escopo original do projeto, para o agente, e ele criava o próximo conjunto de metas.

Em vez de sobrecarregar o agente com instruções extensas, concentrei-me em pequenas etapas com resultados claros.

1. Crie o aplicativo básico do Laravel e a integração com o WhatsApp

2. Adicionar respostas do WhatsApp do aplicativo ao usuário

3. Adicionar histórico de conversas para obter respostas melhores da OpenAI

4. Adicionar tipos de mensagens inteligentes (botões, listas)

Vou resumir o que aconteceu em cada fase e destacar as sugestões mais interessantes.

Fase 1: Deixe o agente planejar o aplicativo

Veja: initial_todo.md para tarefas do agente.

A primeira orientação foi propositalmente de alto nível. Descrevi o aplicativo de demonstração, a integração com o WhatsApp e a exigência de usar a OpenAI tanto para decisões sobre o conteúdo quanto sobre o tipo de mensagem.

Initial prompt used to define the travel concierge app and guide the agent to generate a structured development plan using Laravel Boost and Vonage docs.

Foi aí que o Laravel Boost MCP fez uma diferença notável.

Em vez de gerar uma estrutura genérica em PHP, o agente adotou imediatamente as convenções do Laravel. Ele sugeriu rotas, controladores, tarefas em fila e classes de serviço de uma forma que se alinhava à maneira como os aplicativos Laravel costumam ser organizados. Ele também propôs um plano de trabalho em fases todo.md sem que isso lhe fosse explicitamente solicitado.

O agente estava utilizando o conhecimento da estrutura disponibilizado pelo MCP para definir a arquitetura. Ele criou uma rota de webhook, um controlador para validação, tarefas em fila para processamento e envio de mensagens, além de classes de serviço para o OpenAI e o Vonage.

Se eu estivesse trabalhando sem experiência com o Laravel, teria levado muito mais tempo para montar tudo manualmente. Portanto, a primeira lição é clara: quando o desenvolvedor tem acesso a ferramentas MCP compatíveis com o framework, elas se mostram muito eficazes na criação de uma estrutura inicial do zero.

AI-generated development plan outlining the Laravel WhatsApp app architecture, including webhooks, queue jobs, services, and OpenAI integration.

O primeiro fracasso: um código que parecia correto, mas não fazia nada

A fase de estruturação correu surpreendentemente bem. O agente havia criado uma aplicação completa no estilo Laravel: rotas, controladores, tarefas, serviços e até mesmo um arquivo de teste. Com o Laravel Boost MCP orientando a estrutura, ela já parecia um aplicativo de verdade muito antes do que eu esperava.

Os primeiros problemas surgiram quando executei os testes que eu havia obrigado o agente a escrever.

Um deles falhou imediatamente:

The expected [App\Jobs\ProcessIncomingMessage] job was not dispatched.

Isso parecia mais fácil de consertar do que realmente era.

O agente não rastreou a origem da falha até o controlador. Ele se limitou a especulações superficiais sobre a configuração e o ambiente de teste, embora o erro fosse consistente: o webhook retornava uma resposta, mas a tarefa nunca era despachada.

Depois de analisar lado a lado o teste e o controlador, finalmente descobriu o problema. O controlador validava a solicitação e retornava uma resposta, mas nunca acionava o restante do sistema. A correção consistiu em uma única linha:

ProcessIncomingMessage::dispatch($data['to'], $data['from'], $data['message']);

Depois disso, o teste foi aprovado. Até aquele momento, o agente havia sido muito eficaz na estruturação do código. Ele gerou um código que parecia correto e seguia as convenções do framework. Mas não garantia de forma confiável que o sistema funcionasse de ponta a ponta.

Ao incorporar os testes ao fluxo de trabalho, acabei criando uma versão simplificada do TDD. O teste definia o comportamento, e o agente precisava iterar até que a implementação correspondesse a ele. Não era um ciclo perfeito, mas me deu um parâmetro estável para me orientar.

O agente cuidou do trabalho repetitivo, enquanto eu me concentrei em fazer com que ele se alinhasse ao comportamento esperado. Essa é uma maneira ideal de pensar na divisão de tarefas entre agentes e seres humanos.

Não porque o agente fosse perfeito, mas porque tornava algo como o TDD mais fácil de manter do que normalmente é quando feito manualmente.

Nesse momento, consegui enviar uma mensagem para o aplicativo e vi ela ser registrada no terminal:

[2026-03-09 17:15:00] local.INFO: WhatsApp webhook received {
  "from":"1***2364506",
  "to":"1***3508504", 
  "message_type":"text",
  "text_body":"Let’s test the Vonage WhatsAppp Service"
}

Fase 2: O aplicativo começa a responder

Veja: second_todo.md para tarefas do agente.

A estrutura básica já estava pronta, mas havia um problema. Eu não estava recebendo respostas do aplicativo. O fluxo deveria ter sido o seguinte: o usuário envia uma mensagem pelo WhatsApp, ela chega ao webhook, passa pelo Laravel, recebe uma resposta da OpenAI e, em seguida, é reenviada pelo Vonage.

Parecia que tudo isso existia. O agente havia estruturado as tarefas, os serviços e as integrações. As mensagens estavam chegando ao aplicativo e, aparentemente, nada estava com defeito. Mas ainda assim não estava funcionando de ponta a ponta.

Falha real em tempo de execução na última etapa

Na primeira vez em que o sistema foi executado do início ao fim, ele falhou em uma etapa avançada do pipeline, apresentando um erro de tempo de execução:

Sending message via Vonage {"to":"unknown","type":"text"}
Undefined array key "to"

Esse é um tipo específico de falha que só aparece depois que o sistema já está praticamente todo conectado. Como o agente vinha montando todas as partes isoladamente, tudo parecia estar correto. E, nas etapas anteriores, tudo estava funcionando: o webhook recebeu a mensagem, a tarefa foi despachada e a OpenAI gerou uma resposta.

A falha só apareceu ao tentar enviar a resposta. Ao analisar os registros, percebeu-se que o problema era sutil:

{
 "to": unknown,
 "type": "text"
}

O sistema estava tentando enviar uma mensagem sem um destinatário real. Em algum momento, esse valor foi perdido e substituído por “desconhecido”. Isso ocorreu porque, isoladamente, o agente fazia tudo parecer certo, mas perdia de vista o panorama geral e como tudo se conectava.

O Copilot ficava corrigindo a camada errada

Esse foi o primeiro ponto em que o agente começou a ter dificuldades. Ele não ignorou o erro. Continuou propondo soluções. Mas, mais uma vez, suas propostas ficaram superficiais: ajustar as instruções, refinar a forma como a resposta da OpenAI era analisada, alterar os formatos das respostas

Todas eram ideias razoáveis, mas nenhuma abordava a falha em si. O problema não era como a resposta era gerada, e sim como os dados circulavam pelo sistema.

Três coisas estavam acontecendo ao mesmo tempo: o modelo podia definir campos como até, valores nulos circulavam por várias camadas e nada verificava se os campos obrigatórios estavam preenchidos antes do envio. Essa combinação fazia com que o sistema só apresentasse falha no momento final, quando a Vonage tentava usar os dados.

Mesmo após algumas iterações, o agente não conseguiu convergir para isso. Ele continuou produzindo soluções plausíveis que não alteravam o resultado.

A troca de agentes mudou a abordagem

Naquele momento, mudei do CoPilot para o o GPT-5 Mini para o meu IDE favorito, o Windsurf com Claude Sonnet, e forneci a ele os logs completos, em vez de apenas o erro. A diferença não foi que ele escreveu um código melhor. Ele abordou o problema de maneira diferente. Em vez de se concentrar na linha com erro, ele rastreou todo o caminho da mensagem:

webhook → OpenAI → tarefa → Vonage

Em seguida, foram adicionadas verificações em cada etapa: validando as entradas logo no início, exigindo o preenchimento dos campos obrigatórios antes do envio e registrando o estado intermediário.

A mudança importante foi o local onde a validação ocorria. Até então, o sistema presumia que tudo estava válido e só apresentava erros em um estágio avançado. Após essa etapa, passou a apresentar erros logo no início, em pontos previsíveis. Assim que essas verificações foram implementadas, o problema “para”: “desconhecido” desapareceu.

Claude analyzing the error across the full message pipeline and applying validation at multiple layers instead of patching a single failure point.

O agente tentou reinventar a roda

Com o fluxo de dados corrigido, o sistema seguiu em frente e imediatamente se deparou com o próximo problema. As mensagens de saída continuavam falhando, desta vez com 401 Não autorizado. A resposta do agente nesse caso foi interessante. Em vez de usar as ferramentas existentes, ele começou a reconstruir a camada de autenticação do zero:

• gerar JWTs manualmente

• usando a função openssl_sign()

• criação manual de tokens

• envio de solicitações HTTP brutas

À primeira vista, o código parecia razoável para a IA. Mas ele nunca funcionou de maneira confiável. Esse é um tipo diferente de falha. Nesse caso, a IA estava tentando adivinhar como funcionava a autenticação da Vonage, em vez de seguir as convenções do SDK.

O ponto de virada: exigindo a apresentação de documentação por meio do MCP

A solução surgiu a partir de uma sugestão muito direta:

Por que você não usou a ferramenta de documentação da Vonage para gerar um JWT por meio do SDK? Estamos sempre tendo problemas ao tentar criá-los manualmente.

Em vez de continuar improvisando, o agente consultou a documentação da Vonage sobre a ferramenta MCP e mudou de abordagem. Ele utilizou o SDK PHP da Vonagee deixou que o SDK cuidasse diretamente da geração do JWT.

Isso resolveu o problema por completo.

Prompt that forced the agent to stop generating JWTs manually and use the Vonage documentation MCP tool and official SDK.

Fase 3: Adicionando a memória de conversação

Veja: third_todo.md para tarefas do agente.

Uhuuu! Nesse ponto, eu já tinha um chatbot básico no WhatsApp funcionando. Mas ele parecia muito simplório. Cada mensagem era tratada isoladamente. O assistente respondia corretamente, mas não tinha memória do que tinha acontecido antes.

O objetivo aqui era simples: armazenar o histórico da conversa, incluir as mensagens recentes no prompt da OpenAI e fazer isso de uma maneira simples o suficiente para não introduzir nova complexidade.

Em comparação com a Fase 2, isso pareceu uma simples extensão.

Uma primeira passagem tranquila

O agente implementou a memória de conversas usando um banco de dados SQLite sem grandes dificuldades.

O agente criou uma modelo de e uma tabela, começou a armazenar as mensagens recebidas na tarefa existente e passou as mensagens recentes para o prompt do OpenAI. Como o restante do aplicativo já estava estruturado de maneira bastante padrão para o Laravel, isso se encaixou naturalmente. Não houve muitas idas e vindas nem depuração.

Esse é um dos casos em que a estrutura inicial valeu a pena. Quando a estrutura do aplicativo está bem definida, os desenvolvedores costumam ser bastante eficientes em ampliá-la de maneiras previsíveis.

“Trabalhar” não estava, na verdade, funcionando

Após a implementação inicial, o recurso parecia funcionar. O aplicativo respondia às mensagens. Ele fazia referência ao contexto anterior. Dava a impressão de que a memória estava funcionando corretamente.

Mas um rápido teste na prática revelou o problema: o assistente, na verdade, não se lembrava da conversa corretamente. O sistema não estava falhando abertamente. Estava se comportando de maneira inconsistente. Esse era um tipo de bug diferente dos encontrados nas fases anteriores.

Example of inconsistent conversation memory: the assistant initially references prior context (user name), but fails to connect follow-up messages about Tel Aviv and May.

O Bug Sutil: Memória Incompleta

Quando o agente verificou o que realmente estava sendo armazenado, o problema ficou claro. Apenas as mensagens dos usuários estavam sendo salvas. As respostas do assistente, não.

Então, o histórico da conversa enviado à OpenAI era o seguinte:

User: I want to plan a trip to Tel Aviv 
User: Can you help me plan this trip in May?

Do ponto de vista do modelo, não houve conversa. Não há registro de como o assistente respondeu, então ele não tem nada em que se basear. Imagine tentar ter uma conversa, mas ouvir apenas metade do que é dito!

Em vez de tratar tudo como um único fluxo de mensagens, o sistema precisava acompanhar ambos os lados explicitamente. O agente atualizou a estrutura para armazenar tanto as entradas do usuário quanto as respostas do assistente, reconstruir a conversa como turnos alternados e, em seguida, enviar os últimos turnos para a OpenAI.

Assim que isso foi implementado, o comportamento passou a corresponder às expectativas. As perguntas de acompanhamento começaram a fazer sentido, pois o modelo conseguia realmente acessar a conversa anterior.

Mais um ponto de falha: testes e migrações

Essa também foi a primeira vez que a persistência começou a afetar o conjunto de testes. Tudo funcionava localmente, mas os testes começaram imediatamente a falhar com a mensagem:

SQLSTATE[HY000]: no such table: conversations

Isso não foi um problema do aplicativo. O banco de dados de teste simplesmente não tinha a nova tabela. As migrações não estavam sendo executadas como parte da configuração de teste. Um desenvolvedor Laravel saberia como resolver: use RefreshDatabase para que as migrações sejam executadas nos testes e atualizar os payloads de teste para incluir quaisquer campos obrigatórios, como de.

Depois que isso foi implementado, os testes foram aprovados novamente.

Fase 4: Mensagens estruturadas (o MCP passa a ser obrigatório)

Veja: fourth_todo.md para tarefas do agente.

Nessa altura, o aplicativo já conseguia enviar e receber mensagens de forma confiável. Mas apenas mensagens de texto. O passo final foi aproveitar todo o potencial do WhatsApp e criar algo legal adicionando:

• botões de resposta

• listas interativas

Parecia uma pequena extensão, mas acabou se tornando a parte do projeto que exigiu mais trabalho de integração.

Carga útil plausível rejeitada pelo WhatsApp

A primeira tentativa parecia estar dando certo. A OpenAI estava retornando respostas estruturadas como:

{
 "type": "list",
 "content": {
   "items": [...]
 }
}

Do lado do Laravel, tudo parecia estar correto: 1) a resposta da OpenAI foi recebida no formato esperado, 2) a tarefa foi executada e 3) o serviço da Vonage foi chamado.

Mas a etapa final falhou com a mensagem:

Invalid params: The value of one or more parameters is invalid.

Ou, às vezes, o que era ainda mais confuso, simplesmente não aparecia nada no WhatsApp. Do ponto de vista do Laravel, tudo funcionava. A API discordava.

Laravel logs showing a WhatsApp list message flowing through OpenAI and Vonage correctly, but failing at the final step with an “Invalid params” error due to a malformed interactive payload.O agente reagiu da mesma forma que nas fases anteriores. Ele tentou reformular a carga útil, ajustar formatos e até mesmo recorrer ao texto simples, apenas para conseguir enviar alguma coisa. Isso funcionou tecnicamente, mas não resolveu o verdadeiro problema.

As mensagens interativas do WhatsApp não são apenas texto estruturado. Elas devem seguir esquemas rígidos, e pequenos desvios as tornam inválidas. O agente não possuía um modelo confiável dessas restrições, por isso continuava gerando mensagens que pareciam razoáveis, mas não eram aceitas.

Discrepância entre o SDK e a realidade

Após algumas iterações, surgiu um erro diferente:

Argument #1 ($message) must be of type BaseMessage, array given

O SDK da Vonage espera objetos de mensagem tipados, enquanto as mensagens interativas exigem JSON profundamente aninhado. O agente passou matrizes que correspondiam à estrutura da carga útil, mas o SDK as rejeitou.

Naquele momento, a questão não era apenas a carga útil; era também a camada pela qual estávamos tentando enviá-la.

Segunda rodada: Exigindo documentação por meio do MCP

Foi aí que a ferramenta MCP da documentação da Vonage voltou a ser fundamental.

Em vez de continuar reformulando as cargas úteis, incentivei o agente a examinar os esquemas reais das mensagens do WhatsApp e partir daí.

A abordagem mudou bem rápido:

• utilize o SDK onde for útil (autenticação, cliente básico)

• enviar mensagens interativas por meio de HTTP bruto

• criar cargas úteis que correspondam exatamente à estrutura documentada

Assim que o agente teve o esquema à sua frente, ele conseguiu realizar a tarefa.

Using the Vonage documentation MCP tool to confirm the correct SDK-based approach before refactoring the integration.

Conclusão

Dois dias antes disso, eu não teria escolhido o Laravel para nada além de um tutorial. No final, eu tinha um concierge de viagens no WhatsApp em funcionamento, com o OpenAI, memória de conversas e mensagens estruturadas. Mas mais importante do que o aplicativo foi entender como essa forma de desenvolvimento realmente funciona.

O agente foi útil, mas não autônomo. Ele lidou bem com a criação de estruturas e extensões, especialmente depois que a estrutura já estava pronta. Onde ele teve dificuldades foi nos limites (fluxo de dados, autenticação, APIs rígidas), onde “quase correto” não é suficiente.

O que fez a diferença foi o fluxo de trabalho. Dividir o trabalho em fases, realizar testes desde o início e usar ferramentas MCP para vincular o agente à documentação real me permitiu fazer com que recursos complexos funcionassem rapidamente. Sem isso, o agente tendia a adivinhar. Com o fluxo de trabalho certo, consegui criar um aplicativo cuja sintaxe não consigo explicar.

Próximos passos

A partir daqui, há muito espaço para ampliar o aplicativo. Você poderia adicionar novos tipos de mensagens no WhatsApp, como mensagens de localização para mostrar aos usuários exatamente onde ficam os locais em seu itinerário, ou usar mensagens com arquivos para gerar e enviar uma versão em PDF de um plano de viagem. Esse tipo de adição leva a integração ainda mais longe e destaca onde APIs estruturadas e um fluxo de dados claro realmente fazem a diferença.

A lição é bem simples: você pode se familiarizar com pilhas de tecnologia desconhecidas muito mais rapidamente com um agente, mas somente se mantiver o controle sobre a estrutura e os limites. Se quiser explorar o projeto na íntegra, incluindo o fluxo de trabalho em fases, o código completo está disponível no repositório do GitHub.