> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Driver Amazon Bedrock per Laravel AI SDK

> Driver Amazon Bedrock per Laravel AI SDK. Supporta generazione di testo, streaming, uso di strumenti, output strutturato, allegati di file, cronologia conversazioni, embedding, generazione di immagini, audio (TTS) e reranking.

## Panoramica

[revolution/laravel-amazon-bedrock](https://github.com/invokable/laravel-amazon-bedrock) è un driver per usare Amazon Bedrock con [Laravel AI SDK](https://laravel.com/docs/ai-sdk). Ti permette di gestire più modelli di Bedrock tramite l'API unificata di Laravel AI SDK.

| Funzionalità                        | Utilizzabile solo con Bedrock API key | Modelli / servizi supportati                                                                                         |
| ----------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Generazione di testo / streaming    | ✅                                     | Anthropic Claude, Amazon Nova e la maggior parte degli altri modelli Bedrock (tutti tramite Converse API)            |
| Uso di strumenti (Function Calling) | ✅                                     |                                                                                                                      |
| Output strutturato                  | ✅                                     |                                                                                                                      |
| Allegati di file                    | ✅                                     | Immagini, documenti, audio e video allegati tramite Converse API (i formati supportati variano da modello a modello) |
| Generazione di immagini             | ✅                                     | Stability AI (predefinito), Amazon Nova Canvas (deprecato)                                                           |
| Audio (TTS)                         | ⚠️                                    | Amazon Polly (motori generative / neural / long-form / standard)                                                     |
| Trascrizione (STT)                  | ❌                                     | Non supportata                                                                                                       |
| Embedding                           | ✅                                     | Amazon Titan Embeddings V2 (predefinito), Cohere Embed English/Multilingual V3, Cohere Embed V4 (batch)              |
| Reranking                           | ⚠️                                    | Cohere Rerank 3.5, Amazon Rerank 1.0                                                                                 |
| File                                | ✅                                     | Nella generazione di testo è supportato l'allegato di file locali. Upload sul server e `fromId()` non supportati     |

<Info>
  Il simbolo `⚠️` in tabella non significa "funzionalità non supportata" ma "non utilizzabile con la sola Bedrock API key".
</Info>

<Info>
  Laravel AI SDK v0.6.3 ha aggiunto il supporto ufficiale per Text, Image ed Embeddings usando le Bedrock API key. Questo pacchetto continua a essere pubblicato perché supporta anche funzionalità non disponibili nell'integrazione ufficiale, come l'audio (TTS) con Amazon Polly e il reranking.
</Info>

Le caratteristiche principali sono le seguenti.

* **Autenticazione**: puoi scegliere tra Bedrock API key, credenziali AWS IAM (SigV4) e la catena di credenziali AWS predefinita (ruoli IAM, instance profile, ecc.).
* **Failover**: supporta il failover multi-provider dell'AI SDK. Rate limiting (429), sovraccarico (503, 529) ed errori legati al credito vengono mappati su eccezioni gestibili con failover.
* **Controllo della cache**: la cache ephemeral è sempre attiva sui system prompt della [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html).
* **API unificata**: tutti i modelli, come Anthropic Claude, Amazon Nova, Meta Llama e Mistral, sono gestibili tramite Bedrock Converse API con un'interfaccia uniforme.

## Requisiti

* PHP >= 8.3
* Laravel >= 12.x

## Installazione

<Steps>
  <Step title="Installa il pacchetto">
    ```bash theme={null}
    composer require revolution/laravel-amazon-bedrock
    ```
  </Step>

  <Step title="Pubblica la configurazione dell'AI SDK">
    ```bash theme={null}
    php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
    ```
  </Step>
</Steps>

## Configurazione

Aggiungi il provider `amazon-bedrock` in `config/ai.php`. Se necessario, imposta Bedrock anche come provider predefinito.

```php theme={null}
'default' => 'amazon-bedrock',
'default_for_images' => 'amazon-bedrock',
'default_for_audio' => 'amazon-bedrock',
'default_for_embeddings' => 'amazon-bedrock',
'default_for_reranking' => 'amazon-bedrock',
```

### Opzione 1: Bedrock API key

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'key'    => env('AWS_BEDROCK_API_KEY', ''),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_BEDROCK_API_KEY=your_api_key
AWS_DEFAULT_REGION=us-east-1
```

La Bedrock API key si ottiene dalla console di gestione AWS.

<Warning>
  La Bedrock API key è utilizzabile solo con la Bedrock Runtime API. Non è utilizzabile per il reranking o per Amazon Polly (TTS), che usano `bedrock-agent-runtime`. Per queste funzionalità usa SigV4 o la catena di credenziali AWS predefinita.
</Warning>

### Opzione 2: credenziali AWS IAM (SigV4)

Usa la chiave di accesso e la chiave segreta AWS con firma [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'token'  => env('AWS_SESSION_TOKEN'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=wJalr...
AWS_SESSION_TOKEN= # opzionale (per credenziali temporanee STS)
AWS_DEFAULT_REGION=us-east-1
```

<Info>
  Imposta `AWS_SESSION_TOKEN` solo se stai usando credenziali temporanee (STS).
</Info>

### Opzione 3: catena di credenziali AWS predefinita (ruoli IAM)

In ambienti con ruoli IAM (EC2 / ECS / Lambda), puoi omettere `key` e `secret` e usare la [catena di provider di credenziali AWS predefinita](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).

```php theme={null}
'providers' => [
    'amazon-bedrock' => [
        'driver' => 'amazon-bedrock',
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    ],
],
```

```dotenv theme={null}
AWS_DEFAULT_REGION=us-east-1
```

La catena di credenziali predefinita risolve automaticamente da variabili d'ambiente, file di credenziali condivise (`~/.aws/credentials`), ruoli di attività ECS, instance profile EC2 e altro.

### Chiavi di configurazione opzionali

| Chiave                         | Descrizione                                   | Valore predefinito                                |
| ------------------------------ | --------------------------------------------- | ------------------------------------------------- |
| `secret`                       | AWS secret access key (SigV4)                 | —                                                 |
| `token`                        | AWS session token (SigV4)                     | —                                                 |
| `timeout`                      | Timeout richiesta HTTP (secondi)              | 30                                                |
| `max_tokens`                   | max tokens predefinito per richiesta          | 8096                                              |
| `models.text.default`          | Modello di testo predefinito                  | `global.anthropic.claude-sonnet-4-6`              |
| `models.text.cheapest`         | Modello di testo più economico                | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
| `models.text.smartest`         | Modello di testo più performante              | `global.anthropic.claude-opus-4-7`                |
| `models.embeddings.default`    | Modello di embedding predefinito              | `amazon.titan-embed-text-v2:0`                    |
| `models.embeddings.dimensions` | Numero di dimensioni di embedding predefinito | `1024`                                            |
| `models.image.default`         | Modello di immagine predefinito               | `stability.stable-image-core-v1:1`                |
| `models.audio.default`         | Motore audio (TTS) predefinito                | `generative`                                      |
| `models.reranking.default`     | Modello di reranking predefinito              | `cohere.rerank-v3-5:0`                            |

## Generazione di testo

### Classe Agent

Crea una classe Agent con un comando Artisan.

```bash theme={null}
php artisan make:agent BedrockAgent
```

```php theme={null}
<?php

namespace App\Ai\Agents;

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

class BedrockAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Sei un esperto di sviluppo software.';
    }
}
```

```php theme={null}
use App\Ai\Agents\BedrockAgent;

$response = (new BedrockAgent)->prompt('Parlami di Laravel.');

echo $response->text;
```

### Agent anonimo

Se vuoi usare l'SDK rapidamente senza creare una classe, usa l'helper `agent()`.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Sei un esperto di sviluppo software.',
)->prompt('Parlami di Laravel.');

echo $response->text;
```

### Streaming

```php theme={null}
use App\Ai\Agents\BedrockAgent;
use Illuminate\Support\Facades\Route;

Route::get('/stream', function () {
    return (new BedrockAgent)->stream('Parlami di Laravel.');
});
```

Puoi anche gestire manualmente gli eventi.

```php theme={null}
use Laravel\Ai\Streaming\Events\TextDelta;

use function Laravel\Ai\agent;

$stream = agent(
    instructions: 'Sei un esperto di sviluppo software.',
)->stream('Parlami di Laravel.');

foreach ($stream as $event) {
    if ($event instanceof TextDelta) {
        echo $event->delta;
    }
}
```

### Uso di strumenti (Function Calling)

Definisci gli strumenti da invocare durante la generazione.

```php theme={null}
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class GetWeather implements Tool
{
    public function description(): string
    {
        return 'Restituisce il meteo attuale di una città.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'city' => $schema->string()->required()->description('Nome della città'),
        ];
    }

    public function handle(Request $request): string
    {
        // Qui invochi l'API del meteo
        return json_encode(['temperature' => 22, 'condition' => 'sunny']);
    }
}
```

Utilizzalo dall'Agent.

```php theme={null}
use App\Ai\Tools\GetWeather;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[MaxSteps(5)]
class WeatherAgent implements Agent, HasTools
{
    use Promptable;

    public function tools(): array
    {
        return [new GetWeather];
    }

    public function instructions(): string
    {
        return 'Sei un assistente meteo.';
    }
}

$response = (new WeatherAgent)->prompt('Che tempo fa a Tokyo?');
echo $response->text;
```

Funziona anche con un Agent anonimo.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Sei un assistente meteo.',
    tools: [new GetWeather],
    maxSteps: 5,
)->prompt('Che tempo fa a Tokyo?');
```

Le chiamate di strumento funzionano anche in streaming. L'SDK esegue automaticamente lo strumento e continua la conversazione finché non produce una risposta testuale finale.

### Allegati di file

Con il parametro `attachments` puoi allegare a un prompt immagini, documenti, audio e video. La Bedrock Converse API gestisce i blocchi allegati, ma quali formati siano effettivamente utilizzabili dipende dal modello (ad esempio, Anthropic Claude supporta solo immagini e documenti).

```php theme={null}
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

use function Laravel\Ai\agent;

// Allega un'immagine da percorso locale
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Descrivi questa immagine.', attachments: [
    Image::fromPath('/path/to/photo.jpg'),
]);

// Allega un documento tramite URL
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Riassumi questo documento.', attachments: [
    Document::fromUrl('https://example.com/report.pdf'),
]);

// Allega da stringa (specificando esplicitamente il formato)
$response = agent(
    instructions: 'Sei un assistente utile.',
)->prompt('Analizza questo testo.', attachments: [
    Document::fromString($csvContent, 'text/csv')->as('data.csv'),
]);
```

I tipi di allegato supportati sono `Image`, `Document` e `Audio` in `Laravel\Ai\Files\*`. I video si possono allegare tramite `Illuminate\Http\UploadedFile`.

<Info>
  L'upload di file lato server (`Document::fromPath()->put()`) e il riutilizzo tramite ID (`Document::fromId()`) non sono supportati da Bedrock.
</Info>

### Cronologia conversazioni

Per mantenere conversazioni multi-turno, implementa l'interfaccia `Conversational` nella classe Agent. Restituendo i messaggi passati da `messages()`, verranno inclusi automaticamente in ogni prompt.

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Models\ChatHistory;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;

class ChatAgent implements Agent, Conversational
{
    use Promptable;

    public function __construct(public int $userId) {}

    public function instructions(): string
    {
        return 'Sei un assistente utile.';
    }

    public function messages(): iterable
    {
        return ChatHistory::where('user_id', $this->userId)
            ->latest()
            ->limit(20)
            ->get()
            ->reverse()
            ->map(fn ($m) => new Message($m->role, $m->content))
            ->all();
    }
}
```

```php theme={null}
$response = (new ChatAgent(auth()->id()))->prompt('Di cosa stavamo parlando l\'ultima volta?');
```

#### Salvataggio automatico con `RemembersConversations`

Se non vuoi implementare `messages()` da solo, puoi usare il trait `RemembersConversations` per un salvataggio conversazioni completamente automatico. Sono necessarie le tabelle del database dell'AI SDK, quindi esegui prima `php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" && php artisan migrate`.

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Promptable;

class ChatAgent implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'Sei un assistente utile.';
    }
}
```

Avvia una nuova conversazione.

```php theme={null}
$response = (new ChatAgent)->forUser($user)->prompt('Ciao!');

$conversationId = $response->conversationId;
```

Continua una conversazione esistente.

```php theme={null}
$response = (new ChatAgent)
    ->continue($conversationId, as: $user)
    ->prompt('Dimmi di più.');
```

Il driver Bedrock include automaticamente la cronologia della conversazione nelle richieste Bedrock Converse API, così puoi sfruttare il contesto multi-turno con tutti i modelli supportati.

### Output strutturato

Implementando l'interfaccia `HasStructuredOutput` puoi ottenere risposte tipizzate.

```php theme={null}
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;

class ExtractPerson implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'Estrai le informazioni sulla persona dal testo fornito.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'name' => $schema->string()->description('Nome completo della persona'),
            'age' => $schema->integer()->description('Età'),
            'occupation' => $schema->string()->description('Professione'),
        ];
    }
}

$response = (new ExtractPerson)->prompt('John è un ingegnere del software di 30 anni.');

echo $response['name'];       // "John"
echo $response['age'];        // 30
echo $response['occupation']; // "software engineer"
```

L'output strutturato è disponibile anche con Agent anonimi.

```php theme={null}
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'Estrai le informazioni sulla persona dal testo fornito.',
    schema: fn (JsonSchema $schema) => [
        'name' => $schema->string()->description('Nome completo della persona'),
        'age' => $schema->integer()->description('Età'),
    ],
)->prompt('Alice is 25 years old.');

echo $response['name']; // "Alice"
echo $response['age'];  // 25
```

Internamente viene creato uno strumento sintetico (`output_structured_data`) che forza a restituire valori conformi allo schema. Questo approccio è compatibile con tutti i modelli su Bedrock tramite Converse API.

### Converse API (tutti i modelli)

Tutta la generazione di testo e lo streaming vengono eseguiti tramite la [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html). È tutto unificato, incluso Anthropic Claude, e puoi usare con la stessa interfaccia i vari modelli disponibili su Bedrock come Amazon Nova, Meta Llama, Mistral, Cohere e DeepSeek.

```php theme={null}
use function Laravel\Ai\agent;

// Anthropic Claude (tramite Converse API)
$response = agent(
    instructions: 'Sei un esperto di sviluppo software.',
    model: 'global.anthropic.claude-sonnet-4-6',
)->prompt('Parlami di Laravel.');

// Amazon Nova
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'amazon.nova-pro-v1:0',
)->prompt('Parlami di AWS.');

// Meta Llama
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'meta.llama3-1-70b-instruct-v1:0',
)->prompt('Spiegami il quantum computing.');

// Mistral
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'mistral.mistral-large-2402-v1:0',
)->prompt('Scrivi un haiku sulla programmazione.');

// Cohere Command R+
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'cohere.command-r-plus-v1:0',
)->prompt('Riassumi questo testo.');

// DeepSeek R1
$response = agent(
    instructions: 'Sei un assistente utile.',
    model: 'deepseek.r1-v1:0',
)->prompt('Risolvi questo problema di matematica.');
```

Streaming, uso di strumenti, output strutturato e allegati di file funzionano con i modelli che li supportano. Per maggiori dettagli consulta l'[elenco dei modelli supportati da Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html).

### Provider Options

Per passare opzioni specifiche di Bedrock come `anthropic_version`, implementa `HasProviderOptions`.

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class BedrockAgent implements Agent, HasProviderOptions
{
    use Promptable;

    public function instructions(): string
    {
        return 'Sei un esperto di sviluppo software.';
    }

    public function providerOptions(Lab|string $provider): array
    {
        return [
            'top_p' => 0.9,
        ];
    }
}
```

Provider Options supportate:

| Opzione                        | Descrizione                                           | Valore predefinito |
| ------------------------------ | ----------------------------------------------------- | ------------------ |
| `top_k`                        | Parametro di sampling Top-K                           | —                  |
| `top_p`                        | Parametro di sampling Top-P (nucleus)                 | —                  |
| `additionalModelRequestFields` | Parametri aggiuntivi specifici del modello (Converse) | —                  |

### Attributi di configurazione dell'Agent

Puoi impostare le opzioni di generazione del testo tramite attributi PHP.

```php theme={null}
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
class BedrockAgent implements Agent
{
    use Promptable;

    // ...
}
```

## Generazione di immagini

Genera immagini con i modelli Stability AI (predefiniti) o con Amazon Nova Canvas.

```php theme={null}
use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

// Per impostazione predefinita usa Stability AI Stable Image Core
$response = Image::of('Un simpatico robot steampunk')->generate(provider: Bedrock::KEY);

// Ottieni la prima immagine
$image = $response->firstImage();

// Salva su disco
$response->store('images', 's3');

// Emetti come tag HTML <img>
echo $response->toHtml('robot steampunk');
```

Modelli Stability AI disponibili (tutti richiedono la regione `us-west-2`):

```php theme={null}
// Stable Image Core — veloce, costo ridotto (predefinito)
$response = Image::of('paesaggio')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-core-v1:1');

// Stable Diffusion 3.5 Large — alta qualità, generazione massiva
$response = Image::of('ritratto')
    ->generate(provider: Bedrock::KEY, model: 'stability.sd3-5-large-v1:0');

// Stable Image Ultra — ultra-realistico, massima qualità
$response = Image::of('prodotto premium')
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-ultra-v1:1');
```

<Info>
  I modelli di immagine Stability AI sono disponibili solo in `us-west-2`. Quando usi questi modelli, imposta `AWS_DEFAULT_REGION=us-west-2`.
</Info>

### Editing di immagini con Stability AI

Anche i modelli di editing di Stability AI Image Services sono utilizzabili tramite il metodo `attachments()`. Passi un'immagine di input e la trasformi con un modello di editing.

```php theme={null}
use Laravel\Ai\Files\Image as ImageFile;
use Laravel\Ai\Image;
use Revolution\Amazon\Bedrock\Bedrock;

$inputImage = ImageFile::fromPath('/path/to/photo.jpg');

// Inpaint — sostituzione di aree tramite maschera o canale alpha
$response = Image::of('sostituisci lo sfondo con una foresta')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-inpaint-v1:0');

// Erase — rimuovi elementi indesiderati
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-erase-object-v1:0');

// Rimuovi lo sfondo e ritaglia solo il soggetto
$response = Image::of('')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-remove-background-v1:0');

// Search and Replace — sostituisci l'oggetto indicato nel prompt
$response = Image::of('gatto')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-image-search-replace-v1:0');

// Style Transfer — applica lo stile indicato nel prompt
$response = Image::of('stile pittura a olio')
    ->attachments([$inputImage])
    ->generate(provider: Bedrock::KEY, model: 'stability.stable-style-transfer-v1:0');
```

Modelli di editing Stability AI disponibili (tutti in `us-east-1`, `us-east-2`, `us-west-2`):

| Model ID                                        | Descrizione                                                   |
| ----------------------------------------------- | ------------------------------------------------------------- |
| `stability.stable-image-inpaint-v1:0`           | Inpaint — sostituzione dell'area selezionata                  |
| `stability.stable-outpaint-v1:0`                | Outpaint — espande l'immagine oltre i bordi                   |
| `stability.stable-image-erase-object-v1:0`      | Erase — elimina oggetti                                       |
| `stability.stable-image-remove-background-v1:0` | Rimozione dello sfondo                                        |
| `stability.stable-image-search-replace-v1:0`    | Search and Replace — sostituzione di oggetti                  |
| `stability.stable-image-search-recolor-v1:0`    | Search and Recolor — ricolorazione di oggetti                 |
| `stability.stable-image-style-guide-v1:0`       | Style Guide — applica uno stile da un'immagine di riferimento |
| `stability.stable-style-transfer-v1:0`          | Style Transfer — trasferimento di stile artistico             |
| `stability.stable-image-control-sketch-v1:0`    | Control Sketch — generazione a partire da uno schizzo         |
| `stability.stable-image-control-structure-v1:0` | Control Structure — generazione seguendo una struttura        |
| `stability.stable-creative-upscale-v1:0`        | Creative Upscale — upscaling con integrazione creativa        |
| `stability.stable-conservative-upscale-v1:0`    | Conservative Upscale — preserva i dettagli                    |
| `stability.stable-fast-upscale-v1:0`            | Fast Upscale — upscaling 4x leggero                           |

È supportato anche Amazon Nova Canvas, che però AWS sta progressivamente deprecando.

```php theme={null}
// Nova Canvas (deprecato. Disponibile in us-east-1, ap-northeast-1, eu-west-1)
$response = Image::of('tramonto')
    ->size('3:2')           // '1:1', '3:2', '2:3'
    ->quality('high')       // 'low', 'medium', 'high' (solo Nova Canvas)
    ->generate(provider: Bedrock::KEY, model: 'amazon.nova-canvas-v1:0');
```

## Audio (TTS)

Genera audio da testo con [Amazon Polly](https://docs.aws.amazon.com/polly/latest/dg/what-is.html).

```php theme={null}
use Laravel\Ai\Audio;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Audio::of('Adoro programmare con Laravel.')->generate(provider: Bedrock::KEY);

$rawContent = (string) $response;
```

Puoi specificare una voce maschile o femminile.

```php theme={null}
$response = Audio::of('Adoro programmare con Laravel.')
    ->female()
    ->generate(provider: 'bedrock');

$response = Audio::of('Adoro programmare con Laravel.')
    ->male()
    ->generate(provider: Bedrock::KEY);
```

Puoi specificare una [voce Polly](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html) specifica.

```php theme={null}
$response = Audio::of('Adoro programmare con Laravel.')
    ->voice('Joanna')
    ->generate(provider: Bedrock::KEY);
```

Salva l'audio generato.

```php theme={null}
$response = Audio::of('Adoro programmare con Laravel.')->generate(provider: Bedrock::KEY);

$path = $response->store();
$path = $response->storeAs('audio.mp3');
```

Puoi anche specificare il motore (modello).

```php theme={null}
// generative (predefinito), neural, long-form, standard
$response = Audio::of('Adoro programmare con Laravel.')
    ->generate(provider: Bedrock::KEY, model: 'neural');
```

**Voci predefinite:** `default-female` → Ruth, `default-male` → Matthew (entrambe supportano il motore generative).

<Warning>
  Amazon Polly è un servizio AWS distinto da Bedrock. La Bedrock API key (bearer token) non funziona con Polly. Usa le credenziali AWS IAM (SigV4) o la catena di credenziali AWS predefinita.
</Warning>

## Embedding

Genera embedding vettoriali con Amazon Titan Embeddings V2.

```php theme={null}
use Laravel\Ai\Embeddings;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Embeddings::for(['Hello world', 'Foo bar'])->generate(provider: Bedrock::KEY);

// Primo vettore di embedding
$vector = $response->first();

// Itera tutti gli embedding
foreach ($response as $embedding) {
    // $embedding è un array di float
}

echo $response->tokens; // Totale dei token
```

Puoi specificare il numero di dimensioni (Titan Embeddings V2 supporta 256, 512, 1024).

```php theme={null}
$response = Embeddings::for(['Hello world'])->dimensions(512)->generate(provider: Bedrock::KEY);
```

Esempio con modello personalizzato.

```php theme={null}
$response = Embeddings::for(['Hello world'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'amazon.titan-embed-text-v2:0');
```

### Modelli Cohere Embed

I modelli Cohere Embed vengono rilevati automaticamente e usano l'API batch. Mentre Titan invia una richiesta HTTP per ogni input, Cohere raggruppa tutti gli input in una sola richiesta, risultando più efficiente quando si elaborano più testi.

```php theme={null}
// Cohere Embed English V3
$response = Embeddings::for(['Hello world', 'Foo bar'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-english-v3');

// Cohere Embed Multilingual V3
$response = Embeddings::for(['Hello', 'こんにちは'])
    ->dimensions(1024)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-multilingual-v3');

// Cohere Embed V4 (dimensioni di output configurabili da 256 a 1536)
$response = Embeddings::for(['Hello world'])
    ->dimensions(512)
    ->generate(provider: Bedrock::KEY, model: 'cohere.embed-v4');
```

<Info>
  I modelli Cohere Embed non restituiscono il numero di token, quindi `$response->tokens` è sempre `0`.
</Info>

## Reranking

Usa Cohere Rerank 3.5 o Amazon Rerank 1.0 per riordinare i documenti in base alla rilevanza rispetto a una query.

```php theme={null}
use Laravel\Ai\Reranking;
use Revolution\Amazon\Bedrock\Bedrock;

$response = Reranking::of([
    'Laravel è un framework web per PHP.',
    'Python è un linguaggio di programmazione.',
    'Laravel offre una sintassi elegante per lo sviluppo web.',
])->rerank(query: 'Cos\'è Laravel?', provider: Bedrock::KEY);

// Documento più rilevante
echo $response->first()->document;
echo $response->first()->score;

// Ottieni tutto in ordine
foreach ($response as $result) {
    echo "{$result->index}: {$result->document} ({$result->score})\n";
}

// Limita il numero di risultati
$response = Reranking::of([...])
    ->limit(2)
    ->rerank(query: 'Cos\'è Laravel?', provider: Bedrock::KEY);
```

Esempio con modello personalizzato.

```php theme={null}
$response = Reranking::of([...])
    ->rerank(query: 'query di ricerca', provider: Bedrock::KEY, model: 'amazon.rerank-v1:0');
```

<Info>
  L'API di reranking utilizza l'endpoint `bedrock-agent-runtime` (non `bedrock-runtime`). Amazon Rerank 1.0 non è disponibile in `us-east-1`, quindi in quella regione usa Cohere Rerank 3.5.
</Info>

## Testing

Puoi usare direttamente le funzionalità di test standard di AI SDK.

Non è documentato ufficialmente, ma gli Agent anonimi creati con l'helper `agent()` possono essere mockati con `AnonymousAgent::fake()` e la variante con output strutturato con `StructuredAnonymousAgent::fake()`.

```php theme={null}
use Laravel\Ai\AnonymousAgent;
use Laravel\Ai\Prompts\AgentPrompt;

use function Laravel\Ai\agent;

it('can generate text', function () {
    AnonymousAgent::fake();

    $response = agent(
        instructions: 'Sei un esperto di sviluppo software.',
    )->prompt('Parlami di Laravel.');

    AnonymousAgent::assertPrompted(function (AgentPrompt $prompt) {
        return $prompt->contains('Laravel');
    });
});
```

<Info>
  Per le informazioni più aggiornate consulta la [repository su GitHub](https://github.com/invokable/laravel-amazon-bedrock).
</Info>


## Related topics

- [Tutorial per bot - Laravel Bluesky](/it/packages/laravel-bluesky/bot-tutorial.md)
- [Laravel AI SDK](/it/ai-sdk.md)
- [Creare un provider personalizzato per l'AI SDK](/it/advanced/ai-sdk-custom-provider.md)
- [Integrazione con Laravel AI SDK - VOICEVOX for Laravel](/it/packages/laravel-voicevox/ai-sdk.md)
- [Illuminate\Support\Manager — anatomia del sistema di driver](/it/advanced/manager.md)