INTRODUCCIÓN A LARAVEL AI SDK: LA FORMA OFICIAL DE INTEGRAR IA EN LARAVEL

Laravel AI SDK es el paquete oficial de Laravel ("laravel/ai") que permite integrar fácilmente Inteligencia Artificial con: OpenAI, Gemini, Claude, Grok, etc. de forma unificada y elegante.

Instalación

Ejecutar los siguientes comandos en el proyecto Laravel:

composer require laravel/ai

Publicar la configuración y las migraciones:


php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

php artisan migrate

Las migraciones crean tablas para guardar historial de conversaciones.

Configuración (.env)

Agrega las claves API en el fichero ".env":

GEMINI_API_KEY=AIzaSy...                    # Para Gemini
OPENAI_API_KEY=sk-...                       # Si usas OpenAI
ANTHROPIC_API_KEY=sk-ant-...                # Claude
XAI_API_KEY=...                             # Grok

Crear el primer "Agent"

Un "Agent" es como un "asistente inteligente" con personalidad e instrucciones:

php artisan make:agent AsistenteBasico

El comando anterior crea el archivo en "app/Ai/Agents/AsistenteBasico.php":

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class AsistenteBasico implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return "Eres un asistente útil, amigable y experto en Laravel. 
                Responde siempre en español de forma clara y con ejemplos cuando sea posible.";
    }

    // Opcional: Forzar un proveedor específico
    public function provider(): string
    {
        return 'gemini';        // gemini, openai, anthropic, etc.
    }
}

Uso Básico en un Controlador

namespace App\Http\Controllers;

use App\Ai\Agents\AsistenteBasico;
use Illuminate\Http\Request;

class AiController extends Controller
{
    public function preguntar(Request $request)
    {
        $request->validate([
            'mensaje' => 'required|string|max:2000',
        ]);

        $respuesta = (new AsistenteBasico())
            ->model('gemini-2.5-flash')     // gemini-2.5-pro, gpt-4o-mini, etc.
            ->prompt($request->mensaje);

        return response()->json([
            'respuesta' => (string) $respuesta
        ]);
    }
}

Crear la Ruta

// routes/web.php o api.php
use App\Http\Controllers\AiController;

Route::post('/ai/preguntar', [AiController::class, 'preguntar']);

Probar con Postman o un formulario:json:

{
    "mensaje": "¿Cómo se crea un modelo en Laravel?"
}

Otras Funciones Básicas Útiles

Streaming (respuesta en tiempo real):

return (new AsistenteBasico())
    ->model('gemini-2.5-flash')
    ->stream($request->mensaje);

Cambiar modelo fácilmente:
```
->model('gemini-2.5-pro')
```

Con historial de conversación (memoria):

$respuesta = (new AsistenteBasico())
    ->conversation($idConversacion)   // ID de la tabla agent_conversations
    ->prompt($mensaje);

Generar imagen (básico):

$imagen = \Laravel\Ai\Image::of('Un logo moderno para una app de tareas con colores azul y blanco')
    ->provider('gemini')
    ->generate();