O Laravel AI SDK chegou à versão 1.0 com uma proposta maior do que esconder chamadas HTTP para provedores de modelos. O pacote oficial reúne geração de texto e mídia, embeddings, conversas persistidas, streaming, agentes, ferramentas e testes dentro das convenções do framework.
A vantagem prometida é trocar de provedor ou combinar capacidades sem espalhar SDKs diferentes pela aplicação. A versão estável também fecha decisões de armazenamento e execução que estavam mais fáceis de mudar durante o beta. Para quem já adotou o pacote, isso significa que o lançamento merece uma leitura de guia de upgrade, não apenas um composer update no fim da tarde.
Uma camada Laravel sobre vários provedores
O SDK oferece uma interface comum para serviços como OpenAI, Anthropic, Gemini e outros provedores suportados. O objetivo não é fingir que todos os modelos são idênticos. Recursos específicos ainda dependem do fornecedor, mas a aplicação ganha um lugar consistente para definir agentes, instruções, ferramentas, respostas estruturadas, filas e testes.
A instalação segue o fluxo esperado de um pacote Laravel:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrateAs migrations criam as tabelas usadas pelo armazenamento de conversas. Isso já indica uma escolha importante: uma conversa não é apenas uma sequência descartável de prompts. Ela pode fazer parte do estado da aplicação, precisa de autorização e deve continuar coerente quando um agente chama ferramentas em várias etapas.
Aprovação humana entrou no fluxo das ferramentas
Ferramentas são a ponte entre o modelo e ações reais. Ler um catálogo público e apagar um arquivo não deveriam compartilhar a mesma política. Na versão 1.0, uma ferramenta pode implementar o contrato Approvable e pausar a execução até que uma pessoa aprove, rejeite ou até altere os argumentos escolhidos pelo modelo.
O recurso funciona com respostas diretas, streaming, filas e broadcast. Também conversa com os protocolos Vercel AI SDK e AG-UI, que conseguem representar pedidos de aprovação no frontend. Isso evita criar um protocolo particular apenas para mostrar “o agente quer executar esta ação” e depois continuar a conversa.
A aprovação, porém, não substitui autorização. Ao retomar uma execução, a aplicação ainda precisa verificar se o usuário pode acessar aquela conversa e realizar a ação solicitada. Um botão de confirmar no frontend não resolve acesso indevido a uma conversa de outro usuário.
Middleware agora acompanha cada etapa do agente
No beta, o middleware era executado uma vez por prompt. Agora ele envolve cada etapa de geração. Se o agente consultar três ferramentas antes de responder, o middleware participa das três passagens. Essa granularidade permite cortar uma ferramenta cara depois do primeiro uso, trocar de modelo, resumir histórico, limitar contexto ou devolver uma resposta em cache durante o loop.
É um detalhe de arquitetura mais importante do que parece. Custo, políticas e observabilidade precisam acompanhar o que o agente realmente faz, e não apenas a requisição inicial. Ao mesmo tempo, middleware executado várias vezes pede código idempotente e métricas que não contem um único prompt como várias conversas independentes.
Nem toda ferramenta precisa viajar em todo prompt
Descrever dezenas de ferramentas em cada chamada consome tokens e aumenta o espaço de decisão do modelo. O novo ToolSearch permite agrupar ferramentas menos frequentes e carregá-las quando forem necessárias. No lançamento, esse mecanismo está disponível com OpenAI e Anthropic.
O SDK também inclui execução de código no sandbox do próprio provedor para tarefas como cálculo e análise de dados. O suporte anunciado abrange Anthropic, OpenAI, Azure, Gemini e xAI. Como o código roda fora da aplicação Laravel, continuam valendo os limites, custos e políticas do provedor escolhido.
Conversas mudaram por dentro
A mudança mais sensível para projetos existentes está no armazenamento das conversas. Chamadas e resultados de ferramentas antes ficavam em listas separadas, o que perdia a relação exata entre cada rodada. Na versão 1.0, cada mensagem registra uma coluna JSON de steps, mantendo o resultado junto da chamada que o produziu.
Aplicações que consultavam diretamente as colunas antigas precisarão migrar. O guia oficial inclui um backfill para os registros existentes. Também há mudanças incompatíveis em middleware, nomes das métricas de uso e protocolos de streaming. A recomendação razoável é testar a atualização com uma cópia dos dados e percorrer conversas que contenham ferramentas, aprovações e respostas interrompidas.
Onde a abstração ajuda e onde ela não pode esconder diferenças
Uma API unificada reduz código repetido, facilita testes com fakes e evita que cada feature invente seu próprio cliente de IA. Ela também cria uma camada que precisa evoluir no ritmo de vários fornecedores. Tool search, classificação, execução de código e formatos de streaming não têm disponibilidade idêntica em todos eles.
Por isso, vale tratar portabilidade como benefício gradual, não como promessa de troca instantânea. Um agente simples de texto pode mudar de provedor com pouca fricção; outro que depende de sandbox, aprovações e ferramentas nativas provavelmente exige testes específicos. O SDK organiza essa diferença, mas não faz com que ela desapareça.
A versão 1.0 torna o pacote uma opção séria para colocar recursos de IA dentro de uma aplicação Laravel sem montar a infraestrutura básica do zero. O melhor ganho não está em escrever um chat em cinco minutos, e sim em ter conversas, ferramentas, filas, políticas e testes no mesmo modelo mental usado pelo restante do projeto.