Conecta un proveedor de IA

El kit incluye el SDK de Laravel AI (laravel/ai, versión 0.6.8) y un config/ai.php que ya nombra quince proveedores. Exactamente una función lo usa: la traducción automática detrás de php artisan lang:sync. Léelo para darle un proveedor a ese comando, para saber cuáles de las muchas llaves de config/ai.php hacen algo hoy en realidad, y para llamar a un modelo desde tu propio código sin cablear nada nuevo.

Qué está configurado

config/ai.php tiene tres partes.

Valores por omisión. Qué proveedor responde cuando una llamada no nombra uno, por tipo de trabajo. Son valores committeados, no variables de entorno; edita el archivo para cambiarlos.

Caché. caching.embeddings.cache es false; ponlo en true y el SDK guarda los embeddings generados en el almacén de caché que nombra caching.embeddings.store (CACHE_STORE, valor por omisión database).

Proveedores. Cada entrada empareja un driver con las variables de entorno que lo autentican. Poner una variable no hace nada por sí solo: un proveedor sólo se llama cuando es el valor por omisión para un tipo de trabajo o una llamada lo nombra.

Sólo OPENAI_API_KEY aparece en .env.example, vacía. Todas las demás variables las lee config/ai.php y nada más en el kit: disponibles, pero no conectadas a ninguna función. La entrada bedrock comparte AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY con el sistema de archivos S3, así que llenarlas para el almacenamiento de archivos también llena las credenciales de Bedrock, sin que nada llame a Bedrock.

config/services.php no guarda credenciales de IA: sus entradas son Mailgun, Postmark, Resend, SES, Telnyx, el servicio world de Weblabor, Stripe y Facebook.

Qué usa el kit hoy

Un solo camino, del comando a la red:

php artisan lang:sync
  → App\Services\LangSyncService
    → App\Services\LangTranslatorService::translate()
      → App\Ai\Agents\TranslationAgent::make(locale: $locale)->prompt($text, provider: config('ai.default'))

lang:sync recorre cada idioma en lang/ y, por cada llave que el inglés tiene y al idioma le falta, le pide una traducción al agente. Las instrucciones del agente le dicen al modelo que traduzca al idioma destino, conserve el significado y el tono, preserve los marcadores de posición y devuelva sólo el texto traducido. Antes de la llamada el servicio reemplaza cada marcador de Laravel como :name con una marca (__PH0__) y la restaura después, así que un marcador nunca puede volver traducido.

El proveedor es el que nombre default en config/ai.php, openai tal como se entrega. El modelo es el modelo de texto por omisión del proveedor, porque ni la configuración ni el agente nombran uno; para OpenAI en esta versión del SDK es gpt-5.4. Para elegir otro modelo sin tocar el agente, agrega un bloque models a la entrada del proveedor:

'openai' => [
    'driver' => 'openai',
    'key' => env('OPENAI_API_KEY'),
    'url' => env('OPENAI_URL', 'https://api.openai.com/v1'),
    'models' => [
        'text' => ['default' => 'gpt-4.1-mini'],
    ],
],

El comando decide si un proveedor está configurado antes de la primera llamada. El proveedor por omisión cuenta como configurado cuando su key está llena, o cuando su driver es ollama, que no necesita llave. De lo contrario cada llave faltante se escribe en inglés con la advertencia "AI translation provider is not configured", y el comando termina de todos modos: nada más en lang:sync depende de la red. Una llamada que falla o no devuelve nada se maneja igual, con la advertencia "Translation failed for", así que una llave mala o una cuota agotada te deja con texto en inglés para traducir a mano, nunca con un archivo roto.

Entonces, para encender la traducción con OpenAI:

OPENAI_API_KEY=sk-your-key

Para traducir con otro proveedor, pon su llave y cambia default en config/ai.php a su nombre, por ejemplo 'default' => 'anthropic'. Para traducir en local sin llave alguna, instala Ollama, descarga un modelo y pon 'default' => 'ollama'; el modelo por omisión ahí es llama3.1:8b, y OLLAMA_URL apunta el SDK a otro host.

El flujo completo de traducción, incluidos los idiomas que un usuario puede elegir y los demás comandos lang:*, está en /help/languages-and-translations.

Dos cosas más existen porque el SDK se instaló, y el kit no las usa:

• La migración 2026_05_15_155312_create_agent_conversations_table crea las tablas agent_conversations y agent_conversation_messages. Son el almacén de conversaciones del SDK, para agentes que recuerdan un chat. Ninguna función escribe en ellas.
• stubs/agent.stub, structured-agent.stub, agent-middleware.stub y tool.stub son las plantillas que usan make:agent, make:agent --structured, make:agent-middleware y make:tool.

Nada en el kit envía datos de usuarios, contenido ni prompts a ningún proveedor aparte de las cadenas de traducción de arriba, y sólo cuando corres lang:sync.

Llama a un proveedor desde tu propio código

No necesitas una librería cliente ni una clase de servicio. Genera un agente, dale instrucciones y hazle un prompt; el text de la respuesta es la respuesta del modelo.

php artisan make:agent SummaryAgent

<?php

namespace App\Ai\Agents;

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

class SummaryAgent implements Agent
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return 'Summarize the text you receive in one sentence. Return only the sentence.';
    }
}

$summary = SummaryAgent::make()->prompt('The long text to summarize...')->text;

Esa llamada usa el proveedor default y su modelo de texto por omisión. Para fijar un proveedor o un modelo, pásalos a prompt() o decláralos en la clase:

use Laravel\Ai\Attributes\{Model, Provider};
use Laravel\Ai\Enums\Lab;

#[Provider(Lab::Anthropic)]
#[Model('claude-sonnet-4-6')]
class SummaryAgent implements Agent
{
    // ...
}

// o por llamada
SummaryAgent::make()->prompt($text, provider: 'gemini', model: 'gemini-3-flash-preview');

Lab es el enum de los quince nombres de proveedor; una cadena simple con el mismo nombre también funciona. stream() devuelve la respuesta conforme se produce, queue() corre el prompt como un job. Para un prompt suelto sin clase, la función agent() construye un agente anónimo:

use function Laravel\Ai\agent;

$answer = agent('You answer in one word.')->prompt('What colour is the sky?')->text;

Las imágenes y los embeddings tienen sus propios puntos de entrada, enrutados a default_for_images y default_for_embeddings:

use Laravel\Ai\{Embeddings, Image};

$image = Image::of('A lighthouse at dusk')->square()->generate();
$vectors = Embeddings::for(['first text', 'second text'])->generate();

En una prueba, SummaryAgent::fake(['a canned answer']) reemplaza la red con las respuestas que listes, e Image::fake() y Embeddings::fake() hacen lo mismo con las suyas. php artisan agent:chat abre una conversación con uno de tus agentes en la terminal, que es la forma más rápida de comprobar que una llave funciona.

Sigue la forma del propio kit cuando agregues uno: mantén el agente en app/Ai/Agents, llámalo desde un método de modelo o un servicio y no desde un componente Livewire, y verifica la llave antes de la llamada como hace LangTranslatorService, para que un proveedor faltante se degrade a un mensaje y no a una excepción.