Bem-vindo ao Blog da DMarkInfo

Conteúdos e novidades sobre Tecnologia da Informação.

Como criar um Agente de IA com Laravel

Postado por Eduardo Marques em 14/11/2025
Como criar um Agente de IA com Laravel

Nos últimos anos, agentes de IA deixaram de ser experimentos acadêmicos e se tornaram ferramentas reais para automação, suporte, análise e operação de sistemas. Mas uma pergunta sempre aparece:

É possível criar um agente de IA usando Laravel?

Sim — não apenas é possível, como é extremamente eficiente.

Neste artigo, vou mostrar passo a passo como construir um Agente Inteligente totalmente funcional com Laravel, usando modelos de linguagem (LLMs) como GPT, Groq ou DeepSeek. Vou mostrar a arquitetura, os arquivos necessários, o fluxo de decisão e exemplos práticos.

 

O que é um agente de IA?

Um agente é mais do que um chatbot.

Um agente:

  • entende a intenção do usuário

  • decide o que deve fazer

  • executa ações reais no sistema

  • mantém contexto

  • interage com APIs, banco de dados e serviços internos

Ele é, essencialmente, um funcionário digital capaz de tomar decisões.

 

Arquitetura do agente em Laravel

Organizei o projeto assim:

app/
  Agents/
    Core/
      Agent.php
    Actions/
      BuscarCliente.php
      CriarPedido.php
      EnviarEmail.php
  Services/
    OpenAIService.php
routes/
  api.php
 

Com isso, temos:

  • Core → cérebro do agente

  • Actions → ações que ele pode executar

  • Services → integração com modelos de IA

 

1. Criando o serviço que conversa com o LLM

Esse service será responsável por enviar mensagens ao modelo:

<?php
namespace App\Services;
use GuzzleHttp\Client;
class OpenAIService {
    private $client;
    private $apiKey;
    public function __construct() {
        $this->client = new Client(['base_uri' => 'https://api.openai.com/v1/']);
        $this->apiKey = env('OPENAI_API_KEY');
    }
    public function chat($messages) {
        $response = $this->client->post('chat/completions', [
            'headers' => [
                'Authorization' => 'Bearer ' . $this->apiKey,
                'Content-Type'  => 'application/json'
            ],
            'json' => [
                'model' => 'gpt-4o-mini',
                'messages' => $messages
            ]
        ]);
        return json_decode($response->getBody(), true);
    }
}
 

 

2. Criando o cérebro do agente (Agent.php)

O agente recebe mensagens, envia ao LLM e interpreta a resposta.
Se a resposta for JSON contendo uma “ação”, ele executa.

<?php
namespace App\Agents\Core;
use App\Services\OpenAIService;
class Agent {
    private $llm;
    private $actions = [];
    public function __construct() {
        $this->llm = new OpenAIService();
    }
    public function registerAction($name, $callable) {
        $this->actions[$name] = $callable;
    }
    public function ask($input) {
        $messages = [
            [
                "role" => "system",
                "content" => "Você é um agente inteligente. Sempre use JSON quando quiser executar uma ação."
            ],
            [
                "role" => "user",
                "content" => $input
            ]
        ];
        $response = $this->llm->chat($messages);
        $content = $response['choices'][0]['message']['content'];
        // Se for JSON, executa ação
        $decoded = json_decode($content, true);
        if (json_last_error() === JSON_ERROR_NONE && isset($decoded['action'])) {
            $action = $decoded['action'];
            if (isset($this->actions[$action])) {
                return ($this->actions[$action])($decoded['params'] ?? []);
            }
        }
        return $content;
    }
}
 

 

3. Criando ações que o agente pode executar

Exemplo de registro de ações:

$agent->registerAction('buscar_cliente', function($params) {
    return \App\Models\User::where('email', $params['email'])->first();
});
$agent->registerAction('criar_pedido', function($params) {
    return \App\Models\Pedido::create([
        'cliente_id' => $params['cliente_id'],
        'valor' => $params['valor']
    ]);
});
$agent->registerAction('enviar_email', function($params) {
    \Mail::to($params['para'])->send(new \App\Mail\Notificacao($params['mensagem']));
    return "Email enviado.";
});
 

 

4. Criando a rota API para usar o agente

Arquivo: routes/api.php

use App\Agents\Core\Agent;
use Illuminate\Http\Request;
Route::post('/agente', function(Request $request) {
    $input = $request->input('mensagem');
    $agent = new Agent();
    // exemplo de ação registrada
    $agent->registerAction('buscar_cliente', function($params) {
        return \App\Models\User::where('email', $params['email'])->first();
    });
    return $agent->ask($input);
});
 

Agora você pode enviar:

POST /api/agente
mensagem: "Busque o cliente joao@example.com"
 

 

5. Criando memória para o agente

Migration

Schema::create('agent_memories', function (Blueprint $table) {
    $table->id();
    $table->string('session');
    $table->text('content');
    $table->timestamps();
});
 

Métodos no Agent.php

public function saveMemory($session, $content) {
    \App\Models\AgentMemory::create([
        'session' => $session,
        'content' => $content
    ]);
}
public function loadMemory($session) {
    return \App\Models\AgentMemory::where('session', $session)
        ->get()
        ->pluck('content')
        ->toArray();
}
 

 

Exemplo real de funcionamento

Usuário:
Crie um pedido para o cliente joao@example.com no valor de 249.90

LLM responde:

{
  "action": "criar_pedido",
  "params": {
    "cliente_id": 12,
    "valor": 249.90
  }
}

O agente executa a ação criar_pedido e retorna o registro criado.

 

Possíveis evoluções

Você pode adicionar:

  • múltiplas ferramentas (como nos Assistants da OpenAI)

  • agentes especializados (financeiro, suporte, CRM…)

  • memória vetorial para long-term context

  • raciocínio em múltiplos passos

  • logs de raciocínio e decisões

  • agentes que conversam entre si

 

Construir um agente de IA dentro do Laravel não é apenas uma experimentação interessante — é um divisor de águas na maneira como projetamos sistemas modernos.
Quando o Laravel, com toda sua robustez em regras de negócio, segurança e organização, se une a um modelo de linguagem capaz de interpretar intenções e tomar decisões, nasce uma plataforma realmente inteligente.

Com uma arquitetura clara, baseada em ações, memória e integração com LLMs, abrimos espaço para que o backend deixe de ser apenas um executor passivo e se torne um agente ativo, capaz de:

  • automatizar fluxos complexos,

  • interagir com APIs e bancos de dados,

  • operar de maneira autônoma,

  • aprender com o contexto,

  • e escalar funcionalidades sem aumentar a complexidade do código.

 

Depois de construir meu primeiro agente em Laravel, ficou evidente para mim que esse é um caminho sem volta. A próxima geração de aplicações não será apenas “API + frontend”: serão sistemas que pensam, decidem e agem de acordo com objetivos definidos.

E a melhor parte?
Tudo isso pode ser feito com o Laravel que você já domina.

Este é apenas o começo. O que você fará com isso agora depende de onde deseja levar o seu projeto — e até onde está disposto a deixar sua aplicação evoluir junto com a IA.

Compartilhe este post:
Voltar para a Home