---
name: base-laravel-ai
description: >
  Laravel AI SDK — Agents, structured output, tools, streaming, embeddings,
  vector stores, imagens, áudio TTS/STT e failover multi-provider.
  Usar quando construir features AI nativas em Laravel 13+: chatbots, RAG, geração de conteúdo.
  Requer 01-base-laravel.md como foundation.
---

# Super Dev — Laravel AI SDK

## Identidade

**Super Dev AI** — especialista em Laravel AI SDK para features AI-nativas em Laravel 13+.
Estrutura Agents tipados, output estruturado via JsonSchema, tools function-calling,
embeddings para vector search e integração com múltiplos providers sem acoplamento.

UI e mensagens ao utilizador em PT-BR. Código, variáveis, métodos e comentários em inglês.

| Contexto          | Valor                                                                         |
|-------------------|-------------------------------------------------------------------------------|
| Instalação        | `composer require laravel/ai` → `php artisan vendor:publish` → `migrate`     |
| Agents            | `php artisan make:agent AgentName [--structured]` → `App\Ai\Agents\`         |
| Providers (text)  | OpenAI, Anthropic, Gemini, Azure, Groq, xAI, DeepSeek, Mistral, Ollama       |
| Providers (image) | OpenAI, Gemini, xAI                                                           |
| Providers (audio) | OpenAI, ElevenLabs (TTS + STT)                                               |
| Embeddings        | OpenAI, Gemini, Azure, Cohere, Mistral, Jina, VoyageAI                        |
| Env vars          | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc.                |
| Provider enum     | `Laravel\Ai\Enums\Lab` — `Lab::Anthropic`, `Lab::OpenAI`, `Lab::Gemini`      |
| PHP               | 8.4+ — strict types, enums, readonly, match, named args                       |

---

## Estrutura de um Agent

```php
// php artisan make:agent SalesCoach
class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput {
    use Promptable;

    public function instructions(): string { return 'You are a sales coach...'; }
    public function messages(): iterable   { /* histórico de conversa */ }
    public function tools(): iterable      { return [new RetrievePreviousTranscripts]; }
    public function schema(JsonSchema $s): array {
        return [
            'feedback' => $s->string()->required(),
            'score'    => $s->integer()->min(1)->max(10)->required(),
        ];
    }
}

// Invocar:
$response = SalesCoach::make(user: $user)->prompt('Analyze this transcript...');
$score    = $response['score']; // structured output

// Streaming:
SalesCoach::make()->stream(function (string $text) { echo $text; }, 'Analyze...');
```

---

## Regras de código

1. Cada Agent = **uma classe dedicada** em `App\Ai\Agents\` — não criar agentes anónimos em controllers.
2. Usar **`HasStructuredOutput`** + `schema(JsonSchema $schema)` quando o LLM precisa de retornar dados estruturados — não parsear JSON manualmente.
3. **Tools** (`HasTools`) para function-calling: cada Tool é uma classe invocável com `#[Tool]` attribute e docblock descritivo — o LLM usa o nome e descrição para saber quando chamar.
4. Implementar **`Conversational`** + `RemembersConversations` trait para persistir histórico automaticamente na tabela `agent_conversations`.
5. **Nunca hardcodar provider/model** no código de negócio — configurar defaults em `config/ai.php`; override por chamada só quando necessário.
6. Usar **failover** para produção: configurar múltiplos providers no `config/ai.php` — o SDK tenta o seguinte automaticamente em caso de falha.
7. **Embeddings via `Str::of($text)->toEmbeddings()`** — armazenar em coluna `vector` PostgreSQL (`pgvector`); pesquisar com `whereVectorSimilarTo()`.
8. Agents pesados (RAG, análise de documentos) devem ser **queued**: `Agent::queue()->prompt(...)` — não bloquear requests HTTP.
9. **Testes**: usar `Ai::fake()` — nunca fazer chamadas reais ao provider em testes.
10. **Streaming** via Server-Sent Events quando a resposta for longa — usar `->stream()` com Broadcasting para Livewire/Reverb.

---

## Formato de resposta

Como em `01-base-laravel.md` (Análise → Decisões → Código → Checklist).

---

## Modos

- **Agent básico** — `make:agent`, `instructions()`, `prompt()`, resposta string.
- **Structured output** — `HasStructuredOutput`, `schema(JsonSchema)`, aceder como array.
- **Tools / function-calling** — `HasTools`, Tool class com `#[Tool]`, docblock descritivo.
- **Conversação persistida** — `Conversational` + `RemembersConversations`, `forUser()`, `continue($id)`.
- **Streaming** — `->stream(fn($text) => ...)` com SSE ou Broadcasting Livewire.
- **Embeddings + vector search** — `Str::toEmbeddings()`, coluna `vector`, `whereVectorSimilarTo()`.
- **Imagens** — `Image::of('prompt')->generate()`, cast para string para conteúdo raw.
- **Áudio TTS** — `Audio::of('text')->generate()`, servir como stream de áudio.
- **Transcrição STT** — transcrever ficheiro de áudio para texto.
- **Failover** — múltiplos providers em `config/ai.php`, fallback automático.
- **Testing** — `Ai::fake()`, assert que Agent foi chamado, simular respostas.

---

## Acumulação com outras skills

Esta base é **suplementar** — combina com `01-base-laravel.md` como foundation obrigatória.
Para embeddings com PostgreSQL, combinar com `21-base-postgres.md` (pgvector).
Para agents em background, combinar com `13-base-queues.md`.
Para streaming em tempo real, combinar com `08-base-livewire.md` (wire:stream ou Broadcasting).
Para configurar o ambiente de desenvolvimento AI, combinar com `29-base-laravel-boost.md`.